8 月 26 号那天 archify 还挂着 17,195 颗星，日增刚过一千。四天之后，31,333 颗星，1,947 个 fork，连续第四天坐在 GitHub Trending 日榜第一。这个项目是 4 月 15 号创建的，MIT 协议，主要语言 JavaScript，四个半月走完了多数开源项目一辈子走不完的路。
说真的，热度是结果，解法才是原因。今天把它单独拆开，看看它到底解决了什么。
先纠个偏，它不是画图工具
README 第一句自我介绍就写得很清楚，Archify is a Node.js rendering and validation system。渲染加验证的系统，落点在验证。作者在 Why Archify 一节里也说得很直白，它不是通用绘图编辑器，也不是 Mermaid 主题。
这句话值得停一下。你想想看，让 Agent 画架构图这件事，工具早就有了，让模型吐一段 Mermaid 语法，渲染成 SVG，五秒钟搞定。真正的痛点从来不是「画不出来」，是三个更刁钻的问题。画得丑，自动布局的线像一团毛线。画得假，Agent 会编造不存在的组件关系。画得飘，同一个系统描述给两遍，出来两张不一样的图，review 的人不知道该信哪张。
archify 的答案是把画图这件事改造成一条流水线，Agent 只负责产出一份类型化的 JSON 中间表示，剩下的编译、检查、交付全部确定性执行。
类型化 IR，流水线的地基
五种图型各有一个 JSON Schema，schemas/architecture.schema.json、workflow.schema.json、sequence.schema.json、dataflow.schema.json、lifecycle.schema.json，公共字段抽在 common.schema.json。Agent 产出的每一份图都必须先过 schema，拿仓库里自带的例子 examples/web-app.architecture.json 看，长这样。
json
{
"schema_version": 1,
"diagram_type": "architecture",
"components": [
{ "id": "users", "type": "external", "label": "Users", "pos": [40, 300], "size": [120, 60] },
{ "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000" }
],
"connections": [
{ "id": "users-to-cdn", "from": "users", "to": "cdn", "label": "HTTPS", "variant": "emphasis" }
],
"boundaries": [
{ "kind": "security-group", "label": "sg-api :443/:8000", "wraps": ["lb", "api"] }
]
}组件类型只有七种，frontend、backend、database、cloud、security、messagebus、external，边有四种变体。其实吧，schema 卡死之后，Agent 的自由发挥被圈在一个可枚举的空间里，后面的每一步检查才有据可依。
验证器不是手写的 if else，scripts/generate-validators.mjs 会从 schema 生成 renderers/shared/generated-validators.mjs，这个设计保证了 schema 和验证逻辑永远不会漂移。
把镜头拉远，整个仓库就是按这条契约链分层的。
五个渲染器共用 shared/ 内核，验证器由 schema 生成，CLI 九个命令各管一段，契约先行在这里不是口号，是目录结构。
九道检查，和一张诚实的维修回执
整个项目最值钱的部分在 archify/SKILL.md 里，那是给 Agent 读的作业契约。里面写了一条硬规矩，基础验证只跑 4 项 artifact 检查，showcase 级验收必须 9 项全过，0 个构图错误 0 个警告。
验证失败时的输出是这篇文章最想强调的设计。不是一段 Node 堆栈，不是让 Agent 自由重试，而是一个结构化的诊断对象，稳定的问题码，出错的 subject，量出来的 evidence，以及一组 supportedFixes，只允许用支持的修复手段。renderers/shared/validator.mjs 里有个 annotatedPath 函数，注释写着，/nodes/3/label 对修 JSON 的 LLM 来说不如 /nodes/3 (id: "router") /label 好读。诊断信息是按「谁来读」设计的，这行注释比十个功能更能说明作者想明白了 Agent 时代的错误处理该长什么样。
更狠的是修复纪律。SKILL.md 规定，每次只改被诊断点名的 subject，如果连续两轮修复没有让错误数创新低，停下来，如实报告没解决的问题。不许无限重试，不许假装成功。
这条纪律比功能值钱。
原子交付，和一份 SHA-256 回执
验收通过之后走 deliver 命令，流程是先把 spec 的精确字节冻结成同目录私有快照，渲染并检查这份快照，全部通过后才原子替换目标 HTML，最后报告 spec 和产物的 SHA-256 加字节数。半成品永远碰不到正式输出。
交付之后还有一道可选的 visual-check，在 1440×900、1600×1000、1920×1080、2048×1320 四档视口量容器溢出，抓明暗双主题截图，写旁证文件。注意它的回执永远是 visualReview: "pending"，截图是给你检查用的证据，不是自动通过的声明。老实讲，一个工具能把「我没看」这三个字写进自己的回执里，这种克制在开源圈不多见。
把这条流水线从头到尾画出来，长这样。
实线是主流程，虚线是失败路径，回执驱动修复，两轮封顶，这就是它和「让 Agent 再试一次」的分界线。
给架构评审场景还留了一手，archify/delta/architecture-delta.mjs 配合 compare 命令，对比两份已验证快照，产出 Before / Delta / After 三视图，added、removed、changed、moved、rerouted 五类事实各带精确清单。PR review 的时候，架构变更从「肉眼找不同」变成机器回执。
工程细节里的密度
这个仓库的细节密度配得上它的星数。
布局层有 Automatic Port Spread 规则，自动路由禁止产生小于 8px 的线段和小于 16px 的内部转角，近并行端口走外侧桥接，这些数字都写在 SKILL.md 的 authoring invariants 里。品牌标识收了 107 个带来源的矢量 mark，抓取必须 digest 锁定，SHA-256 对不上就 fail closed。测试目录躺着 87 个 .test.mjs 文件，粒度细到 repair-receipt.test.mjs、motion-governor.test.mjs、automatic-port-spread.test.mjs。连设计系统都是 token 化的，DESIGN.md 里 canvas #020617、八种语义色、全家 JetBrains Mono，一字排开。
版本节奏也密，v2.14.0 是 8 月 11 号，v2.15.0 是 8 月 17 号，现在开发版已经到 v2.16.0-dev.0，六天一个 minor。
挑刺时间，带着证据挑
坦白讲，说了这么多好话，该挑的刺一根都不能少。
讲真，最实在的一条来自 issue #126，一位跑了三个仓库十四张图的深度用户报告，workflow 的列间距不均匀，同样的边放在 0→1 列能过，放在 1→2 列就报 too short（12px，最低 28px），间距模型在文档里查不到，只能试错。更别扭的是诊断建议的修复是「删掉标签或走通道」，用几何理由删语义信息，而标签在 archify 自己的契约里是 semantic data。这个 issue 同时暴露了一个交付陷阱，deliver 失败时会保留上一个 artifact，紧跟着的 visual-check 测的其实是旧文件。文档缺口也顺手记两条，--repo-root 只有 architecture 类型支持但 SKILL.md 没写，workflow 的 col 只到 5，都是 validate 阶段才炸出来。
社区结构要留意。十个贡献者里 tt-a1i 一人 153 个 commits，第二名 18 个，bus factor 老实说偏高。出身也要说全，SKILL.md 的 metadata 里写着 based_on Cocoon-AI/architecture-diagram-generator v1.0，它不是从零长出来的，是在一个 MIT 项目的地基上盖起来的楼。
商业痕迹轻微但存在。README 赞助位挂着 API 聚合商 APINEBULA 的 referral 链接带九折码。还有一个联网行为，装好的 skill 会每 72 小时左右 GET 一次固定的稳定版 manifest 提示更新，不传版本号不传项目数据，可以用 ARCHIFY_UPDATE_CHECK_DISABLED=1 一键关掉。怎么说呢，披露写得算透明，但「本地工具默认联网」这件事，我觉得每个用户都该知道。
和老伙计们比一比
| 维度 | Mermaid | PlantUML | D2 | Excalidraw | archify |
|---|---|---|---|---|---|
| 输入形态 | 文本语法 | 文本语法 | 文本声明式 | 手绘 | Agent 产类型化 JSON IR |
| 布局 | 自动布局 | 自动布局 | 自动为主可手动 | 全手动 | Agent 主导，规则兜底 |
| 质量验证 | 无 | 无 | 语法检查 | 无 | 九项检查 fail closed |
| 产物 | SVG | SVG/PNG | SVG/PNG | PNG/SVG | 自包含交互 HTML 加四格式导出 |
| 变更对比 | 无 | 无 | 无 | 无 | Before/Delta/After 机器回执 |
对比完就清楚了。快速往 README 里贴一张图，Mermaid 还是首选，别折腾。但当你需要一张「能拿去评审、能对得上代码、能当交付物」的架构图，工具栏里没有第二个选项带验证链和变更回执。
能带走什么
我一直觉得这个项目最值得偷的不是图，是模式。给它起个名字，验收前置的工件管线。
任何 Agent 生成的工件，图、文档、代码、配置，都可以套这四步。第一，把自由输出压进 schema 化的中间表示，圈住发散空间。第二，确定性编译加多维检查，不过就给结构化回执，码、主体、证据、支持的修复。第三，修复轮次封顶，两轮不见好就如实上报，禁止无限重试和假装成功。第四，原子交付加哈希回执，半成品永远上不了台面。
archify 用四个月证明了一件事，Agent 时代工具的竞争力不在「能生成什么」，在「生成的东西凭什么被信任」。这个判断迁移到任何 Agent 周边工具上都成立，你在做 Agent 应用的话，这条流水线值得原样抄走。
至于它自己能走多远，看两件事就够了，bus factor 什么时候降下来，以及那个列间距模型什么时候写进文档。工具的护城河是信任，信任的敌人是例外。