Archify：让 Agent 把代码库画成可核验架构图的技能

正常人都觉得，让 AI 画一张架构图，最难的环节是画得好看。Archify 偏不。它把画这件容易翻车的事，交还给了一个确定性程序，只让大模型干它真正擅长的事：读代码、抽信息。这个分工看着不起眼，其实是整个项目最聪明的设计。

我第一次看到它的定位时，下意识把它归到了又一款 AI 画图玩具那一类。毕竟这类东西太多了，你让模型吐一段 Mermaid，它画得挺漂亮，但你点开节点会发现，那条调用链根本不存在。Archify 的卖点恰恰反过来：它赌你需要的不是好看的图，而是能信的图。

它本质上是一个 agent skill，装进 Cursor、Claude Code、Codex 或者 OpenCode 之后，你用自然语言说一句梳理这个仓库的运行时架构，它就读代码、出一张可交互的 HTML 地图。图里的每个节点都带着 SRC 标记，能跳回具体的文件和行号。这点和那些凭空生成的示意图，是两个物种。

这篇文章想讲清楚一件事：在 AI 帮我们画图这件事上，Archify 到底解决了什么真问题，又在哪里给不了你想要的。但光说它是什么还不够，真正让我愿意写它的，是几个反常识的设计选择。

核心亮点

最值钱的设计是 AI 抽信息、程序管渲染。大多数 AI 绘图工具让模型直接输出 SVG 或 Mermaid，质量完全看模型心情，今天画对明天画错。Archify 让模型只产出一份强类型的 JSON 中间表示，真正决定图形长什么样、边怎么连、标签会不会重叠的，是一个确定性渲染引擎。模型负责理解，引擎负责正确。

这份 JSON 中间表示不是自由发挥的。每种图类型都有对应的 schema，节点、边、路由、标签都有结构约束。作者管这叫 typed JSON IR，每种模式有 schema 与可复现源。意味着同一份输入，渲染出来的图是可复现的，不会因为模型随机性而漂移。这点对工程文档极关键：你今天画的图和明天画的图，是同一套事实。

校验发生在交付之前，而且失败会给你维修单。Archify 在把图交给你之前，会跑一套原子级校验：schema 对不对、布局合不合理、HTML 和 SVG 有没有问题、路由和标签有没有冲突。更妙的是，它不直接丢一个 Node 报错堆栈给你，而是返回稳定的规则码和修复建议。你或你的 Agent 能知道具体哪错了、怎么改。

交互不是为了炫技，是为了可溯源。生成的 HTML 不是一张死图。你可以搜索节点、上下游追踪调用链、按语义角色比较，甚至播放一段引导故事逐步走查系统。关键是所有这些交互都复用作者写进去的真实节点，不会临时编造拓扑结构。它反复强调一句话：truthful interaction，不虚构。可交互做得这么重，到底是刚需还是花架子？后面实测部分我专门验证了这个疑问。

它最实用的功能其实是架构评审的 Before、Delta、After。做 PR 评审或者架构改造时，你把改造前后的两份快照喂进去，它产出三组视图，精确列出新增的组件、删除的模块、改变的连线、移动和重路由的节点。整个过程只读，不推断影响，也不替你下该不该合并的结论。判断权留给你。

单文件交付是它的工程洁癖。一张图最终就是一个自包含的 HTML，导出时给你 PNG、SVG、WebM，还有一个 1200×630 的分享卡，可以直接贴进 README 或发布说明。没有外部依赖，没有临时状态，拷给别人就能打开。这种可移植的执念，让它在分享和归档场景里比一堆散文件靠谱得多。

上面这张分层图把它的分工画得很直白。最左边是 Agent 和代码库，中间是被 schema 死死约束的 JSON 中间表示，再往右是校验加渲染的确定性引擎，最右边才是交付给人的查看器和导出物。你会发现，模型只在最左一层出现，越往右越没有模型的自由发挥空间。

快速体验

安装就是一行命令。它走的是 skills 这个分发机制，全局装好之后会让你选自己用的 AI 编程工具。如果你是 Cursor 用户想要非交互安装，也有对应的显式命令。装完之后，在项目里直接下自然语言指令就行，本质上零配置上手。

# 全局安装（会提示选择你正在使用的 AI 编程工具）
npx skills add tt-a1i/archify -g

