把程式码库变成可验证的系统地图：Archify 如何让 AI 生成的架构图不只好看

当团队请 AI「画一张系统架构图」时，最常见的结果不是不能看，而是不能信：元件可能漏掉，箭头可能只是视觉上的猜测，图表更新后也很难知道到底改了什么。tt-a1i/archify 选择的路线不同。它不是另一个 Mermaid theme，也不是一般绘图编辑器，而是一个让 coding agent 产生 typed JSON intermediate representation（IR），再由 Node.js 工具链以可重现方式验证、编译成 HTML/SVG 的 Agent Skill。

本文以 GitHub 上的 Archify 原始码与官方文件为查证基础，拆解它的工作模型、验证闸门、互动式阅读方式，以及它适合放进日常开发流程的原因。文中的指令与功能描述以 2026 年 9 月 11 日查询到的 main 分支与 README 所列的 v2.17.0-dev.1 为准；GitHub 星数会随时间变动，当时约为 58,020 颗。

先说结论：Archify 解决的是「沟通可信度」

Archify 的核心价值不在于把方块排得更漂亮，而在于把「图上宣称的关系」变成可检查的资料。它的流程可以浓缩成五步：

1. Agent 根据描述或 repository source 产生 typed JSON IR。

1. Validator 检查 schema、layout、HTML/SVG、route 与标签和路线的间距。

1. 通过检查的 IR 被渲染成 self-contained HTML，并可汇出 PNG、SVG、WebM 或 1200×630 share card。

1. 使用者在图上搜寻节点、追踪 authored upstream/downstream reach、检查精确路线，或播放有限的 guided story。

1. 下一次修改只替换通过验证的产物；若候选版本失败，预览仍保留上一个 last-good artifact。

这个设计把 AI 的不确定性放在「产生候选 IR」阶段，并把交付责任交给 deterministic checks。它不会让 AI 自动知道线上系统的真实流量，也不会凭空推论风险；它只呈现已被写入并通过规则检查的拓扑。

安装：把 Skill 接到 coding agent

Archify 的 README 提供最短安装路径：

npx skills add tt-a1i/archify -g

官方列出的整合对象包含 Cursor、Claude Code、Codex CLI 与 OpenCode。若只是想试用，也可以不先安装到全域环境：

npx skills use tt-a1i/archify@archify --agent codex

安装完成后，不需要先准备一个 repository 才能开始。直接在 Agent 对话中描述系统即可：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

如果需要 source evidence，则先开启 repository，再要求 Agent 分析原始码并建立 high-level runtime architecture diagram。官方 quick start 建议限制核心元件数量、指定 primary path、外部依赖与 trust boundaries，并把支援细节放进 cards，而不是无限制增加连线。

五种图表类型，对应五种问题

Archify 没有把所有东西都塞进同一种 architecture diagram，而是把阅读目的拆开：

Architecture：回答有哪些元件、服务、储存与边界。
Workflow：回答 CI/CD、审批、工具呼叫与 runbook 的顺序、分支和例外。
Sequence：回答一次 API 呼叫、cache fallback、认证或非同步互动如何随时间展开。
Data Flow：回答资料从哪里来、如何转换、存在哪里，以及 PII 或其他敏感边界在哪里。
Lifecycle：回答状态、等待、重试、取消与终止结果如何流动。

这个分法很实用。若把部署拓扑、请求时序、资料血缘与失败重试全放在一张图，读者最后通常只剩下「看起来很复杂」的印象。先决定要回答的问题，再选 diagram type，才有机会把图变成沟通工具。

验证闸门：漂亮不是交付条件

Archify 的 README 把 validation 描述成 atomic validation before delivery。实际工作流不是「render 一次就完成」，而是候选结果必须依序通过规则，才会取代最后一个可信版本。常用指令如下：

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

失败时，validate --json 与 deliver --json 回传包含 stable rule code、subject、measured evidence 与 supported fixes 的诊断资料。这一点比直接看到 Node stack 或让 Agent「再试一次」更重要：修复动作被限制在诊断明确支援的范围内，而且官方文件也要求视觉检查另外进行，不把自动规则当成设计审查的替代品。

Archify 也提供 preview 模式。它只在 loopback 介面监看单一 JSON 档案，候选版本通过所有闸门后才重新载入；若储存内容不完整或验证失败，画面维持上一个 verified diagram。对正在修改架构图的开发者来说，这比预览画面闪成半成品更适合长时间迭代。

