Archify 怎么用：让 AI 读一遍项目，交出一张能点、能查、能被机器验过的系统图

0030 秒速览：三句话，和你的第一个动作

读完这一篇，你能做到三件事：① 判断 Archify 值不值得装进你自己的 AI 工具里；② 知道该说什么话，才不会得到一张「密密麻麻没法看」的图；③ 拿到 AI 交回来的那张图时，知道要问哪几句话才算真的验收过。

如果只记三句话

接下来 60 秒：你的第一个动作

先确认你手上有没有跑得起来的运行环境。打开终端（就是那个能粘命令的窗口；macOS 叫「终端」，Windows 叫 PowerShell），粘这一条：

node --version

# 看到 v18.x / v20.x / v22.x / v24.x 之类都算合格。
# 本文作者本机是 v24.19.0，npm 12.0.2。
# 如果提示 command not found：去 nodejs.org 下 LTS 版
# （LTS 是「长期维护版」，选它就不会踩到试验版本），一路下一步装完，再回来重敲这一条。

合格之后，就是装它——一条命令，装到你的 AI 编程工具里：

npx skills add tt-a1i/archify -g

# npx 是 Node 自带的一个「临时取来就跑」的命令，装 Node 的时候就有了。
# 敲下去之后它会问：装到哪个 Agent、要不要软链接。
# 软链接（symlink）的意思是「装一份、多个工具共用」，建议选它，方便以后更新。

装完，回到你平时跟 AI 说话的那个窗口（不是终端），把下面这句发给它，就是你今天的第一张图：

用 Archify 画出这个项目的运行时架构。只保留 8–12 个核心部分、一条主路径、
外部依赖和信任边界；支持性细节放进卡片，不要继续增加连线。

关键数字（先有个量级感）

如果你只有半小时：按你的处境直接跳

01它是什么：AI 画的图，凭什么可信

先破一个几乎每个人都会有的错想，不破掉它，后面所有事都会被理解歪。

它不是「让 AI 直接画一张图」

你大概见过那种用法：对 AI 说「给我画一张架构图」，它思考两秒，吐出一张看着挺像回事的图。Archify 的用法不一样——中间多了一道东西。

这个分工看着只是工程上的讲究，但它决定了你能拿这张图做什么。「模型涂的图」你只能看个大概；「程序从源文件渲染出来的图」你可以指着某个框问「这一块对应代码里的哪个文件」——因为有源文件可以对。

一次生成里到底发生了什么

README 里把这条链写成了五个词：生成 → 校验 → 预览（可选）→ 交付 → 迭代。[1] 里面有一步值得你特别留意：交付是「原子替换」——新图先在同目录生成候选文件，只有全部门禁通过，才替换掉原来那份。也就是说，你手上永远不会出现一张「改到一半、坏的」图；要么是上一张好的，要么是新的这张。

它不是这三样东西

那它是什么：一句话定义

这句话里有四个词值得当场拆开，拆完就没有生词了。

「Agent 技能」是什么

「Agent」在这里就是指会自己动手的 AI 助手——不光跟你聊天，还能读你的文件、敲命令、改代码的那种（Claude Code、Codex CLI、Cursor 都属于这一族）。

「技能」（Skill）是一份写给 AI 看的操作手册 + 一箱配套工具，放在一个约定好的目录里。AI 平时不知道它存在；一旦你说的话跟手册封面上的描述对上了（比如提到「画架构图」），它就把这份手册读进来，照着里面的步骤干活。你可以把它理解成给 AI 装的一本岗位说明书——它不改变 AI 的智力，只改变 AI 在这个特定任务上的做法。[7]

所以装 Archify 不是「装一个软件」，是往你的 AI 工具里放了一份说明书加一套渲染器。

「源文件」和「成品」是什么，为什么你必须知道有这个区分

