archify 深度解析：7.7 万星的 Agent Skill，把架构图变成可交互 HTML
archify 深度解析：7.7 万星的 Agent Skill，把架构图变成可交互 HTML
架构图最贵的成本从来不是画，是改完之后没人敢信它还是对的。
给 Agent 写提示词让它画架构图，这件事早就不新鲜了——让它输出一段 Mermaid，十秒钟就有了。问题是三周后：代码改了三个服务，图还在原地；新人问"这个箭头到底走不走数据库"，图上只有一根线，没有答案；review 时你说"这条路径我捋一遍"，只能截图加红框。
archify 走的是另一条路。它不生成 Mermaid，也不做一个画图 SaaS，而是让 Agent 产出一份类型化的 JSON IR，再把它渲染成一个自带交互、可独立打开的 HTML 文件，并且在交付前必须通过一串校验门禁。截至 2026-10-05，这个仓库有 77,471 stars、5,212 forks、203 个 open issues，MIT 许可，当前稳定版 v3.0.1（2026-09-28），skills.sh 上标注 130K+ 安装量。作者在 9 月 1 日晒出过 GitHub Trending 周榜（全语言）第一的截图，量子位也做过项目报道和开发者访谈。
这篇文章拆它的设计和工程取舍：为什么"类型化 IR + 交付门禁"比"让模型直接吐 SVG"更靠谱，它的交互能力边界在哪，以及什么场景下你不该用它。
本文提纲
- 它到底是什么：一个 Skill，不是画图工具
- 五种图类型与"从代码里取证"
- 真正的护城河：四道交付门禁与可修复的失败
- 交付物本身：一个会回应的 HTML
- 和 Mermaid、通用画图工具的分工
- 安装、上手与成本边界
它到底是什么：一个 Skill，不是画图工具
archify 的定位很明确——它是给编码 Agent 用的 Skill。安装只有一行：
npx skills add tt-a1i/archify -g装完之后你不需要记任何 CLI 参数，直接用自然语言提需求：
Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.对真实仓库则换一种说法：
Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8-12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.它支持 Claude Code、Codex CLI、Cursor、opencode，也有 DeepSeek Harness 的社区集成（dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0）、Hermes Agent 和 Kimi Work 插件商店的入口。这一点值得单独说：**它把"生成能力"寄生在宿主 Agent 上，自己只负责"表达 + 校验 + 渲染"。**你不用学一套新的图定义语言，也不用在 IDE 和画图网站之间来回复制粘贴。
产出物是一份自包含 HTML。收图的人不需要装任何东西，双击就能看；发给同事，交互也跟着走。
五种图类型与"从代码里取证"
它把"想表达什么"收敛成五种类型，每种都有独立 schema，避免"一张架构图装下所有事"：
| 类型 | 适合表达 | 提示词里该给什么 |
|---|---|---|
| architecture | 组件、服务、存储、边界 | 范围、核心组件、主路径 |
| workflow | CI/CD、审批、工具调用、runbook | 参与者、顺序、分支、异常 |
| sequence | API 调用、缓存回退、鉴权、异步链路 | 调用方、被调方、返回、时序 |
| dataflow | 管线、血缘、PII、消费方 | 数据源、变换、存储、边界 |
| lifecycle | 状态机、重试、等待、终态 | 状态、事件、重试与取消路径 |
挑不准时可以让 CLI 帮你判：
node bin/archify.mjs guide "Show an API request with Redis cache miss"
node bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json更有意思的是它的仓库取证能力。当图需要反映真实代码时，节点可以标记 SRC n，点击直接打开 Git 校验过的文件与行号区间，并且锁定在一个公开 commit 上；官方示例是把 mco-org/mco 追溯到 9f1a1cf 后产出的运行架构图。普通（非取证）产物则保持 source-free，不硬塞来源。
这个设计解决的是架构图最常见的信任问题：图上的每个组件，能不能回答"你凭什么这么说"。它没有让模型自由发挥，而是把证据锚定到 commit。
真正的护城河：四道交付门禁与可修复的失败
如果只让模型输出 HTML，你迟早会遇到"图是生成了，但标签压线、箭头乱飞、点开报错"。archify 把交付做成了一个有门禁的流水线：schema 校验 → 布局规则 → HTML/SVG 结构 → 路由与标签避让 → 真实浏览器检查，全过才算成功。
graph LR
A[Typed JSON IR] --> B[Schema validation]
B --> C[Layout rules]
C --> D[Render HTML and SVG]
D --> E[Route and label clearance]
E --> F[Real browser check]
F -->|pass| G[Atomic replace last known good]
F -->|fail| H[Repair receipt with rule codes]
H --> A几个细节决定了它比"让模型重画一遍"高明：
- 原子替换：只有通过全部门禁的产物才会替换上一个"已验证版本"。中间失败一次，用户看到的还是上一版能用的图，而不是半成品。
- 失败带修复清单：
validate --json和deliver --json返回的是稳定的规则码、具体出错对象、量测证据，以及只包含受支持修复方式的清单，而不是一段 Node 报错堆栈让你猜。修复还有轮次上限，避免 Agent 无限重试。 - 可选实时预览：
preview起一个只监听回环地址的桌面会话，盯着一个 JSON 文件，只在最新候选通过全部校验后才刷新；保存到一半或写错时，屏幕上留着的仍是上一张正确的图。
这套机制的代价也很实际：它要求 Agent 先写 JSON 再渲染，比"直接吐 Mermaid"多一步；而且 JSON 的 schema 一旦选错字段，报错会落到你头上。换来的是可复现、可 diff、可校验——同一份 JSON 渲染出来的东西是确定的，这恰好是"图要被 review、要被版本管理"所需要的属性。
顺带一提它还有个 compare 子命令：把 Before / Delta / After 三份快照做成 Architecture Delta，并输出机器可读的 receipt。它明确声明不推断影响面、风险或合并安全性，只呈现被作者声明的事实变化（新增、删除、修改、移动）。这种"不越界承诺"的克制，在架构工具里很少见。
交付物本身：一个会回应的 HTML
静态图的问题是"你只能看"。archify 的产物把追问做成了内置能力，键盘直接驱动：
| 操作 | 快捷键 |
|---|---|
| 打开发图指南 | ? |
| 搜索并聚焦某个语义节点 | / |
| 追踪上游/下游可达路径 | 聚焦节点后 Upstream / Downstream |
| 探针式追踪一条有向路径 | R 或 PATH |
| 对比一到两个语义角色 | L 或 LENS |
| 打开全局雷达视图 | M 或 MAP |
| 进入演示模式 | F |
| 切换视觉风格 / 主题 / 导出 | S / T / E |
这些状态都能变成稳定深链：#focus=<id>、#focus=<id>&reach=upstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind>。也就是说，"看这里"这件事从口头描述变成了可以贴进工单和聊天窗口的 URL。
导出也做了分层：Export 菜单里可以复制 PNG 到剪贴板、下载静态或动效格式；追完一条路径后可以导出 Route Share Card（1200×630，保留完整图作为上下文），追完可达范围可以导出 Reach Share Card——而且在命名上明确区分"作者声明的可达"与"运行时影响"，不暗示后者。
动效是可选开启的（meta.animation: "trace"），且遵守 prefers-reduced-motion；动效永远不会进入正式导出物。这个细节说明作者分得清"演示效果"和"交付文件"。
和 Mermaid、通用画图工具的分工
README 把边界写得毫不含糊，而这恰恰是最值得借鉴的部分：
- 它不是通用画图编辑器，也不是 Mermaid 主题。没有 WYSIWYG，不做托管分享。
- 它接受粘贴 Mermaid 作为输入语义（flowchart/graph、sequenceDiagram、stateDiagram 分别映射到 workflow 或 architecture、sequence、lifecycle），但不做机械解析和样式复刻——读的是拓扑与含义，然后重新写成 archify 的 JSON。
- 通用自动布局不在范围里。它选择让 Agent 做布局判断：层次、间距、走线、强调，共享的自动端点会确定性分散，而不是把箭头全堆在同一个中点。路线冲突时还有专门的修复流程，但只允许改"节点的位置与尺寸"，节点、关系、标签、来源一个都不许动。
这就解释了一个常见的误判：把 archify 当成"更漂亮的 Mermaid"会失望，因为它的价值不在渲染，而在用类型化 IR 把技术意图固定下来，再让校验门禁保证它没被画歪。
安装、上手与成本边界
安装方式按宿主不同：
# 通用（Claude Code / Codex / Cursor / opencode）
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迭代发生在对话里：add Redis、move auth to the left、highlight the rollback path。因为类型化源文件一直在，改动可以定点进行，而不是每次重建整张图。
几条需要提前知道的边界与成本：
- 隐私与网络：更新检查只会 GET 一个固定的 stable manifest，用于显示可选的升级提醒；不发送版本号、Agent 信息、项目数据、prompt、账号或设备 ID，也不带 ETag。设
ARCHIFY_UPDATE_CHECK_DISABLED=1可以彻底关掉网络请求与状态写入。它从不自动安装更新。 - 节点数不是目标也不是上限：官方在 Skill 里明确写了"没有节点数、关系数、卡片数、边界数的目标或上限"，避免为凑数量堆组件。
deployment-ownership这类 profile 是 fail-closed 的：缺少作者声明的 owner、区域放置、私有数据库范围或命名跨域关系，直接判失败；它也不会去探测真实基础设施。- 本地化：
meta.locale内置en与zh-CN，其他语言（例如西班牙语）需要在meta.translations里给映射，否则回退到英文并明确告知发生了回退。 - 它不替你做决策：Delta 不推断风险，Reach 不声称运行时影响，Mermaid 输入不保留原样式。想要"图自己告诉我哪里会挂"，它不会接这个活。
适合它的场景很具体：需要被别人读懂、还要在改动后继续可信的图——新项目的运行架构、跨服务的调用链路、上线与回滚流程、数据血缘、以及 review 时要反复引用的路径。如果你的图只活在一次性汇报的 PPT 里，Mermaid 更省事。
顺带说一句：archify 也是这个项目正在用的能力之一——如果你在自己的仓库里装它，第一个值得画的图往往是"这个仓库是怎么跑起来的"，画完你大概率会发现两三个自己都忘了的依赖。
参考链接
- GitHub: tt-a1i/archify — 77,471 stars、5,212 forks，MIT 许可，v3.0.1
- 官方站点与交互示例 — 含 Proof Lab、场景指南与 11 个已校验场景
- Archify 中文 README — 中文说明与更新
- Skill 契约文件 archify/SKILL.md — 生成与查看器的完整契约
- Schema 参考 — 五种图类型的 schema 与字段约束
- Agent cookbook — 提示词与编写实践
- DeepSeek Harness 集成说明 — DSH 插件安装与限制
- MCO 运行架构案例 — 从公开仓库取证生成的示例
- 上海 CityWalk 社区作品 — 非技术场景的用法示例
- Changelog — v3.0.1 及历史版本变更
你会把架构图交给 Agent 生成吗？更在意"画得快"还是"改完还准"？评论区聊聊你的做法，觉得有用点个赞让更多做系统设计的人看到。
作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top
本文首发于 AI人工智能时代，转载请注明出处。