Architecture Delta：把 PR 审查从「找差异」变成「读变更」

架构图最容易失效的时刻，往往不是第一次产生，而是系统改版之后。Archify 的 Architecture Delta 接受 validated Before、Delta、After snapshots，将变更整理为 added、removed、changed、moved 与 rerouted facts，并产出 machine receipt。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

这不等于自动判断「这个 PR 安全」或「这个改动一定会影响哪个服务」。Archify 明确把 impact、risk 与 merge safety 留在使用者判断范围内。它做的是把 authored facts 的差异整理干净，让审查者先看变更本身，再决定要追哪些程式码、测试与部署证据。

互动功能的关键：不虚构拓扑

静态图片只能展示结果，Archify 的互动 viewer 则把阅读操作限制在已编写的节点与关系上。README 列出的功能包含：搜寻 nodes、开启 revision-verified source、追踪 authored upstream/downstream reach、检查 exact routes、比较 semantic roles，以及播放有限的 named chapters。

这里的限定词很重要：是 authored reach，不是 runtime impact；是 exact route，不是模型临场补出来的可能路径；是 revision-verified source，不是模糊地附上一个 repository 连结。当图表缺少 deployment ownership、region placement、private database scope 或 named crossings 时，deployment-ownership profile 会 fail closed，而不是自行假设答案。

官方 Proof Lab 目前包含 11 个 checked-in scenarios、JSON source、named views 与 validation receipts。这些范例可以用来观察同一份结构如何支援 guided story、route probe 和 semantic lens，而不必把每一种阅读目的重新画一张图。

从 repository 取证：有边界地使用 AI

如果要让图表包含原始码证据，Archify 的设计是将 Architecture nodes 标记为 SRC n，再开启固定在单一 public commit 的 Git-verified files 与 line ranges。这种做法适合 code review 或 onboarding，因为读者可以从图上的元件回到具体档案与行号。

但它仍然不是 runtime observability。即使 source analysis 找到一条函式呼叫链，也不代表线上所有流量都会经过那条路；即使图表通过 validator，也不代表部署环境的权限、网路政策或资料品质已经被验证。比较稳妥的做法是把 Archify 当成 source-grounded communication artifact，并在文章、PR 或设计文件中清楚标示查证的 commit 和范围。

一个适合团队落地的最小流程

可以从一个不依赖真实 repository 的小案例开始：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

接着采用以下节奏：

1. 先用一句话定义图表要回答的问题。

1. 在对话中生成第一版 typed JSON IR。

1. 用 validate --json 取得可机器处理的诊断。

1. 只依 diagnostics[] 里的 supported fixes 修复，并保留修复轮数上限。

1. 以 deliver 产生与 JSON 同目录的 HTML，提交 JSON 与 validation receipt。

1. 让 reviewer 进行独立的视觉检查与 source review。

1. 下一次改动以前一版 validated snapshot 作为 Before，产生 Architecture Delta。

这套流程特别适合需要跨职能沟通的情境：后端工程师可以检查 route，平台工程师可以检查边界，产品或管理者则可以用 guided story 先理解主流程，而不必先读完整个 repository。

限制与采用前检查

Archify 的限制同样值得写进评估报告：

它不是 general-purpose drawing editor，不能取代需要自由绘图的工具。
它不会自动读取 live infrastructure，也不应被当成 runtime topology 或 impact analysis 系统。
deployment-ownership 等严格 profile 可能因证据不足而拒绝交付；这是 fail closed 的预期行为，不是单纯的 UI 错误。
图表品质仍取决于 prompt、source 范围与 authored IR；deterministic renderer 能稳定地呈现输入，不能替团队补上不存在的架构决策。
README 所列版本为 development version，导入正式流程前应锁定版本，并在 CI 中保存 JSON、receipt 与输出档案。

结语：让架构图成为可审查的产物

AI 生成架构图真正的问题，从来不只是排版。当图上的箭头会被误读、系统改动没有可比较的基准、预览会展示未完成的候选内容时，团队需要的是一个对「哪些事可以宣称」有明确边界的工具链。

Archify 的答案是 typed JSON IR、deterministic rendering、atomic validation、last-good preview 与 source evidence。它没有承诺替你理解所有线上行为，反而把这个限制说清楚。对正在使用 Cursor、Claude Code、Codex CLI 或 OpenCode 的团队而言，这种「让 Agent 产生候选、让规则决定能否交付」的模式，比单纯追求一张更华丽的图更值得借鉴。