Carreyda
← 返回文章

一句话生成交互式架构图：Archify 上手指南

Archify 是一个开源（MIT）的 agent skill，可装进 Claude Code、Codex CLI、Cursor、OpenCode。用 npx skills add tt-a1i/archify -g 安装后，对 agent 说 Use Archify to ...，用自然语言描述系统、流程或代码仓库，它就生成一个可交互、自包含的 HTML 图，浏览器直接打开即可查看。

·5 分钟阅读

一句话生成交互式架构图：Archify 上手指南

画架构图最痛苦的不是画，而是改。需求变一次，图就要重新拖一遍。Archify 的思路是：把图交给 AI agent 来生成和迭代，你只负责描述和提要求。

Archify 是什么

Archify 是一个开源（MIT）的 ​agent skill​，可以装进 Claude Code、Codex CLI、Cursor、OpenCode 等 AI 编程助手。装好之后，你用自然语言描述一个系统、一个流程，甚至一份旅行计划，它会生成一个​可交互的、自包含的 HTML 文件​。

它不是 Mermaid 主题，也不是通用画图编辑器，而是把"技术意图"转成"可沟通的成品"：

  • 输出是单个 HTML，浏览器直接打开，发给别人交互也一起带过去
  • 内部先生成 typed JSON（IR），再经过校验和渲染，而不是让模型直接吐 SVG
  • 支持在对话里局部修改，其他结构保持稳定

支持哪些图

目前有 10 种类型：

类型 适用场景
Architecture 组件、服务、存储、边界
Workflow CI/CD、审批、tool call、runbook
Sequence API 调用、缓存回源、鉴权、异步链路
Data Flow 数据管道、血缘、PII、消费方
Lifecycle 状态、重试、等待、终态
ERD 数据库表结构、主外键、基数
Class 类、接口、继承与依赖
Tree 单父节点层级，如目录或能力拆解
Timeline 事故复盘、发布历史
Waterfall 一次请求或 agent 运行的耗时分布

不确定该选哪种时，可以用自带的 CLI 问一下：

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"

安装

需要 Node.js。一条命令：

npx skills add tt-a1i/archify -g

也可以手动放到对应目录：

工具 目录
Claude Code ~/.claude/skills/ 或 .claude/skills/
Codex CLI ~/.agents/skills/ 或 .agents/skills/
OpenCode ~/.config/opencode/skills/
Claude.ai Settings → Capabilities → Skills 上传 archify.zip

Claude.ai 网页版是否能跑完整的渲染和校验流程，取决于沙箱里有没有 Node.js。想要完整体验，建议用 Claude Code、Codex 或 OpenCode。

三种典型用法

1. 从一句话开始（不需要仓库）

Use Archify to diagram a web request: Browser calls the API,
the API checks Redis, and a cache miss queries PostgreSQL and fills the cache.

agent 会生成一份 Sequence 或 Architecture 图。之后继续说：

  • Add authentication
  • Highlight the cache-miss path
  • Switch to the light theme

2. 读代码仓库，生成有来源依据的架构图

在项目目录里让 agent 分析：

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.

几个提示词技巧：

  • ​限定节点数量​（8–12 个），否则图会变成一团线
  • ​指定一条主路径​，让图有叙事重点
  • ​细节放进 card​，不要都画成 edge

如果需要证据链，Evidence-backed 的节点会标 SRC n，点开能看到固定到某个 commit 的文件和行号。

3. 一页式回答（explainer）

不是所有问题都适合一张图。你可以让它"以一页的形式回答"：

Use Archify to answer as one page: our API's P99 went from 80 ms to 600 ms
while the mean barely moved. What is the likely cause, and how should we investigate?

得到的是：​结论先行​，然后每个问题一个 panel，里面可以有表格、步骤、图表、代码和校验过的图。步骤会和旁边的时序图联动高亮。

看图的时候能做什么

生成的 HTML 自带一套交互，这部分是 Archify 和"静态图片"最大的区别：

操作 快捷键
搜索并聚焦节点 /
追踪某节点的 Upstream / Downstream 选中节点后点按钮
路径追踪（A 到 B 的路由） R
对比角色（Lens） L
概览小地图 M
演示模式 F
切换样式 / 主题 / 导出 S / T / E
帮助 ?

这些视图还能通过 URL hash 分享，比如 #focus=<id>&reach=downstream、#route=a~b，对方打开链接就能直接看到你要说的那条路径。

导出支持 PNG、WebP、JPG 长图，也可以打印成 PDF，还有 Route Share Card（1200×630）方便发到文档或群里。

它为什么比"让 AI 直接画图"靠谱

从 README 描述的设计看，有几个工程上的取舍值得说：

  1. ​Typed JSON IR​：每种图都有 schema，源文件可复现、可 diff，局部修改不会把整张图推倒重来。
  2. ​交付前原子校验​：schema、布局、HTML/SVG、路由、标签避让都通过，才会替换上一份"最后一个好版本"。校验失败不会毁掉已有输出。
  3. ​失败有结构化回执​：validate --json 会返回稳定的 rule code、出错对象和可用的修复选项，agent 可以按提示最多修两轮，而不是盲目重试。
  4. ​交互不编造拓扑​：Reach、Route 这些视图只复用你声明过的节点和关系，不会声称"运行时影响"。

几个常用命令

在 archify 目录下：

node bin/archify.mjs doctor                     # 环境检查
node bin/archify.mjs demo /tmp/archify-demo     # 生成 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

preview 模式还能在本地 127.0.0.1 起一个 watch 会话，保存 JSON 就刷新，失败时保留上一个通过校验的版本。

使用时的几点提醒

  • ​不是画图编辑器​：不支持 WYSIWYG 拖拽，也不自动解析 Mermaid，这是项目明确声明的边界。
  • ​Timeline / Waterfall 的示例数据是示意性的​：只有来自日志或 trace 的数字才应当当真。
  • ​更新检查​：它会定期 GET 一次固定的稳定版 manifest 来提示新版本，不会自动下载安装，也不发送版本、项目或 prompt 信息。不想要可以设环境变量 ARCHIFY_UPDATE_CHECK_DISABLED=1。
  • README 里的赞助商和 API 中转链接是推广内容，与 Archify 本身的使用无关，按需判断即可。

小结

如果你经常要给团队讲系统、做设计评审、复盘事故，或者想快速读懂一个陌生仓库，Archify 值得装一个试试：

  1. npx skills add tt-a1i/archify -g
  2. 对 agent 说一句 Use Archify to ...
  3. 用对话继续改，直到图能讲清楚你要说的那件事

在线示例：https://archify.si/gallery.html项目地址：https://github.com/tt-a1i/archify

© 2026 Carreyda