画架构图不用拖框，13 万次安装的 Archify 把代码库变成交互地图

接手一个陌生仓库，最耗人的往往不是第一处报错，而是那段“我到底该从哪读起”的空白。目录有十几层，服务名看着都像熟人，连线却藏在配置、队列和环境变量里。你点开 src，又点开 infra，最后在第三个 README 里开始怀疑人生。

这时候，架构图比一份更长的说明文档更有用。不是那种交接前夜匆忙拖出来、三个月后没人敢改的静态框图，而是一张可以点节点、追路径、带回源码出处的阅读地图。

最近刷到的 Archify 就在做这件事。它的 GitHub 页面当前有 8.8 万 Star，官方 README 标出的 skills.sh 安装量超过 13 万次。官方把它定位成一个给 Codex、Claude Code、Cursor、OpenCode 用的 Skill：把一段描述或一个代码库交给 Agent，产出可继续修改、可导出的交互式 HTML。

上面这张是官方演示，不是我对某个项目跑出来的结果。这个边界得先摆在前面：它证明产品想交付什么，不能证明它已经读对了你的仓库。把它拿来做“第一张图”，我觉得很值；把它当成架构真相，事情就开始往沟里滑了。

先让它收敛，不要让它“把整个仓库画出来”

官方的安装命令很直接：

npx skills add tt-a1i/archify -g

接着别急着丢一句“帮我画架构图”。这种任务没边界，Agent 很容易把页面、工具函数、测试夹具和半废弃模块都拖进画布，最后得到一碗颜色很好看的意大利面。

官方 README 给了一个很靠谱的收敛方式：只保留 8–12 个核心组件，突出一条主要路径，并单独标出外部依赖和信任边界。我把它改成了更适合接手仓库的版本，直接发给 Agent 就行：

分析当前仓库，生成一张高层运行时架构图。
只保留 8–12 个核心组件；从用户请求开始，突出一条主路径。
标出外部依赖、数据存储、异步任务和信任边界。
每个节点附上对应目录或关键文件路径；不确定的连接标为“待核对”，不要猜。
辅助细节放进说明卡片，不要增加更多连线。

这段提示词真正有用的地方，不是“画得更漂亮”，而是逼着提问的人先给任务定比例尺。你要的是新人 onboarding 的鸟瞰图，还是一次缓存穿透的排查图，还是一个 PR 改动前后的影响图？三种图都能画，混在一张里就谁也读不动。

比如一个典型的 Web 服务，第一张图只需要回答：浏览器进来以后先到哪，缓存没命中时谁去读库，消息怎么交给后台任务，哪些调用跨出了自己的系统。至于每张表、每个 DTO、每个 retry 参数，留给下一张更窄的图。图一旦试图替代 IDE，就已经开始失去用途。

图里每一根线，都得有个能回去核对的地方

Archify 官方 README 提到，它可以把仓库来源固定到具体提交，并在图里提供源码关联。这个设计比“AI 自动画图”更值得看，因为架构图最麻烦的不是生成，而是过几周以后有人问：这根线凭什么还在？

所以生成后，我建议顺手做三件很朴素的事。

第一件，点开主路径上的每个节点，确认它能回到真实目录、接口定义或部署配置。找不到来源的节点不要补脑，直接挂上“待核对”。图里最危险的颜色，往往不是红色，而是看上去毫无疑问的绿色。

第二件，专看边界。数据库、第三方 API、对象存储、队列、鉴权服务，都是图最容易“画顺了”的地方。你需要问的是：数据从哪儿进，凭据在哪儿停，失败后往哪儿退，谁有权限跨过去。很多设计评审卡住，并不是大家不懂业务，而是边界被一条过于顺滑的箭头抹掉了。

第三件，把运行时和设计时分开。代码里连着 Redis，不代表线上每个请求都走 Redis；图里有 Worker，也不代表它正在消费；一条箭头更不等于延迟、吞吐和成本都合理。涉及生产判断时，还是得回到 trace、日志、指标、配置和发布记录。漂亮的交互图不能替你背 SLO。

这三步没什么炫技，甚至有点扫兴。但它们能把“AI 帮我画了一张图”变成“团队拿着一张图开始查事实”。后者才是它进工程流程的理由。

它适合当起点，不适合当盖章工具

我会把 Archify 放在这几类场景的开头：刚接手代码库、给新人讲一条请求链、准备架构评审、排查一个跨服务问题，或者需要把一段口头方案变成能讨论的页面。官方还展示了流程图、时序图、数据流、ERD、时间线等类型，输出是独立 HTML，也能导出图片或 PDF；做同步沟通很顺手。

但有两类场景需要收一点。涉及权限、支付、隐私数据或生产变更时，图只能帮你发现该问什么，不能替代评审和验证。另一个是仓库本身已经缺文档、模块命名也混乱的情况：Agent 读到的材料不完整，画出来的图自然也会带着缺口。它不会因为配色高级就获得事实豁免权。

Archify 的产品价值，不在于让每个团队都多一张海报，而在于把“这套系统我还没读懂”变成一组能被点击、反驳和修正的问题。图是入口，核对才是后半程。

如果你接手一个陌生仓库，最想让第一张图回答的问题会是什么：一条请求怎么走、数据在哪落，还是谁在悄悄依赖谁？

—— 小岛AI