你大概也遇到过：让 Cursor 或 Claude Code 顺手画一下系统架构图，几秒钟后它真交出一张。第一眼挺唬人，细看就露馅——Redis 出现在图里，可你压根没碰过 Redis；两个服务之间的连线，是模型猜的；想改一个箭头，整张图的布局跟着重新排列。
这类图最大的问题不是丑，而是没人敢信。放进评审文档，读者得先逐个节点核对；贴进新人文档，等于给自己埋雷。手写 Mermaid 会好一点，但那又是另一份体力活：背语法、调箭头，画完之后布局还是不听使唤。
我平常翻这类项目，习惯先看它怎么处理“画错了怎么办”，而不是先看效果图。Archify 让我破过一次例，但真正把我留住的，还是那套失败处理机制。
Archify 就是冲这个缝隙来的。它本质是装进 Cursor、Claude Code、Codex CLI、OpenCode 的 agent skill：你用自然语言提需求，agent 产出一份带类型的 JSON 中间表示，Archify 再把它确定性编译成 HTML/SVG——重点是，渲染之前机器先做校验，不过关就不交付。
项目卡片
- 项目：Archify[1]
- 状态：v2.16.0（2026-08-30）/ 6.1万 star / 2026 年 4 月创建，四个半月
- 一句话判断：把「AI 画架构图」拆成两道工序——布局判断交给 agent，事实校验交给机器，交付带质检回执的自包含 HTML
好看不是第一关，作者先证伪了「换皮」
市面上不缺“把 Mermaid 画好看”的工具。Archify 的作者先做了个实验，直接把这条路堵死了：五张真实的 Mermaid 图，各渲染三个版本——A 原生 Mermaid，B 只换 Archify 的配色和字体、布局不动，C 让 agent 手动摆放坐标。15 张截图盲评，结论就写在仓库的 experiments/v3-mermaid-validation/RESULT.md 里，只有一行：C looks good; A and B both don't look good。换 CSS 不换布局，审美差距无法弥合。
所以 ROADMAP 里写得很硬：Auto-layout (dagre / elk-js) is a dead end for archify。这类架构图的价值本身就藏在布局判断里——Auth Provider 画在 AWS 区域外面，因为它是外部身份源；S3 放在 CloudFront 正下方，表达的是服务关系。把这些判断拿掉，再好的配色也只能得到一张均匀网格。
于是 Archify 干脆把布局判断整个交给 agent：节点层级、间距、路由、强调，都由模型从语义推断。这也是它和“Mermaid 美化器”的本质分界——前者改皮肤，后者改信息架构。换皮救不了布局，这行实验结论是整个项目的地基。
agent 会画了，凭什么信它
判断交给模型，信任问题自然就冒出来了：模型万一画错呢？Archify 的答案，是把“验收”从人眼里挪到机器里。
那份 JSON 中间表示有独立的 JSON Schema，五种图——架构、工作流、时序、数据流、状态机——各有各的 schema、渲染器和布局规则。交付走 deliver 命令：schema、布局、HTML/SVG、路由、标签避让等九项检查全部通过，产物才会原子替换旧文件；任何一项失败，旧图原样保留：
node bin/archify.mjs validate workflow candidate.json --quality showcase --json
node bin/archify.mjs deliver workflow candidate.json /tmp/flow.html --quality showcase --json
失败时不甩报错栈，而是返回带稳定规则码的诊断和允许的修复动作，agent 按回执修，两轮修不好就如实上报。
更较真的是，仓库自带一个 ordinary-model-floor 基准，专门回答“普通编码 agent 第一次能不能画对”：语义要求齐不齐、CLI 校验过不过、人工复查有没有缺陷，三关全过才算数。把“AI 生成的质量”做成可回归验证的交付门禁，而不是一句“效果很好”——这个工程姿态本身就是它值得关注的原因。
交付之后的交互，不许发明拓扑
图打开之后，可信度还得延续。Archify 生成的 HTML 是单文件、可交互的：按 / 搜节点，点一个节点能向上游、下游追溯，按 R 探测两点之间的精确路径，还能播放一段有限的引导式讲解——所有这些操作，只复用图里声明过的节点和关系，不现编拓扑。
需要对着源码讲架构时，可以让节点挂上证据标记：标注 SRC n 的节点点开是 Git 校验过的文件和行号，钉在一个公开 commit 上。README 里给的实例是它对 mco-org/mco 仓库的实测，生成图里的每条主干都能回溯到具体提交。
对外分享也有对应物：导出菜单里除了 PNG/SVG/WebM，还有 1200×630 的分享卡；查完一条路径后可以导出「Route 分享卡」，把这条路径连同完整底图一起带走。另一个容易被忽略的场景是代码评审：给改动前后的两份快照跑一次对照，生成 Before / Delta / After 三联图，增、删、改、移动的节点逐条列清——它只陈述事实，不替你判断这次合并危不危险：
node archify/bin/archify.mjs compare architecture base.json head.json delta.html --json
看到这里我基本确认了它的取向：Archify 不想当“更聪明的画图模型”，它想当那条质检线。模型换了一茬又一茬，质检线是稳定的。
普通开发者怎么用上它
一条命令装进 agent：
npx skills add tt-a1i/archify -g
装完不需要学任何语法，三种入口按手头的材料选：手头只有想法，直接在对话里说“用 Archify 画：Browser → API → Redis 缓存 → PostgreSQL 兜底”，不需要仓库；手头有代码库，让 agent 先分析仓库再画，还能要求 8 到 12 个核心组件、一条主路径、信任边界；顺手贴一段 Mermaid 也行，agent 读它的拓扑和含义，重新作图，不沿用原样式。
图生成后在对话里继续改：“加个 Redis”“把 auth 挪到左边”“高亮回滚路径”，改动落在 JSON 源上，无关部分不动。刚发布的 v2.16.0 还给查看器界面加了简体中文（meta.locale: "zh-CN"），图里的节点文字仍按你写的来。
边界在哪里
先说它不是什么：不是通用绘图编辑器，没有拖拽画布；不做自动布局——这是刻意为之，不是没做完；没有托管分享，产物就是本地一个 HTML 文件；Mermaid 也只是输入之一，不存在“解析所有 Mermaid”的承诺。
环境上它依赖本机 Node，查看器按桌面优先设计，窄屏只是安全降级而不是完整体验。想画带源码证据的图，得明确要求，普通产物不含源码链接；而“上游/下游追溯”只代表图里声明的关系，作者反复强调它不是爆炸半径、不代表运行时影响。另有更新检查会访问一个固定 manifest，不发版本、项目或账号数据，可以用 ARCHIFY_UPDATE_CHECK_DISABLED=1 整个关掉。
一句话收口：AI 画图这个赛道里，多数项目在卷“画得更好看”，Archify 把力气花在“画错时机器先知道”。如果是我自己上手，会先拿一个正在维护的小服务试：让 agent 分析仓库出图，再故意说错一个需求看它怎么拦。架构图只活在聊天窗口里，它可能过重；要进文档、进评审、进新人的第一周，“带质检回执”这四个字就值回一条安装命令。
引用链接
[1] Archify: https://github.com/tt-a1i/archify
发表于 3 小时前
|
查看: 7|
回复: 0