这是全篇最该记住的一处机制。每次生成，AI 会先产出一份 JSON 文件——JSON 是一种给人看也给程序看的纯文本数据格式，长这样（这是项目自带的一个真实示例的片段）：

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "participants": [
    { "id": "user",  "label": "User",    "sublabel": "browser session" },
    { "id": "api",   "label": "API",     "sublabel": "request handler" },
    { "id": "redis", "label": "Redis",   "sublabel": "cache" }
  ],
  "messages": [
    { "from": "api",   "to": "redis", "label": "read cache" },
    { "from": "redis", "to": "api",   "label": "miss" }
  ]
}

看不懂语法没关系，你只需要看出来一件事：它是能读的。「API 向 Redis 读缓存，Redis 回了 miss」——这句话在文件里就是一行，谁都念得出来。

这份文件才是「图的真相」。成品 HTML 只是它的一次渲染结果。这个区分带来三个实际好处：

五种图，其实就是五种问题

Archify 只做五种图。别把它当成「五种样式」——它是五种不同的问题，选错类型，图再漂亮也答不了你的问题。

还是不确定？它自带一条「问它选哪种」的命令，把你想画的场景描述给它，它返回推荐的类型和一份可以直接用的提示词：

node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --lang zh

# 本文作者本机实测的输出（节选）：
#   recommendation.type = "sequence"
#   问题："谁调用谁、顺序如何、最终返回什么？"
#   适合："API 文档、请求耗时排查、鉴权评审和缓存回退说明。"
#   别用："如果顺序不重要，受众只需要稳定的服务拓扑，请用架构图。"

02它替你解决的三个麻烦

这一节是对着一种具体的处境写的：你在互联网行业做事、但不写代码；手上有几个半途停下的项目；AI 给的建议你判断不了，因为它说得头头是道，而你只被专业名词挡在外面，最后只能照做。Archify 不会让你一夜之间看懂代码，但它能在这三处给你一个能抓的东西。

麻烦一：AI 说得头头是道，你没有依据判断

真实场景长这样——AI 看完你的项目，说：

这几句话对不对？你没有能力判断。你只能点点头，然后看着它动手——这正是你在别处反复遇到的处境。

Archify 在这里的作用不是「替你做判断」，而是把一段你没法反驳的话，变成一张你能指着问的图：

要诚实地说清楚：这不等于你获得了技术判断力。它只是把你从「没有抓手」变成「有一个抓手」。但对你现在的处境，这一档差别很实在——它把「只能照做」换成了「至少能问」。

麻烦二：半成品项目，连你自己都说不清里面有什么

这是 Archify 最贴合你的一处。项目 README 的第一句卖点是「不需要绑定代码库」，而你的情况恰好相反：你有代码库，但你读不动它。

停下来的项目最难受的地方不是「没做完」，是回去的时候不认识它了。隔了六周再打开，满屏文件，你忘了当初为什么这么分、哪两块是连在一起的、哪个是你当时正在纠结的地方。

这时候让 AI 读一遍仓库、出一张总览图，你面对的就不再是「一整个看不懂的项目」，而是：

麻烦三：要讲给别人听

给同事对齐、给老板汇报、给外包交代——你现在大概是用一段话，或者一堆截图。Archify 的成品是一个 HTML 文件：发过去，对方双击就能开，不需要装任何东西，也不需要联网。

更好用的是带视角的链接。它的地址栏支持这样一串参数：

图.html#focus=api                     # 打开就聚焦在 api 这个节点上
图.html#focus=api&reach=downstream     # 聚焦 api，并点亮它下游的所有东西
图.html#route=web~db                  # 点亮从 web 到 db 的这条路径

# 把这样的链接发给别人，他点开看到的就是你想让他看的那个视角，
# 不用再附一段解释。这是它 README 里列的「稳定链接」。

它解决不了什么（三条硬边界）

不写清楚这一节，你迟早会把期待放错地方。

03什么时候该用它、用哪一种

