Archify 详解：把代码库变成可交互的系统地图
让 Agent 画架构图，老问题的解法通常是"生成一段 Mermaid"——但 Mermaid 出来的静态图既不能交互也难以验证，改图等于重画。tt-a1i/archify（Archify）换了个思路：Agent 只产出类型化的 JSON 中间表示（IR），Archify 确定性地编译成自包含 HTML/SVG——五种图型、动画、明暗主题、可验证、可分享。装进 Cursor、Claude Code、Codex CLI、OpenCode 后，一句"画：浏览器 → API → Redis → PostgreSQL 回退"即可出图，无需仓库，纯对话描述也行。2026 年 4 月创建，五个月冲到约 62.9k Star，MIT 协议。本文从工作机制、图型体系、工程质量到选型，完整拆解。
1、项目概述
Archify 定位为面向 Cursor、Claude Code、Codex CLI 与 OpenCode 的渲染与验证系统（Agent Skill 形态）：Agent 生成类型化 JSON IR，Archify 确定性编译为单文件 HTML/SVG，把代码库或系统描述变成"打磨过的交互式系统地图"。仓库约 62.9k Star、4.2k Fork、MIT 协议，JavaScript / Node.js 主体，个人开发者 tt-a1i 维护，2026 年 4 月创建。配有项目主页、场景指南与 Proof Lab（11 个已验证场景的在线画廊），Trendshift 徽章在列，已获 Supercode 与 EverMind 商业赞助。
基本盘：
- 安装：npx skills add tt-a1i/archify -g 一条命令；Claude Code / Codex / opencode / Raven 各有对应技能目录，Claude.ai 走 ZIP 上传
- 版本：v2.17.0-dev.1 开发中，CHANGELOG 与 ROADMAP 公开
- 输出：自包含单 HTML 文件，另可导出 PNG / SVG / WebM 与 1200×630 分享卡
- 零仓库起步：纯文字描述即可出图；有仓库时可选证据模式，节点标记 SRC n 并打开 Git 锁定的文件与行号
- 更新检查：仅 GET 固定清单做可选提醒，不自动下载；ARCHIFY_UPDATE_CHECK_DISABLED=1 可彻底断网
2、工作机制：生成、验证、交付
流水线四步走，核心是"Agent 出结构、渲染器出图、验证器把关"。
流程拆解：
- Generate：Agent 依据描述生成类型化 JSON IR——每个渲染模式都有 schema，来源可复现
- Validate：捆绑的校验器与布局规则检查源文件，失败时给出机器可读 JSON——规则码、精确对象、证据与修复手段，而非一坨 Node 堆栈
- Preview（可选）：仅回环桌面的监视模式，盯一个 JSON 文件，只有通过全部检查的新版才刷新，失败时保留最后已知良好图
- Deliver：同目录候选渲染并检查，通过后原子替换目标文件，可选 --open 启动该确切文件
机制要点：
1. 原子验证门槛：schema、布局、HTML/SVG、路由与标签间距五道检查全过，新图才替换旧图——"最后良好版本"永不回退
2. 布局判断优于自动布局：层级、间距、路由与强调由 Agent 决定，共享端点确定性展开而非箭头堆一点
3. 诚实交互原则：聚焦、上下游溯源、精确路由、角色对比、导览故事全部复用已著录的节点与关系，不发明拓扑、不宣称运行时影响
4. 修复有凭据：validate --json 与 deliver --json 返回稳定规则码 + supportedFixes 列表，技能内限两轮修正，视觉审阅另算
3、五种图型与对比工作流
按表达意图选图型，PR 审查另有快照对比杀手锏。
五种图型：
- Architecture：组件、服务、存储与边界——提示词要点：范围、核心组件、主路径
- Workflow：CI/CD、审批、工具调用、runbook——参与者、顺序、分支、异常
- Sequence：API 调用、缓存回退、鉴权、异步追踪——调用方、被调方、返回、时序
- Data Flow：管道、血缘、PII、消费方——来源、转换、存储、边界
- Lifecycle：状态、重试、等待、终态——状态、事件、重试与取消路径
图型要点：
1. Architecture Delta 是 PR 审查利器：对比两份已验证快照，输出 Before / Delta / After，新增、删除、变更、移动与改路由的事实精确到机器凭据
2. deployment-ownership 剖面失败即关闭：著录的属主、区域、私有库范围缺一不出图，绝不隐式推断，不查真实基础设施
3. 拿不准图型问 CLI：node archify.mjs guide "描述场景" 零依赖给出建议，--json 可编程
4. 每张图四种预设（Signal Flow / Blueprint / Classic 等）、明暗主题一键切换、有限动画尊重 prefers-reduced-motion
4、查看器与命令行
成品不是死图：键盘驱动的查看器 + 完整 CLI 双形态。
# 安装技能
npx skills add tt-a1i/archify -g
# 仓库内常用命令
cd archify
node bin/archify.mjs doctor # 环境自检
node bin/archify.mjs demo /tmp/archify-demo # 演示
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
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
# 快照对比（PR 审查）
node archify/bin/archify.mjs compare architecture \
base.json head.json architecture-delta.html --json查看器要点：
1. 键盘全家桶：? 图指南、/ 搜索聚焦、R 路由探测、L 角色对比、M 雷达总览、P 导览故事、F 演示舞台、S / T / E 风格 / 主题 / 导出
2. 稳定链接可分享：#focus、#reach、#route、#lens、#view 等锚点还原精确视图状态
3. 导出菜单：PNG 进剪贴板，静态 / 动图格式下载，1200×630 分享卡（含路由分享卡与溯源分享卡）
4. 中英本地化：meta.locale 切换界面文案，著录内容永不翻译
5、定位对比：架构图方案三选一
把 Archify 与 Mermaid、专业建模工具放在一张桌上，三种定位清晰起来。
三者对比：
- Archify：Agent 技能形态，类型化 IR + 确定性渲染 + 原子验证，交互查看器与快照对比，单 HTML 分发（62.9k Star，MIT）
- Mermaid：文本即图的通用标准，生态最广、随 Markdown 渲染，但静态无交互、复杂图布局易崩
- 专业建模工具（draw.io / PlantUML / C4）：手动精细控制或结构化规范，适合规范化文档，非 Agent 原生
选型建议：
1. 在 Agent 工作流里出架构图、要交互与验证 → Archify
2. README / 文档内嵌简单图、要 Markdown 生态 → Mermaid
3. 手工精修大型规范图集 → 专业建模工具
4. 组合玩法：Archify 出沟通与审查用的交互图，定稿后导 SVG 嵌入文档，Mermaid 补小场景速记
6、总结
Archify 是个人开发者 tt-a1i 出品的 Agent 架构图技能（约 62.9k Star、MIT 协议）：以类型化 JSON IR 为中枢——Agent 生成结构、渲染器确定出图、五道验证原子把关，产出自包含 HTML/SVG；五种图型覆盖架构、工作流、时序、数据流与生命周期，配四种预设、明暗主题、有限动画与键盘驱动的交互查看器；Architecture Delta 支持 PR 级 Before / Delta / After 对比，证据模式可回链 Git 锁定源码；CLI 提供 doctor / demo / guide / validate / deliver / compare 全流程命令，导出含 PNG / SVG / WebM 与分享卡。五个月 6 万 Star，社区热度与商业赞助俱佳。
适用与边界：它适合在 Agent 对话流里快速产出可信、可交互的系统图——代码评审、架构沟通、文档分享都是主场景，"对话描述即可出图"的零门槛体验是最大卖点；官方明示不是通用绘图编辑器也不是 Mermaid 主题——Mermaid 自动解析、通用自动布局、托管分享与 WYSIWYG 编辑均不在范围内；当前为 2.17 开发版，API 与 schema 仍在演进，生产嵌入需锁版本；Claude.ai 网页端的沙箱 Node 权限会影响能力完整度，本地 CLI 客户端（Cursor / Claude Code / Codex / OpenCode）是完整体验路径。