# Cursor 非交互安装
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

# 不想安装，临时试用
npx skills use tt-a1i/archify@archify --agent codex

装好之后，打开一个仓库，直接说人话。README 里的示例指令很直白：用 archify 梳理这个仓库的运行时架构，只要 8 到 12 个核心组件，突出一条主路径，标出外部依赖和信任边界。它背后会读代码、抽组件、出图。生成初稿后你还能继续用自然语言微调，比如把鉴权模块挪到左边、标出回滚路径，它只改你指定的部分，不会整张重画。

它同时暴露了一套 Node.js 命令行，适合想精确控制的人。核心入口是 bin/archify.mjs，自带 doctor、validate、deliver、compare 几个子命令。doctor 做环境自检，validate 对 JSON 中间表示跑质量校验，deliver 把渲染结果原子替换到目标位置，compare 则专门用来做架构快照对比。

# 环境自检
node bin/archify.mjs doctor

# 校验一份 workflow 图的 JSON 中间表示
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

# 渲染并打开 HTML
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

# 对比两份架构快照
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

交互检索是社区实测里最常被夸的一点。有用户在 Web 项目上生成图后，用斜杠搜索 Redis 节点，定位后查看下游，缓存命中和未命中的两条路径一目了然。再按 R 输入 Web 和 DB 两个节点，页面直接高亮从 Web 应用到数据库的完整调用链路，每个节点都有标注。这种图会回答你问题的体验，是静态截图给不了的。

它的处理流水线是一条单向但可回退的链路。Agent 先生成 JSON 中间表示，引擎做原子级校验，桌面预览只重载通过校验的版本，交付时原子替换目标文件，最后你更新源、无关结构保持稳定。这条链路的每一个环节，都把模型当成一个需要被校验的不可靠输入来对待。

适用场景与局限

先说什么时候该用。它不是通用画图器，而是专门解决代码库到架构图这条链路。接手陌生仓库想快速建立心智地图、团队做架构或 PR 评审、新人熟悉业务代码、给技术提案配一张能溯源的图，这几类场景它都比手画或截图高效。

什么时候别用，也得讲清楚：

• 你只想画一张一次性的简单流程图，直接 Mermaid 或 Excalidraw 更快，Archify 在这里是杀鸡用牛刀。
• 你需要手动精修每个框的位置和连线，它会让你抓狂，因为它根本不支持拖拽编辑。
• 你想要托管式在线协作、多人实时改图，它明确不做托管分享。

一个判断标准供你参考：如果你的团队架构知识现在锁在某个人脑子里，靠他口述和手画维持，那 Archify 比任何新画图软件都更该被装上去。它解决的是文档和代码对不上的慢性病，不是临时画张图的急性需求。不过工具再好，也得看谁在维护、社区到底靠不靠谱。

社区健康度

Stars 这块我得先打个预防针。GitHub 页面本身没直接显示数字，一个第三方聚合页给的是 over 13,000 stars。我没在官方仓库确认到精确值，所以这里用约数，不替它虚报。量级上它显然不是 React 那种怪物，但作为今年 4 月才从 fork 重写起步的项目，这个爬升速度不慢。

维护者结构是我最担心的点。核心作者基本就是 tt-a1i 一个人，邮箱挂在 QQ 域名下，典型的个人主导开源。赞助方有 APINEBULA、EverMind 和 Raven 这几家，能给点资源和背书，但决策和代码主力还是单点。换句话说，Bus Factor 是 1，这种项目最怕作者哪天忙自己的事去了。

但活跃度是真的没得说。181 个 commit，最新一条是 2026-08-27 修 GitHub 语言分类，说明项目每天都在被打磨。README 体系也很完整，光语言版本就有 README、README_EN、README_ZH，外加 ROADMAP、DESIGN、PRODUCT 三份设计文档。一个个人项目愿意花精力写 PRODUCT 文档，说明它不是玩票。

社区声音方面，目前公开讨论主要集中在中文技术博客和社交平台。深求社区有帖子把它定性为打通源码到架构图纸链路的工具，赞赏它以代码为唯一信源、支持源码跳转校验。博客园一位作者实测后用比之前手画的图好不少评价导出效果。X 上 @alin_zone 则直接安利：不需要学 Mermaid，不用手拖框线，对 Claude Code 或 Codex 说句话就出可交互单 HTML。

