Archify 解读：让 AI 用自然语言生成可交互架构图的 Node.js 渲染系统
画架构图是开发者的日常痛点：Mermaid 画出来的图经常箭头堆在一起、布局不可控；draw.io 这类工具又太慢，改一个组件要拖半天；让 AI 直接生成图，往往得到几个方框加箭头，看完不知道先看哪里。
Archify 试图解决这个问题。它是一个 Node.js 渲染和验证系统，专为 Cursor、Claude Code、Codex CLI 和 OpenCode 设计：Agent 先产出带类型的 JSON 中间表示（IR），Archify 再把它确定性地编译成可交互的 HTML/SVG 架构图。项目由 tt-a1i 开发，MIT 协议开源，GitHub 上已超过 1.7 万 Star。
项目地址：https://github.com/tt-a1i/archify
一、它是什么
用一句话概括：把自然语言或代码库描述，变成漂亮、可交互、可验证的系统架构图，直接在聊天里呈现。
它不是通用绘图编辑器，也不是 Mermaid 主题。Archify 的定位是"把技术意图变成沟通产物"——Agent 负责理解系统结构并选择布局，Archify 负责把结构渲染成高质量、可交互的单 HTML 文件。
核心设计思路是 typed JSON IR：每一种图表模式都有 schema 和可复现的源。Agent 不直接写 HTML，而是生成结构化的 JSON；Archify 验证通过后再渲染。这意味着图是"可复现、可迭代、可验证"的，而不是一次性的图片。
二、五种图表类型
Archify 支持五种图表，每种都有明确的适用场景：
| 类型 | 适用场景 | Prompt 中应包含 |
|---|---|---|
| Architecture（架构图） | 组件、服务、存储、信任边界 | 范围、核心组件、主路径 |
| Workflow（工作流） | CI/CD、审批、工具调用、runbook | 参与者、顺序、分支、异常 |
| Sequence（时序图） | API 调用、缓存回退、认证、异步追踪 | 调用方、被调方、返回、时序 |
| Data Flow（数据流） | 管道、数据血缘、PII、消费者 | 源、转换、存储、边界 |
| Lifecycle（生命周期） | 状态、重试、等待、终止结果 | 状态、事件、重试与取消路径 |
不确定用哪种时，可以用交互式场景指南，或直接问 CLI：
node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
三、核心特性
1. 视觉预设与主题
四种视觉预设（signal-flow、blueprint、classic 等），深色/浅色主题一键切换，内置品牌标记，有限动画（尊重 prefers-reduced-motion）。同一张图可以在深色和浅色之间无缝切换，不需要重新生成。
2. 可交互查看器
生成的不是静态图片，而是一个可交互的 HTML 文件，支持：
- 焦点搜索（
/）和节点聚焦 - 上游/下游可达性追踪（Upstream / Downstream）
- 有向路径探测（Route）
- 语义角色对比（Lens）
- 引导式故事播放（Story）
- 演示模式（Presentation Stage，按 F 进入）
- 缩放、重置、快捷键操作
这些交互都基于图中已有的节点和关系，不会凭空发明拓扑或声称运行时影响。
3. 导出与分享
导出菜单支持把 PNG 复制到剪贴板，或下载静态/动态格式。特别实用的是 Share Card：生成 1200×630 的标准图片，适合放在 README、Release Note 或社交媒体。追踪路径后还可以导出 Route Share Card，保留完整架构作为上下文，同时高亮指定路径。
4. 架构变更对比（Architecture Delta）
对于设计评审或 PR Review，Archify 可以对比两个已验证的快照，生成 Before / Delta / After 视图，精确显示新增、删除、变更和移动的事实，并附带机器收据。命令行用法：
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json
注意：它只推断图中已有的变更，不会推断影响、风险或合并安全性。
5. 代码库溯源（Source Evidence）
Archify 可以从真实代码库生成架构图。开启溯源后，节点会标记 SRC n，并链接到 Git 验证过的文件和行号（固定到某个公开 commit）。普通产物则保持无源状态，避免不必要的噪音。
6. 原子验证与修复收据
这是 Archify 区别于普通"AI 画图"工具的关键。交付前必须通过五道门：schema 校验、布局规则、HTML/SVG 渲染、路径检查、标签到路径的间隙检查。全部通过才会原子替换上一个已知良好的输出。
失败时，validate --json 和 deliver --json 返回稳定的规则码、精确的主体、测量证据，以及仅支持的修复操作——而不是一个 Node 堆栈或无结构的重试猜测。Agent 可以在两轮修正内针对性修复。
7. Last-good 实时预览
可选的桌面模式监视一个 JSON 文件，只在最新候选通过所有门后才刷新；当保存不完整或无效时，保持显示上一个已验证的图。这避免了"改一半图就崩了"的尴尬。
四、安装与快速上手
安装
一行命令全局安装：
npx skills add tt-a1i/archify -g
支持的 Agent 客户端包括 Cursor、Codex CLI、Claude Code、OpenCode。Raven 用户可以手动把 archify.zip 解压到 ~/.raven/workspace/skills。DeepSeek Harness 用户可以通过社区插件安装：
dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0
从描述开始（不需要代码库）
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.
在聊天中迭代
继续用聚焦的请求修改，比如 add Redis、move auth to the left、highlight the rollback path。Archify 保持 typed 源可用，支持针对性迭代，不相关的结构保持稳定。
五、工作原理
Archify 的工作流分为五步：
| 步骤 | 发生什么 |
|---|---|
| Generate | Agent 从你的描述创建 typed JSON IR |
| Validate | 内置验证器和布局规则检查源；失败时用机器可读 JSON 指出精确的本地修复 |
| Preview（可选） | 仅回环的桌面会话监视一个源，只重载已验证版本；失败时保持上一个良好产物 |
| Deliver | 渲染并检查同目录候选；只有通过的才原子替换目标，可选 --open 启动该文件 |
| Iterate | Agent 更新源，不相关的结构保持稳定 |
常用 CLI 命令：
cd archify
node bin/archify.mjs doctor # 环境检查
node bin/archify.mjs demo /tmp/archify-demo # 生成演示
node bin/archify.mjs guide "CI/CD + 审批 + 部署 + 回滚" # 场景指南
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json
六、与 Mermaid、draw.io 的区别
| 维度 | Mermaid | draw.io | Archify |
|---|---|---|---|
| 输入 | 文本 DSL | 手动拖拽 | 自然语言 / 代码库 → typed JSON IR |
| 布局 | 自动布局（常堆箭头） | 手动 | Agent 选择层级、间距、路径，确定性分布 |
| 交互 | 静态 | 编辑时交互 | 焦点、路径追踪、角色对比、故事播放 |
| 验证 | 语法检查 | 无 | schema + 布局 + 渲染 + 路径 + 间隙五道门 |
| 输出 | SVG/PNG | 工程文件 | 单 HTML 文件（可交互）+ PNG 导出 |
| 可复现 | 是 | 否 | 是（typed JSON 源） |
Archify 明确不做：自动 Mermaid 解析、通用自动布局、托管分享、WYSIWYG 编辑。它的核心价值在于"Agent 决策布局 + 确定性渲染 + 原子验证"的组合。
七、适合谁
- 经常需要画架构图但嫌 Mermaid 丑、draw.io 慢的开发者
- 用 AI Coding 工具（Cursor / Claude Code / Codex）想直接在聊天里生成可交互架构图的人
- 需要做架构评审、PR 变更对比的团队（Architecture Delta 功能）
- 想从代码库自动生成运行时架构图并溯源到具体文件行号的项目
- 需要在 README、Release Note 中放高质量架构图 Share Card 的维护者
局限：Archify 不是通用绘图工具，不适合自由创作式的图表设计；它的质量依赖 Agent 对系统结构的理解和布局判断，如果 Agent 理解有误，图也会有误（虽然验证门能拦住格式和布局问题，但拦不住语义错误）。此外，DeepSeek Harness 集成目前是社区版，需要 Node 22.19+ 或 24+。
如果你已经在用 Cursor 或 Claude Code，装上 Archify 试试，让 AI 帮你把系统结构变成一张能看、能点、能导出的架构图。
项目地址：https://github.com/tt-a1i/archify