它的每一次生成都要花掉模型不少力气，所以「该不该用」比「怎么用」更值钱。这一节给一张对照表：你想问的问题长什么样 → 该用哪种图 → 该说哪句话。

十二个现成配方：照抄就行

Archify 内部带 12 个「配方」——针对 12 种常见场景，各自给出「适合什么、别用在什么上、提示词里必须出现什么」。下表是从它本机的配方文件里导出的中文原文，「说什么话」那一列可以直接复制给 AI。[1]

什么时候别用它

04装好它：一条命令，三个前置

前置一：Node.js 是什么，为什么它必须先在

Archify 的渲染器是一段用 JavaScript（一种编程语言）写的程序，要靠 Node.js 才能在终端里跑起来。Node.js 你不用懂——它就是一个让这类程序离开浏览器也能运行的环境，装一次，以后很多工具都靠它。

node --version
npm --version

# 本文作者本机：v24.19.0 / 12.0.2，doctor 自检 20 项全绿。
# 要求是 Node.js >= 18（项目 doctor 命令会明写这一条）。
# 没装：去 nodejs.org 下 LTS 版（长期维护版）；
# macOS 上也可以用 brew 装（brew 是 macOS 上的软件安装命令行工具）：brew install node。

前置二：一个 AI 编程工具

Archify 是技能，技能要有地方挂。你可以先看一眼自己电脑上有没有现成的技能目录（有目录说明工具已经装好了）：

ls ~/.claude/skills          # Claude Code 的全局技能目录
ls ~/.agents/skills          # Codex CLI 的全局技能目录
ls ~/.config/opencode/skills # OpenCode 的全局技能目录

# 任何一个存在（哪怕里面是空的），对应的工具就能装 Archify。
# 本文作者本机：前两个都在，里面各有几十个技能；OpenCode 目录不存在。

前置三：一个终端

就是那个能粘命令的窗口。整件事里你只需要往它里面粘两条命令，其余全在聊天窗口里完成。

装：一条命令

# 推荐：交互式安装，会让你选装到哪个 Agent、要不要软链接
npx skills add tt-a1i/archify -g

# 想省掉所有问答、一条命令装到指定工具（这里以 Claude Code 为例）：
npx -y skills add tt-a1i/archify --skill archify --agent claude-code --global --copy --yes

# 只想临时试一次、不落到硬盘上：
npx skills use tt-a1i/archify@archify --agent codex

这里的 npx 是 Node 自带的一个「临时取来就跑」的命令；skills 是一个开放的技能生态命令行工具（npm 上的包名就叫 skills，本文校对时最新版是 1.7.0，来自 vercel-labs）。-g 是「装到全局」——意思是这个技能对你所有项目都生效，而不只是当前这个文件夹。[12]

npx -y skills add tt-a1i/archify --list --full-depth

装到哪儿：按你的工具选

装完怎么确认：两条自检命令

装好之后，进到 Archify 那套文件所在的目录（就是技能装进去的那个文件夹），跑这两条：

node bin/archify.mjs doctor        # 检查环境与文件是否齐全
node bin/archify.mjs demo /tmp/archify-demo   # 生成一套示例图

本文作者本机实测输出：doctor 打印 20 行 [ok]，从 [ok] Node.js v24.19.0 (requires >=18) 一路到五种渲染器全部就绪，最后一行是 Archify is ready.。看到这一行，就说明装好了。

装的时候会踩的三个坑

05说什么话让它开工

装好之后最现实的问题是：我到底该说什么？这一节给四种起手方式、一个句式骨架，和一次生成会在硬盘上留下什么。

四种起手方式

四条可以直接复制的开场白

【1】有代码，要看系统总览（最常用）
分析这个仓库，然后用 Archify 生成高层系统架构图。展示 8–12 个核心运行时组件、
一条主要请求或数据路径、外部依赖、归属或信任边界；支持性细节放进卡片，
不要继续堆连线。生成后告诉我源文件和 HTML 的完整路径。

