用途与定位 这个技能是终端内的 CLI 架构图编写流程。适用场景：你自己编写 JSON IR，或通过脚本化方式生成图表，不希望经过 agent。CLI 零依赖，可在干净的源码树上直接运行。产出是经原子化校验的自包含 HTML 文件，并附 JSON 回执，其中记录 spec 与产物的 SHA-256 和字节数。下文所有命令均在终端执行；面向 agent 的提示词另见 02-agent-chat-authoring.md。
准备 设置便捷变量（指向已安装的 skill 目录）：
export A=~/.claude/skills/archify
步骤 0：用 guide 选择图类型 node $A/bin/archify.mjs guide "Show an API request with Redis cache miss" 示例输出会给出推荐类型（如 API request chain [sequence]）、置信度、回答的问题、适用与不适用场景、必须包含的要素、展示形式及可复制提示词。支持机器可读与中文输出： node $A/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json node $A/bin/archify.mjs guide "CI/CD approval gate" --lang zh
步骤 1：只读取三个文件 针对选定的 <type>： cat $A/schemas/<type>.schema.json cat $A/schemas/common.schema.json ls $A/examples/ 从 examples 中选择一个同类 JSON 示例，只参考字段结构，不参考其内容。示例目录共有 19 项（含已渲染 HTML），如 agent-run.lifecycle.json、cache-miss-request.sequence.json、web-app.architecture.json 等。新工作流源使用 schema_version: 2；仅在需要保留旧几何时保留 1。
步骤 2：architecture schema 的三个常见陷阱
- 顶层键是 connections，而非 relationships；合法键包括 schema_version、diagram_type、meta、layout、components、boundaries、connections、cards；必填为 schema_version、diagram_type、meta、components。
- 未提供 layout 即自由摆放，此时每个 component 必须带 pos [x, y]；layout.mode 只接受 "grid"，加上 "layout": { "mode": "grid" } 后使用 row/col 即可。
- 标签宽于组件单元格会阻止校验通过（如 Label “Architecture renderer” (~139px) 宽于 120px 的组件），需要缩短标签或为该组件设置 size: [w, h]。默认单元格宽 120px。
步骤 3：每次修改后校验 node $A/bin/archify.mjs validate workflow candidate.json --quality showcase --json 验收标准：9 项 artifact 检查全部通过，0 errors，0 warnings。只有 4 项检查的回执属于基础校验，不是 showcase。若 meta.quality_profile 缺失或名称写错，先修正它再改几何。失败时 --json 返回稳定结构的 diagnostics[]。修复规则：只改诊断指向的 subject，对照 evidence，从 supportedFixes 中选一种，然后重新运行；若连续两轮客观错误数未减少则停止并如实报告，不要猜测。 工作流 v2 的几何诊断： node $A/bin/archify.mjs validate workflow candidate.json --layout-json 对 architecture，inspect 是该命令的别名： node $A/bin/archify.mjs inspect architecture candidate.json
步骤 4：交付产物 node $A/bin/archify.mjs deliver workflow candidate.json out/workflow.html --quality showcase --json 回执包含输入与输出路径、specification/artifact 的 sha256 与 bytes，以及 checksPassed、checkCount、compositionProfile、compositionStatus、errors、warnings。deliver 会将 spec 字节精确冻结为同目录快照，渲染并校验该快照，再原子替换目标 HTML；失败时保留旧文件，因此 deliver 失败后不要运行 visual-check，否则检查的是旧的正常产物。加 --open 可打开刚提交的文件；打开器出错不影响成功状态。
步骤 5：复检已有 HTML node $A/bin/archify.mjs check out/workflow.html 输出 JSON 含 9 项具名检查（single_svg、finite_svg、orthogonal_arrows、label_route_clearance、relationship_crossings、relationship_corridors、container_border_runs、route_rhythm、legend_clearance），并附 composition 实测指标（properCrossings、maxBends、maxStretch、minSegmentPx 等）与 suggestedLimits。通过返回 0，失败返回 1。
常用辅助命令 node $A/bin/archify.mjs render workflow candidate.json out/raw.html（裸渲染，不做校验，不用于验收） node $A/bin/archify.mjs brands postgres node $A/bin/archify.mjs brands "grafana" --json node $A/bin/archify.mjs brands capture "https://example.com" --json node $A/bin/archify.mjs demo /tmp/archify-demo brands 仅当节点确实是该产品时使用，不要从“database”等模糊角色推断品牌，徽章不能替代 type/label/关系。examples 会就地覆盖 $A/examples/ 下的 HTML；如需输出到别处，直接调用 node $A/scripts/render-examples.mjs /tmp/out。
退出码 0 成功；1 真实失败（schema/layout/artifact-check 失败、doctor 未就绪、visual-check 失败）；2 使用错误（未知命令、标志、图类型，在不支持的类型上用 --repo-root），以及因无 Chrome 而跳过 visual-check。2 在不同命令下含义不同：CI 脚本中先按命令分支，再按退出码分支，不要把所有非 0 合并处理。