GitHub Trending 全语言周榜第一，本周涨星两万四。archify 是一个 Agent Skill，把一段描述或者一个仓库变成可交互的 HTML 架构图，并且在自己交付之前先验证一遍。

仓库 tt-a1i/archify，2026 年 4 月 15 日创建，MIT 许可，JavaScript 写的。抓取 GitHub API 的数据是 71,257 stars、4,790 fork。

它解决的不是「画图」

多数人画架构图的流程是：脑子里有个结构，找一个绘图工具，手动摆位置，导出图片。图对不对只有自己知道；结构改一次，全部重摆。

archify 把这件事拆成两段。Agent 负责理解结构、决定层次和摆放（README 里明确写了布局判断交给 agent，通用自动布局被排除在范围之外），CLI 负责验证这个决定是否成立。产物是一份单文件 HTML：带交互、带命名视图、可以导出 PNG 和 1200×630 的分享卡，打开它不需要安装任何东西。

三个我觉得最有价值的点。

一、类型化 JSON IR，而不是让模型直接吐 HTML。

每个图形模式（架构、流程、时序、数据流、生命周期）都有自己的 schema，中间表示必须先过 schema 才能进入布局。schema 在每一层都设了 additionalProperties: false，未知字段直接被拒绝，不会被静默忽略。这一点决定了后面所有事情——只有结构是确定的，验证才有意义。

二、验证发生在交付之前，而不是交付之后。

validate 和 deliver 会跑一份检查清单。实测我这张图的检查项是九条：single_svg、finite_svg、orthogonal_arrows、label_route_clearance、relationship_crossings、relationship_corridors、container_border_runs、route_rhythm、legend_clearance。名字基本就是内容：SVG 只有一块、动画可终止、连线走正交、标签与连线保持净空、关系不交叉、不贴着容器边框跑。交付是原子的——只有全部通过，新产物才会替换掉上一份已知可用的输出。

三、失败带修复回执，而不是甩一个 Node 堆栈。

验证失败时返回的是稳定规则码、精确到像素的证据，以及该规则支持的修复项。不是「布局有问题」这种话。

白物集这边怎么用上

我们自己的架构图是这么生产的：用架构图技能生成一份 HTML，浏览器打开，截图，再当作专栏文章的配图。流程能跑，但有个一直没解决的问题——图对不对全靠肉眼。两条线穿过一个节点、标签压住模块名字、连线贴着分组边框走，这些细节在宽屏上凑合能看，缩进文章里就是一团糊。

所以我把 archify 拉到本地实测，测的对象不是它的示例，是我们自己的内容管线。

第一步 clone 仓库，跑 node bin/archify.mjs doctor。输出 15 条 [ok]，从 Node 版本（要求 >=18，本机 26.3.0）到五个 renderer、schema 校验器、预览运行时，全绿，最后一行是 Archify is ready.

第二步把白物集的管线写成 IR：感知源 → 采集器 → 聚类打分 → 出稿 Agent → 内容 API → Postgres，再从 Postgres 下沉到服务端渲染 → 分发出口（网站 / 小程序 / 专栏）→ 反馈采集 → 表现表 → 权重修正，最后由权重修正回到聚类打分，闭环。11 个组件、1 个分组、11 条连接、3 张说明卡、3 个命名视图（出稿主路径 / 分发出口 / 反馈回流）。文件 4,213 字节。

第三步验证。第一版直接失败，诊断按规则码分成四类：clean-flow/endpoint-side-direction（端点方向与推断的进出边不一致）、clean-flow/edge-through-node（连线穿过无关组件）、composition/container-border-run（连线顺着分组边框跑了 166 像素）、composition/label-route-clearance（标签之间净空不足 4 像素）。每条都带具体坐标和像素证据。

按回执改完，第二版只剩一条：标签「文章数据」压在了组件 db 上。

Label "文章数据" overlaps component "db"
  label rect:     [1086, 154, 48, 14]
  component rect: [1040, 110, 140, 64]
  Suggested fix:  labelAt [1110, 188] or labelDy +24 (below)

照它给的方案加了一个 labelDy: 24。第三版九项检查全部通过。deliver 的回执是 checksPassed 9/9、errors 0、warnings 0、规范文件 sha256 5335e26e…、产物 sha256 ccb64cbc…、产物 813,909 字节。

顺手核了一遍「自包含」这件事：产物 HTML 里 <script src> 出现 0 次，没有 CDN 引用，字体内嵌（只留了 JetBrains Mono 的许可证链接），<html lang="zh-CN"> 也对。

对我们来说真正的变化是：图从「看起来对」变成「检查过」。以前判断一张架构图有没有毛病，只能盯着看；现在有一条可复现的命令，退出码和 JSON 回执说明问题，而且回执里写清了该怎么改。

适合什么，不适合什么

适合的几类：

• 结构会被反复改的系统图。IR 是一份文本，改一个组件、重跑验证，没被碰到的结构不会跟着漂。
• 要嵌进文章或文档的图。单文件 HTML、可导出 PNG、1200×630 分享卡，阅读者不需要装任何东西。
• 需要机器卡住的场合。validate 返回 JSON 和退出码，可以进 CI，而不是一张需要人看的图片。
• 讲解型内容。命名视图与引导播放（#view= 形式的长链接能恢复到某个视图）比一张塞满信息的静态图好读。
• 架构变更说明。README 描述了一个 compare 子命令，把 before / delta / after 三份快照做成带机器回执的对比图，我没有实测这一项。

不适合的几类：

• 想让它自己摆盘的。通用自动布局明确不在范围内，坐标要你或你的 agent 给。这是取舍而不是缺陷——判断力放 agent 侧，确定性放 CLI 侧。
• 只想画草图的。为草稿写 IR 属于过度工程。
• 已经用 Mermaid 且图不复杂的。它自己说了不是 Mermaid 主题。
• 想要在线协作编辑的。没有托管分享，没有所见即所得编辑器。
• 想让界面和内容全中文的。meta.locale: "zh-CN" 只本地化 Viewer 界面（页标题、图例、无障碍文案、语言标记），作者写的内容不翻译——图里的中文得你自己写进去。

上手

# 1. 装到你的 agent（Cursor / Claude Code / Codex CLI / opencode）
npx skills add tt-a1i/archify -g

# 2. 自检环境，15 条检查全绿再往下走
node bin/archify.mjs doctor

# 3. 不确定该用哪种图，让 CLI 推荐
node bin/archify.mjs guide "Show an API request with Redis cache miss"

# 4. 验证：失败会返回规则码、证据与可用的修复项
node bin/archify.mjs validate architecture my-pipeline.json --quality showcase --json

# 5. 交付：验证通过才原子替换目标文件
node bin/archify.mjs deliver architecture my-pipeline.json out.html --quality showcase --json

对 agent 说的话很短：Use Archify to diagram a web request: Browser calls the API, the API checks Redis, and a cache miss queries PostgreSQL and fills the cache. 然后接着聊——加一个组件、把认证挪到左边、高亮缓存未命中路径。

写这篇文章时我在想一个更实际的问题：一张图是给人看的，但一张图有没有毛病，其实可以先让机器筛一遍。费时间的从来不是画，而是你不知道自己画错了。