【2】没有代码，只有一段想法
用 Archify 画出一个网站的请求流程：浏览器请求 API，API 优先读取 Redis，
缓存未命中时查询 PostgreSQL 并回填缓存。

【3】要讲给别人听（一张有顺序的流程图）
用 Archify 工作流模式绘制从代码提交到生产发布的流程。拆分开发者、CI、审批、
环境和异常泳道；标出阻断检查、冒烟测试、负责人和回滚路径，
并保留一条一眼可见的成功主路径。

【4】图已经有了，但太挤/线穿过框
用 Archify 修复这张现有图，保留图表类型、拓扑、有意义的标签和表现设置。
按顺序修：schema 错误 → 节点重叠或越界 → 线穿过节点、端点方向错 →
交叉与绕行 → 标签间距。每次修改后运行 validate，依据诊断里的 code 和 subject，
每次只改一项有依据的几何问题。

一次生成会在硬盘上留下什么

技能手册里规定了一个固定做法：每个新请求单独开一个文件夹，名字里带类型和时间戳。[2]

.archify/
└── architecture-my-project-20260930-171500/
    ├── candidate.json      ← 源文件：图上的每句话都在这里
    ├── my-project.html     ← 成品：双击就能开的那张图
    ├── my-project.delivery.json        ← 交付回执（记录这次交付结果的清单）
    └── my-project.finalize-summary.json ← 校验摘要

为什么你要在意这个目录结构：它决定了「改图」这件事的性质。因为每个版本有自己的文件夹，你上次生成的那张图不会被覆盖掉。改错了，上一个版本还在原地。这也解释了为什么迭代很便宜——AI 改的是同一份 candidate.json，不是从头重画。

06图出来之后：看、改、交出去

它不是一个静态图片，而是能点的

双击打开那个 HTML，你会看到一个带工具栏的页面。下面这些键是项目文档里列的正式快捷方式，都值得试一遍。[1]

改图：继续说人话就行

增加 Redis
把鉴权移到左侧
突出回滚路径
切换浅色主题
把「用户中心」这个名字改成「账号服务」

技能手册对外的说法是：它保留源文件，只修改相关部分。所以这些改动是局部的——挪一个框不会牵动其他框。这是它和个人画图工具最不一样的地方。[1][2]

交出去：四种东西，四种场合

关于「离线可用」这件事，本文作者做了一次实测，结论比 README 的说法更具体：

你不写代码，怎么判断这一次生成成功了

项目自己的技能手册规定，AI 收尾时必须回报五样东西：成品文件的绝对路径、图类型、校验摘要、规格与成品的回执、浏览器证据状态和真实的视觉复核状态。手册里还有一句硬话：不许把非零的退出码说成成功。[2]

所以你可以直接用下面这句话验收——它把一句含糊的「好了」变成一个有明确答案的问题：

这次校验是 9 项全过、还是只过了前 4 项？把 composition 里的
errors 和 warnings 各是多少报给我。另外，源文件和 HTML 的完整路径分别是什么？

# composition 是回执里「构图检查」那一段的字段名，
# errors / warnings 是它数出来的错误条数和警告条数。

07最小例子：拿一个停了六周的项目走一遍

下面这一次完整的走查，用的场景就是你的处境：一个六周没碰的副业项目，代码还在，但你已经说不出它里面有什么了。

第 0 步：先认一件事

第一次不要问「帮我把我的项目画出来」。问题太大，AI 只能把知道的全画上，你会得到一张密密麻麻、什么都看不清的图，然后还得重来一次——重来一次就是再花一次钱。这是博客园那位实测者踩过的坑，也是 §02 里那条「投入不小」的代价最容易被浪费的地方。

先花两分钟回答一句话：

第 1 步：把范围钉死，然后把话说给 AI

在项目目录里打开你的 AI 工具（或者是让它进到这个目录），把这句发过去：

