Archify 用 Agent 把描述和仓库变成交互式架构图

团队画架构图的流程通常是这样的：先有人凭记忆在白板上比划，再有人把它翻译成 Mermaid 或 draw.io 文件，等代码改过几轮，图就和系统对不上了。编码 Agent 越来越能改代码，却看不见自己要改的结构长什么样。

Archify 是一个用 JavaScript 写成的开源 Agent Skill，把一句话描述或一个代码仓库转成交互式 HTML 架构图、时序图与数据流图。

它不要求你先有仓库。在 Cursor、Claude Code、Codex CLI 或 OpenCode 里装好这个 Skill 之后，用自然语言把系统描述给 Agent 就行，比如让它画一次 Web 请求：浏览器调用 API，API 查 Redis，缓存未命中时查询 PostgreSQL 并回填缓存。产出的是一份带交互动效的 HTML，你可以接着让 Agent 加认证、高亮缓存未命中的路径，或者切换成浅色主题。

它怎么做到的

链路的起点是用户的一句话或一个仓库。Agent 装载 Skill 后读到它的说明文件，按其中的指引把描述整理成图定义，再交给对应类型的渲染器生成 HTML。从 Issue 里流出的命令 node archify/bin/archify.mjs validate workflow map.json --json 能看出，工作流图的定义落成了一份 JSON 文件，校验由命令行子命令完成，这也意味着生成物在交回给你之前会被机器检查一遍。

渲染器按图的种类分开存放，路径形如 renderers/<type>/render-<type>.mjs。架构图、工作流图、时序图、数据流图、生命周期图各走一条，输出统一是自包含的 HTML，放进 viewer/ 里浏览，也可以导出。README 里给的示例包含源码链接与路径追踪，图上的节点能对应回仓库里的文件。

3.0 之后交付环节多了一步验证。finalize 和独立的 deliver 会先检查生成的产物，再把结果写进回执与终端输出；3.0.1 又在这份回执里加了版本提示，当有更新的已验证版本时，Skill 会在最终回复里提醒一次。至于 Agent 如何挑选图类型、如何决定节点布局，仓库未展开说明。

几个关键设计

以 Skill 形式接入编码 Agent

安装走的是多语言 Agent 生态里常见的那条路：

npx skills add tt-a1i/archify -g

README 写明它适配 Cursor、Claude Code、Codex CLI 与 OpenCode，另外的集成放在 integrations/ 目录下。这样带来的结果是使用门槛压在「你的 Agent 支不支持 Skill」这一个条件上，不需要单独跑一个服务，也不需要把图上传到某个平台。Issue 里也出现了这类设计带来的诉求：有人希望它发布到 npm registry，好让 npm 与 npx 直接装上，这条请求目前仍是待解决状态。

按图类型拆分的渲染器

每种图有独立的渲染器脚本，renderers/<type>/render-<type>.mjs 一一对应，输入从标准输入读。有人提过希望把这些渲染器暴露成可导入的库 API，理由是它们现在是脚本而不是导出函数，这条 Issue 已经关闭。对只想画图的用户，脚本形态不构成障碍；想在自己的 Node 程序里复用渲染逻辑，就得自己琢磨脚本的输入约定。

校验与交付回执

生成只是第一步。Archify 在把产物交回之前会跑一轮校验，并把结果写进回执。校验覆盖的是结构与语义规则，例如组件不应落在边界框之外、连线不该穿过无关组件、带虚线的连接标签要用对应颜色，这些规则在 Issue 里大多已经修掉。校验能发现问题，也在若干案例里放过了问题，具体见下一节。

自包含 HTML 与可选的外部集成

最终产物是一份自包含的 HTML，动效、交互和导出都打包在里面，这也是仓库体积达到 468126 KB 的一部分原因。2.15.0 加了一个可选配置 column_fit，按 viewBox 相对宽度排布泳道；同一版本还放出了面向 DeepSeek Harness 的可选分发包 @tt-a1i/[email protected]：

dsh plugin --profile web add @tt-a1i/[email protected]

它要求 @deepseek-ai/[email protected] 与 Node.js ^22.19.0 或 >=24.0.0，README 把它标为实验性发布。不打算引入这套依赖的人可以完全不管它，主链路不依赖 dsh。

这样设计的代价

最直接的一条是 token。Issue 里两条被顶得比较高的反馈都在说这件事：有人画一张架构图消耗了 minimax m3 几十兆 token，另有人说整个过程很慢、token 消耗很大。两条都已标记为已解决，但对按量计费的模型，这仍是使用前要算的一笔账。

校验通过不等于画得对。有几条待解决的 Issue 描述了这类情况：一个非成员组件被渲染在边界框内部，而 showcase 与 deployment-ownership 两项校验都通过；两条反向平行的 labelAt 连接被画成一条线，交付校验仍然给了 9/9；架构模式下连线可以穿过无关组件，渲染与校验都不报错。校验规则和渲染实现之间还有缝隙。

规模也是一道限制。一条待解决的 Issue 记录 validate 在大型工作流上会失败，原因是 checker 的报告超过了 spawnSync 默认 1 MiB 的缓冲区。图一复杂，这条路就走不通。

生态覆盖同样不全。有人提出需要图标优先的节点渲染模式，因为内置图标库没有 AWS、Azure、GCP 云厂商图标；也有人希望补上 Hermes Agent 的 Skill-only 安装路径，目前文档覆盖的是 Cursor、Claude Code、Codex、OpenCode、Raven 与 DeepSeek。仓库当前有 195 个开放 Issue。

同类项目的横向对照

如果你只想要一张静态图、不想为交互动效和校验轮次付 token，Archify 在这件事上没有优势：它的产物是自带动效与导出的 HTML，生成成本随图复杂度上升，名字里带 svg 的同类项目更值得先看一眼（它们的实际能力我没有逐一核实）。它的长处出现在需要把图交给别人浏览、需要在交付前有一次校验的时候。另一个绕不开的点是安装路径，Archify 目前没发布到 npm registry，发布请求还在待解决，选它就要接受只能通过 Agent Skill 装载。

对你的实际影响

在开发机上用 Cursor 或 Claude Code 干活的人，安装就是在终端里跑一条 npx skills add，没有服务要起，也没有数据库要建。真正占资源的是生成过程：图越复杂，Agent 读写和校验的轮次越多，token 账单和等待时间都跟着涨。

校验宽松这件事在日常使用里的表现是，你可以相信回执说了什么，但不能只靠回执判断图对不对，连线交叉密集的架构图尤其要自己看一眼。大图建议拆成几张小的，既避开 1 MiB 的报告缓冲，也省 token。

项目用 JavaScript 写成，MIT 许可证，仓库地址在 github.com/tt-a1i/archify，当前 75014 star、5039 fork、218 watcher，最近一次提交在 2026-09-30。想改渲染细节的人需要读懂 renderers/ 下脚本的约定，这部分没有库 API 可用。

适合已经用 Cursor、Claude Code、Codex CLI 或 OpenCode 干活，需要把系统结构、调用链路或交付流程画出来给同事看的人，尤其是那些希望图能一直改、能跟着代码走的人。不适合只想拿一张 PNG 贴进文档的人，也不适合坚持用 npm install 管理全部工具链的团队，以及需要大规模图一次性校验通过、不能接受渲染与校验存在缝隙的场景。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。