客观说，它还没到社区生态成熟的阶段。Issue 和 PR 的公开讨论量不算大，外部平台的评价多是介绍性而非批判性。对一个四个月大的项目，这正常。但如果你打算把它放进生产流程，我会建议你亲自盯一段时间 Issue 响应速度，而不是只看营销文案。

洞察与判断

我对 Archify 的核心判断是：它押对了一个被严重低估的真问题。软件架构文档最大的痛点从来不是画不出图，而是图和代码对不上。人脑整理的图，画完那一刻就开始过时。Archify 的聪明在于，它把图的根绑死在源码上，节点能跳回具体行号，等于给架构图上了可核验的户口。这比画得更漂亮有价值十个数量级。

我一开始其实没太把它当回事。fork 重写自一个 MIT 项目 Cocoon-AI/architecture-diagram-generator，又顶着 AI 原生的壳，太像那种换个皮蹭热度的东西。翻了它的 DESIGN 和 PRODUCT 文档后才改观：它对 AI 抽信息、程序管渲染的分工是有完整论证的，不是口号。这种把大模型当不可靠组件、用确定性程序兜底的思路，才是它站得住的根。

它和直接让大模型画 Mermaid 的路线，是两个哲学。后者赌模型越来越聪明，总有一天画得对。前者承认模型现在、甚至长期都不可靠，所以干脆不让模型碰正确性，只让它干信息提取。我越来越觉得后者务实。你看那些 AI 生成的架构图翻车现场，十有八九不是模型不会画，是它编了一条根本不存在的调用链还画得理直气壮。

但我也得泼盆冷水：它解决不了图准不准的全部问题。校验能拦住格式错误、重叠标签、悬空边，但拦不住 Agent 漏抽了一个关键模块，也拦不住入口分散时抽出来的组件残缺。Archify 把正确性的边界划在已抽取的 IR 内部一致，而不是 IR 完整覆盖真实系统。这点在复杂仓库里要心里有数。

一个 Bus Factor 为 1 的项目，凭什么让人敢接进生产流程？我对它商业化或长期独立存续，持保留态度。个人单点维护加 MIT 协议，意味着任何有资源的团队都能 fork 走它的思路自己集成。它真正的护城河不是代码，代码会被抄，而是 Agent 提取逻辑、校验规则库、可视化交互这三块积累的工程细节。这些细节不写在 README 里，藏在 181 个 commit 和校验源码中。护城河有，但浅。

关于趋势，我的判断是上升，但斜率会放缓。它已经接进了 Cursor、Claude Code、Codex、OpenCode、Raven，甚至 DeepSeek 社区做了 DSH 插件，分发面铺得很开。一个 agent skill 的生死，很大程度取决于能不能被装进主流 Agent 的默认工作流。它在这点上做得比大多数同类激进。等新鲜感过去，真正的考验是日常还用不用得上。

把 Archify 和另外三条常见路线摆在一起，差异就清楚了。Mermaid 通用但静态、拓扑靠模型自觉。手绘白板准确却全靠人肉、无法溯源。裸 LLM 出 SVG 最方便，但也最容易凭空编造一条调用链。Archify 卡在中间偏工程的一侧：牺牲一点自由度，换来源可核验和输出可复现。它不是画图工具的对手，是人肉维护架构文档这桩苦差事的对手。

资源地址

工具讲完了，真正该落地的，是你用不用、怎么用。

先用它梳理一个熟仓库

如果你已经在用 Cursor 或 Claude Code 做日常开发，又苦于团队架构图总是过期，现在就去装它。从梳理一个你最熟的仓库入手，看它抽出来的组件和你脑子里的对不对得上。这一步能最快判断它对你有没有用。

如果你还在观望，盯两个指标就够了：一是 Archify 自己的 Issue 响应速度，二是它能不能在主流 Agent 里变成默认带的 skill。前者决定项目靠不靠谱，后者决定它是个人玩具还是会变成生产依赖。

它不会替你做架构决策，也不会把一张歪图自动画正。但它把图和代码同源、可溯源、可校验这件事，第一次做得这么顺手。在一个人人都喊 AI 自动化的时代，这种愿意用确定性程序给 AI 兜底的克制，反而让我觉得踏实。