分析这个仓库，然后用 Archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，突出一条主要路径，标出外部依赖与信任边界。
支持性细节放进卡片，不要继续增加连线。
哪些部分是你从代码里读出来的、哪些是你推断的，生成后分别告诉我。
最后回报源文件（JSON）和 HTML 成品的完整路径。

这段话里每一句都有用：「8–12 个」给了它取舍的依据；「一条主要路径」逼它分主次；「细节放进卡片」防止它用连线淹没你；「哪些是推断的」给了你验收的抓手；「回报完整路径」解决你找不到文件的问题。

第 2 步：等它干完，然后核这三样

第 3 步：打开图，做三件小事

# ① 按 / 搜一个你记得的模块名，看它是不是在图上
#    在 → 图至少没漏掉你知道的东西；不在 → 直接问 AI「为什么没有 X」

# ② 点中它，看 Upstream / Downstream
#    这里是你最容易发现问题的地方：图上说它连着某样东西，
#    但你记得不是这样 —— 记下来，这就是你的第一个「可核对的问题」

# ③ 按 R，试着点出一条从入口到数据库的路径
#    走不通的地方，往往就是当初没做完的地方

第三步最有价值的地方在于：你不再需要「读懂代码」才能发现问题，你只需要「记得当初大概是怎么回事」。记得起来的部分和图上对不上，那就是问题。

第 4 步：本文作者实测的那一次，以及它失败的地方

本文作者在自己的机器上把这条链路真跑了一遍。结果里有一条，比所有「一切顺利」的教程都有用：

第 5 步：验收完成的样子

走完这一遍，你手上应该有两样东西：一张能点开的图，和一句话——「这个项目主要分成这几块，中间那条主路径是从哪到哪」。

如果你现在能对着一个没读过这个项目的人，用三五句话说清楚「它大概是怎么回事」，那这一步就完成了。说得出来 = 这篇讲的东西真的落地了。

08机器校验挡得住什么、挡不住什么

这一节是整篇里最该慢慢读的一节。因为「可验证」是 Archify 最大的卖点，而卖点被理解过头的时候最危险。

那 9 项检查，一项一项是什么

本文作者把 9 项检查的名字直接从它本机的检查命令里导了出来。它们全部是几何与结构层面的：[13]

看完这份清单，你自己就能得出那个结论了：

三个真实的反例：9 项全过，图却是错的

这个说法不是我推的。Archify 项目自己的 issue 列表里就挂着这样的例子——下面三条在本文校对时都还是开着的：[11]

还有一条不同性质的，也值得知道：#590——大工作流会让校验报告本身超出缓冲区，导致校验直接失败。这不是图画错了，是工具在规模变大时自己绊倒。本文校对时它同样开着。也就是说：如果某天你对一个很大的系统跑校验、得到一条看起来莫名其妙的失败，先怀疑规模，别怀疑自己。[11]

项目自己怎么说这件事

它没有藏着。交付契约里有两句话，本文直接翻译过来：[5]

翻译成人话：机器能替你排除的是「图坏掉了」；机器不能替你排除的是「图讲错了」。前者它做得比人可靠得多；后者从头到尾都是你的活。

所以验收该问什么：三句可以照抄的话

【问机器那部分】
这次校验是 9 项全过还是 4 项？构图检查（回执里叫 composition）
里 errors 和 warnings 各是多少？

【问事实那部分】
图上这几条线，分别对应代码里的哪个文件、哪一行？请你逐条列出来。
（有源码依据时，节点上会出现 SRC 标记——SRC 是 source（源码）的缩写——
并且能点开到固定版本的文件与行号。）

【问责任那部分】
这张图里哪些是你从代码里直接读出来的、哪些是你推断的？把推断的标出来，
或者直接在图上把它们区分开。

第三句是这三句里最值钱的。因为它把「我信不信这张图」这个没法回答的问题，换成了「哪几处需要我另行确认」这个能执行的清单。[2]

