让 AI 画一张系统架构图，结果通常分两种：图能看，内容对不上代码库；内容对得上，框线挤成一团，没法放进正式文档。GitHub Trending 本周第三名的 archify（tt-a1i/archify）给这个问题一个工程化答案：单日新增 star 超过 4000，总量 2.2 万，它把「AI 画图」拆成三段——AI 写数据、程序画图、程序验图，前两段的产物必须全部通过机器验证才会出现在你面前。
这个项目当前版本 v2.16.0-dev.0，MIT 协议，README 里对自己定位的表述很克制：一个面向 Cursor、Claude Code、Codex CLI 和 OpenCode 的 Node.js 渲染与验证系统。下面按机制拆开看。
先拆问题：AI 画图错在哪
第一种失败是拓扑幻觉。让模型描述一个它没见过的系统，它会补全出并不存在的组件和连线；即便描述是对的，转成图的那一步仍可能增删节点。这类错误肉眼难以逐项核对，尤其图上一旦超过十几个框。
第二种失败是布局失控。通用自动布局算法把所有箭头堆到同一个中点，标签压在连线上，组件重叠。Mermaid 这类工具的渲染结果常被开发者形容为「能跑但不能见人」，放进方案文档需要手工重排。
这两类错误的共同点：生成过程没有验收环节。图是直接输出的终态，错了只能整体重画。
核心机制：类型化中间表示加确定性编译
Archify 的做法是把职责切开。AI 负责它擅长的部分：理解代码库或口头描述，产出一份带 schema 的类型化 JSON 中间表示（typed JSON IR），里面是节点、连线、分组、边界这些「事实」。程序负责其余部分：把这份 IR 确定性地编译成 HTML/SVG。
分工的边界划在「判断」和「执行」之间。README 里有一条明确的划分：布局判断力放在 agent 侧——层级、间距、路由走向、强调重点由模型决定；而「共享自动端点的确定性散开」放在程序侧——多条箭头汇聚时按确定规则分散到端点，不再堆叠在中点。同一个 IR 每次编译出的图是同一个样子，这一步不存在随机性。
交付前的五道验证关
IR 写完并不等于图生成了。Archify 的交付流程里有一组必须全过的检查：schema 校验、布局规则、HTML/SVG 渲染、路由检查、标签与连线的间距检查（label-to-route clearance）。全部通过后，产物才会以原子操作替换上一版输出；任何一关失败，旧图保持原样。
失败时的返回也有讲究。validate --json 和 deliver --json 返回的是机器可读的修复回执：稳定的规则代码、出问题的具体对象、测量得到的证据，以及仅限受支持操作的修复建议，而不是一段 Node 堆栈让 agent 猜着重试。
可选的 preview 模式对应桌面上的迭代场景：只绑定 127.0.0.1 的随机端口，监视唯一一个 JSON 源文件，保存后的候选版本通过全部检查才会刷新；保存不完整或校验失败时，屏幕上保留的是上一次验证通过的图。README 特别说明这是显式的桌面创作模式，不是后台常驻服务。
五种图，各自的提示词要点
| 类型 | 适用场景 | 提示词里写什么 |
|---|---|---|
| Architecture | 组件、服务、存储、信任边界 | 范围、核心组件、主路径 |
| Workflow | CI/CD、审批、工具调用、runbook | 参与者、顺序、分支、异常 |
| Sequence | API 调用、缓存回退、鉴权、异步追踪 | 调用方、被调方、返回、时序 |
| Data Flow | 管道、血缘、PII、消费方 | 来源、变换、存储、边界 |
| Lifecycle | 状态、重试、等待、终态 | 状态、事件、重试与取消路径 |
README 给的实践建议是每次只要一个「有边界的视图」：让 agent 分析仓库后产出 8 到 12 个核心组件、一条主路径、外部依赖和信任边界，支撑性细节放进卡片而不是继续加连线。后续迭代在对话里做定向修改（加一个 Redis、把鉴权模块左移、高亮回滚路径），类型化源文件保证改动只影响目标部分，其余结构保持稳定。
对应的安装命令一行：
npx skills add tt-a1i/archify -g把架构评审搬进 PR：Architecture Delta
这是 README 里着墨最多、也最贴近团队工作流的能力。两条命令分别对同一系统的两个快照做架构图比对，产出 Before / Delta / After 三个视图：
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json
官方示例是一套结算平台从 Baseline 演进到引入 Fraud Gate（风控门）的快照对比，界面上直接给出精确计数：2 个新增、2 个移除、5 个变更，外加移动和改道的连线路由。评审者看到的每个差异都是 IR 里写明的事实，工具不推断「影响」「风险」或「合并安全性」这类它无法验证的结论。
Architecture 模式还可以显式启用一个 deployment-ownership 工程档案。它的行为是 fail-closed：当 owners、单地域部署位置、私有数据库作用域、具名的边界穿越这四类信息缺失时，校验直接失败而不是放行。两条硬约束写在 README 里：这个档案永远不会被静默启用；它验证的是作者写进 IR 的事实，不探测真实基础设施。
源码证据：给节点挂上 Git 行号
防幻觉的最后一环是溯源。开启证据模式后，架构节点会带上 SRC n 标记，点击可以打开经过 Git 验证的文件和行号区间，并且固定在指定的那次公开提交上。README 的示例是 archify 对公开仓库 mco-org/mco 在提交 9f1a1cf 上做全仓追踪，生成的架构图连同类型化 JSON 源一起放进 Proof Lab 供人核对。不开启证据模式的普通产物则完全不携带源码声明，避免给读者「每个框都有出处」的错觉。
边界与上手成本
几个使用前要知道的边界：Archify 不做通用绘图编辑，也不是给 Mermaid 换皮，输入端只认它定义的类型化 IR；导出格式为自包含 HTML，外加 PNG、SVG、WebM 和 1200×630 分享卡，静态导出保持完整图面；preview 的实时预览只在本机回环地址上监听。
仓库自带 11 个签入场景的 Proof Lab（含 JSON 源、命名视图和验证凭据），不想装可以先看渲染效果。常用诊断命令包括 doctor、demo 和自然语言场景推荐 guide，例如 node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" 会给出对应的建图方案。
对一个天天让 agent 读代码、写文档的团队来说，这套流水线解决的问题很具体：架构图的每一次变更有了机器验收的凭据，评审时看到的图和 IR 是同一份事实。项目仍在 dev 版本快速迭代期，装来试跑一条命令的成本，比争论「AI 画的图能不能用」低得多。