tt-a1i/archify · 上手攻略
- 仓库：tt-a1i/archify
- 链接：https://github.com/tt-a1i/archify
- 分类：Agent工具 · 架构可视化
- 作者：Tom
- 更新：2026-08-05
是什么
Archify 是一款面向 AI Agent 的架构图生成 Skill（支持 Raven、Cursor、Claude Code、Codex CLI、OpenCode），通过自然语言描述或代码仓库分析，自动输出可交互的 HTML 系统地图，支持五种图类型、多种视觉主题，并可直接导出 PNG / SVG / WebM / 1200×630 分享卡片。
其核心特点是基于 Typed JSON IR + 确定性校验，生成的拓扑不是模型随意发挥，而是经过事实核验、可溯源的系统架构表达。当前稳定版本 v2.13.0（2026-08-03）。
解决什么问题
- 架构"只存在于脑子里"：代码Review或交接时没有统一视图，团队靠口述或手画。
- 部署评审缺少客观依据：PR 描述的架构变化难以精确对照，Before/Delta/After 靠人工比对容易出错。
- Graphviz / Mermaid 难看又难维护：画一张技术图需要学习语法，图生完就成了死图。
- 架构图无法验证：普通生成的图没有任何校验机制，节点和边的正确性完全依赖模型幻觉。
Archify 通过可校验的拓扑生成 + 版本快照对比解决了这些问题。
快速安装
# 全局安装（推荐，支持多种 Agent）
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
# Raven 手动 ZIP 安装
# 下载 archify.zip 解压到 ~/.raven/workspace/skills/archify
注意：不同 Agent 的全局目录不同，安装后确认文件出现在对应 Agent 的 skills 目录下（Cursor 为
~/.cursor/skills/，Claude Code 为~/.claude/skills/等）。
核心用法
基础命令——让 Agent 自动生成
在已装好 Archify 的 Agent 中，直接发自然语言指令：
分析这个仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，突出一条主要路径，并标出外部依赖与信任边界。
辅助信息放进说明卡片，不要继续增加连线。
使用 archify 画出这条登录流程：
Browser -> Web App -> API -> JWT 校验 ->
Redis Session 查询 -> PostgreSQL 回源。
把缓存未命中作为次要路径。
五种图类型及适用场景
| 类型 | 最适合 | Prompt 关键词 |
|---|---|---|
| Architecture | 组件、服务、存储、系统边界 | "高层架构""核心组件""信任边界" |
| Workflow | CI/CD、审批、工具调用、Runbook | "流程图""审批流""工具链" |
| Sequence | API 调用、缓存回源、鉴权、异步链路 | "调用链""时序""API 序列" |
| Data Flow | 数据管线、血缘、PII、下游消费者 | "数据流""Pipeline""血缘" |
| Lifecycle | 状态机、重试、等待、终态 | "状态机""生命周期""重试路径" |
交互功能
- 搜索节点：在图上搜索特定组件，快速定位
- 路径追踪：计算最短有向路径，或追踪上下游可达范围（
reach=upstream/reach=downstream） - 语义角色对比：对比两个角色（如
backend~database）之间的真实流量 - 引导故事播放：按命名章节顺序播放架构演化，适合 PR 评审演示
- 主题切换：Dark / Light 一键切换
架构变更对比（Architecture Delta）
在已有快照的基础上运行第二次，Archify 会生成 Before / Delta / After 三视图：
- Added（新增节点/边）
- Removed（删除）
- Changed（语义变化）
- Moved（位置调整）
- Rerouted（重路由）
配合 deployment-ownership 工程画像，可自动检测：负责人缺失、跨区域归属不清、数据库边界穿越机制缺失等，直接在图中阻断。
输出格式
- 主文件：独立 HTML（自含 Viewer，含动画和交互）
- 导出：PNG 剪贴板复制、SVG 静态图、WebM 动图
- 分享卡：1200×630 PNG（适合 README / Release / 社交媒体）
- Reach 卡：上游/下游可达范围导出 1200×630 PNG
生成后的最小可跑验证命令
# 1. 确认 archify skill 已安装
ls ~/.cursor/skills/ # 或对应 Agent 的 skills 目录
# 2. 在 Agent 中触发生成
# 在 Cursor/Claude Code 对话框输入:
# "使用 archify 梳理本仓库的运行时架构"
# 3. 打开生成的 HTML 文件（Archify 输出路径通常在当前目录或 /tmp）
open archify-output.html # macOS
xdg-open archify-output.html # Linux
# 4. 对比两次生成（需先生成 baseline）
# 在 PR 评审时，第二次生成会自动输出 Delta 视图
典型适用场景
- 新项目入手：快速生成系统全貌，不必逐文件阅读
- PR / MR 架构评审：生成 Before / After，对比变更是否与描述一致
- 外部沟通：导出分享卡放进 README / 文档，降低沟通成本
- 跨团队对齐：交付物是自验证的 HTML，任何人都可以打开交互
- 论文/报告插图：导出 PNG / SVG，避免手动绘图
坑与注意
| 坑 | 说明 |
|---|---|
| Agent 上下文窗口限制 | 超大代码库建议分段生成，每次聚焦 8–12 个核心组件 |
| gpt-4 等模型 Token 消耗较高 | Architecture 图的 JSON IR 可能较大，长仓库注意 token 预算 |
| Raven 手动 ZIP 安装 | 不走 npx skills，需要手动下载 archify.zip 并解压到正确路径 |
| Deployment-ownership 不会自动开启 | 需在 Architecture 模式下显式启用；它只校验作者写入的事实，不代表线上已核验 |
| PDF / Markdown 导出非交互 | 导出是 HTML 内置功能，不依赖外部渲染器 |
| 分享卡分辨率固定 1200×630 | 如需其他尺寸需截图后再处理 |
与同类对比
| 工具 | 特点 | Archify 优势 |
|---|---|---|
| Mermaid / Graphviz | 文本语法定义图 | 零语法，NL 生成，可校验 |
| draw.io / Lucidchart | 手动绘图 | AI 生成，可版本对比，可交互 |
| Structurizr | 架构即代码 | 更偏静态文档，Archify 更适合 Agent 工作流 |
| d2lang/d2 | 声明式图语言 | 需要学习 DSL，Archify 自然语言直出 |
| CodeRabbit AI Review | PR 评审 + 架构 | 仅覆盖代码变更，Archify 支持完整系统图 |
核心差异：Archify 是目前唯一在 Agent 内实现"生成 → 校验 → 交互 → 导出"完整闭环的架构可视化 Skill，尤其适合 AI-native 工作流。
一句话推荐结论
如果你的 AI Coding 工作流还在靠文字描述系统架构，Archify 是目前将自然语言转化为可验证、可交互、可分享的系统地图最低成本的方案，尤其适合 PR 评审和团队知识沉淀。
来源：https://github.com/tt-a1i/archify · https://tt-a1i.github.io/archify/ · https://tt-a1i.github.io/archify/guide.html · v2.13.0（2026-08-03）
不确定处：Raven 的 skills 目录结构未在 README 中明确说明，ZIP 安装路径需用户自行确认；Architecture Delta 的快照存储机制未找到明确文档