09上手之后才知道的坑

下面六个问题，前三个你一定会遇到，后三个是该提前知道的。都来自真实记录，不是假设。

坑 1：装不上 / 敲了命令提示找不到

坑 2：AI 交回来的图密密麻麻，什么也看不清

这是最高频的一条，而且原因百分之百在提示词上。真实用户的总结原话：「画真实项目的时候别贪多。第一次让它扫仓库，一口气让它画了所有组件，出来的图密密麻麻没法看。」[9]

对策就是那句句式：「只保留 8–12 个核心组件、一条主路径，其余放进卡片。」数字 + 主次 + 出口，三个都要给。不要用「简洁一点」这种形容词——那不是取舍依据。

坑 3：最后一步报错，但不知道是环境还是图的问题

本文作者实测就遇到了（§07 第 4 步）。区分方法只有一个：看诊断里的词。

坑 4：很慢、很费 token

这是有记录的真实代价。项目 issue #22「太费 token 了，画个架构图消耗 minimax m3 几十兆 token」（token 是 AI 处理文字和计费的计量单位，你在账单上看到的就是它）、#66「整个过程很慢，而且 token 消耗很大」。量子位报道里也提到读者反馈「消耗额度有点大」，作者当时的回应是正在攻这个问题。[8][11]

三条能立刻减少消耗的做法：① 缩小范围——一次只画一部分，别整个仓库一次画完（这也让图更好看）；② 用纯描述起手——让它读一整个仓库是最贵的方式，如果只是想验证一个想法，描述就够了；③ 一次说清要求——「只保留 8–12 个、一条主路径、其余放卡片」提前给，比出图之后再改四五轮的代价低得多。

坑 5：图出来了，但内容不对

先别怪工具。按这个顺序排查：

坑 6：用网页版 AI，能力对不上

如果你用的是 claude.ai 网页版或「项目知识」，走的是降级路径：把自带的 archify.zip 上传，然后靠提示词驱动。这条路能不能跑通，取决于它背后的沙箱给不给 Node 环境——给不了就只能出「提示词驱动的架构图」，不是完整的渲染加校验流程。想要完整能力，你手上必须有一个能在终端里跑的 AI 编程工具。[1]

10一页纸：命令、参数、验收话术

命令速查

两个参数要知道

验收三句话（直接复制）

1. 问机器
这次校验是 9 项全过还是 4 项？composition 里 errors 和 warnings 各是多少？

2. 问事实
图上这几条线，分别对应代码里的哪个文件、哪一行？逐条列出来。

3. 问责任
哪些是你从代码里直接读出来的、哪些是你推断的？把推断的标出来。

「什么时候别用它」四问

11名词速查

这篇里出现过的、不属于日常用语的词。第三列是「什么时候用得上它 / 别把它当成什么」——只给中英对照的翻译表对读文章没有帮助。

98来源与证据边界

一手来源

99一句话总结

留给你自己验的那一条

前面所有内容你都能在文章里找到答案，只有这一条不行——它需要你自己的场景。请做一次：

挑一个你手上半途停下的项目，先写下那句话：「这张图给谁看、他看完要能回答哪个问题。」然后按 §05 的句式【1】把提示词改写成适合你这个项目的版本——把「8–12 个核心组件」换成你项目的说法，把「一条主要路径」换成你真正想知道的那条路径。

例如：「我要看清楚用户从注册到第一次成功下单这条路上到底经过了哪些东西」——那就把提示词写成「只保留这条路上的组件，其他的一律放进卡片，连一条线都不要加」。

如果你写完发现自己答不出「给谁看、回答什么问题」，那正是一个有用的结果：说明你现在的第一步不是让它画图，而是先想清楚要拿这张图干什么。按 §03 最后一条「别用它」的对策处理——这张图的一次生成不便宜，先花两分钟想清楚，比画完再重来划算得多。