用途
dym-archify-agent-chat-authoring 是 Archify 的主要使用路径：在 agent 的聊天框中用自然语言描述系统来绘制图表。用户描述系统后，agent 自行选择图表类型、按 schema 编写 JSON IR、运行 validate/deliver，最后返回 HTML 路径。
所有内容都输入到 agent 的聊天框，而不是终端；shell 命令位于 03-cli-authoring-loop.md，不要在两个文件之间交叉粘贴。
前置条件
技能已按 01-install-and-verify.md 安装，且 agent 具备运行 shell 的权限（agent 需要调用 node bin/archify.mjs）。
主要能力
- 从描述启动，无需仓库：例如
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. - 需要贴合真实代码的图表时，可打开仓库后提问，例如要求分析仓库并生成高层运行时架构图，展示 8–12 个核心组件、一条主路径、外部依赖与信任边界，并把辅助细节放进卡片而不是增加更多边。
- 明确指定图表类型（来自 SKILL.md 的 "Type router"）：
- architecture：组件、服务、云/安全边界、基础设施；提示中说明范围、核心组件、主路径。
- workflow：流程、审批门、工具调用、runbook、CI/CD；提示中说明参与者、顺序、分支、异常。
- sequence：API 调用链、请求生命周期、异步 trace、返回值；提示中说明调用方、被调用方、return、时机。
- dataflow：管道、ETL/ELT、lineage、数据治理、消费方；提示中说明来源、转换、仓库、边界。
- lifecycle：状态转换、重试、等待、终止状态；提示中说明状态、事件、重试/取消路径。
- 不确定时可直接询问，agent 会运行 guide 帮助选择。
- 逐轮小幅微调：Archify 保留已输入的 JSON 源，因此窄范围请求成本低且稳定，例如 add Redis、move auth to the left、highlight the rollback path、put the retry budget in a card instead of a new edge。
- 导入 Mermaid：Archify 不机械解析 Mermaid，而是由 agent 读取 Mermaid 获取拓扑后重新编写 Archify JSON。映射规则：flowchart / graph → workflow（若为组件地图则为 architecture）；sequenceDiagram → sequence；stateDiagram → lifecycle。
- 可选设置（仅在确实需要时说明）：make it showcase quality、use the signal-flow visual preset、enable trace animation for the demo、set the viewer UI language to zh-CN、add up to five guided story chapters。
使用方式
- 从描述启动，无需仓库。
- 已知所需类型时在提示中明确说明图表类型。
- 逐轮小幅微调。
- 需要时粘贴 Mermaid 进行转换。
- 需要时提出可选设置。
- 阅读 agent 返回内容，并识别其是否夸大。
- 探索生成的 artifact。
约束与规则
SKILL.md 中 agent 必须遵守、用户也应了解以避免反向要求的规则：
- 一条清晰主路径，分支从主路径上最近的节点分出，主节点最多约 12 个。
- 辅助细节放入卡片，不新增边。
- agent 只有在具体诊断要求时才可添加几何控制（via、channelX、channelY、labelAt），且每轮只修改一处。
- 关系标签是语义数据。删除标签不是修复几何碰撞的方式——agent 必须先移动标签、改变路由、拉开间距，最后才在保留语义的前提下精简文字。
meta.locale 只接受 en 或 zh-CN，且只改变 viewer 的 UI 部分（页面标题、Legend、错误消息、a11y、lang 属性），不翻译用户编写的内容。对于其他语言，agent 必须去掉 meta.locale 并说明 viewer UI 回退到英文。
输出与验证
根据 SKILL.md 的 "Output" 部分，agent 必须返回：已检查的 HTML 路径、图表类型、validate 摘要、spec/artifact 回执、浏览器证据状态，以及诚实的视觉审查状态。
三类声明相互独立，不应被合并：
- Artifact 通过确定性检查：由 deliver 证明（showcase profile 下 9 项 artifact 检查，0 错误 0 警告）；不能证明是否好看。
- 浏览器中的真实行为：由 visual-check 证明；不能证明美观。
- 视觉审查：由真人或能读取图像的 reviewer 完成。
agent 夸大的迹象，应立即制止：
- 只有 4 项 artifact 检查的回执却被称为 "showcase"。Showcase 必须满足全部 9 项检查、0 错误、0 警告。
- 退出码非 0 却仍被描述为成功——SKILL.md 明文禁止。
- 在无人打开 HTML 的情况下声称 "已用肉眼检查"。
探索 artifact
生成的 HTML 已内置快捷键，无需额外安装：
- 打开 Diagram Guide：?
- 查找并聚焦某个节点：/
- 探测一条有向路线：R
- 比较一个或两个角色：L
- 总览雷达：M
- 运行 story / 切换章节：P / [ ]
- 演示模式：F
- 切换 style / theme / 打开 Export：S / T / E
- 缩放 / 重置：+ / - / 0
稳定深链：#focus=<id>、#focus=<id>&reach=upstream|downstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind>、#view=<view-id>。
适用场景
适合在 agent 聊天框中用自然语言快速生成架构、流程、时序、数据流与生命周期类图表，尤其适合需要贴合真实代码仓库生成高层运行时架构图、或需要将 Mermaid 拓扑转换为 Archify 图表的场景。
限制
- 需先安装技能并让 agent 具备 shell 权限。
- 所有输入在 agent 聊天框，shell 命令在另一文件，不可交叉粘贴。
- meta.locale 仅支持 en 与 zh-CN，且只影响 viewer UI。
- 主节点数量、几何控制添加时机、标签处理等受 SKILL.md 规则约束。
- 关于收费、价格、平台支持范围等事实，资料暂未提供。