Archify教程：AI代理自动画架构图的技能安装与使用指南（29k星）

📅 2026-08-29 · 🏷️ 架构图 · Agent Skills · 技术文档

Archify是什么？

一个 Agent Skill：装进 Claude Code、Codex、Cursor 或 opencode 后，你的 AI 代理就能为代码库生成"漂亮且可验证"的图表——架构图、工作流、时序图、数据流、生命周期，产出是自包含 HTML（带动画、可交互、可高清导出），不依赖任何外部服务。

与普通"让 AI 画图"不同的是可验证性：每张图有 JSON 源、命名视图和校验收据，错的连接画不出来。官方用公开仓库 mco-org/mco 做过完整案例，从源码追踪到成图全程可复查。

五类图，各管一摊

图类型	适用场景	重点表达
Architecture	系统全貌、部署评审	组件、主路径、信任边界
Workflow	CI/CD、审批、runbook	参与者、顺序、分支、异常
Sequence	API 调用、缓存回退、异步链路	调用方、被调方、时序
Data Flow	管线、血缘、PII 合规	来源、变换、存储、边界
Lifecycle	状态机、重试、终态	状态、事件、取消路径

安装

# 一条命令全局安装
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

安装位置按宿主而定：Claude Code 在 ~/.claude/skills/，Codex 在 ~/.agents/skills/，opencode 在 ~/.config/opencode/skills/。Claude.ai 网页版在 Settings → Capabilities → Skills 上传 archify.zip。

使用：让代理画一张图

装完直接下指令，官方推荐的提示词模式：

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.

关键技巧：一次只要一张有边界的图——限定组件数量、主路径和边界，细节收进卡片而不是堆节点。

CLI 命令

# 交互式场景向导
node bin/archify.mjs guide

# 校验图 JSON（showcase 级质量门槛）
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

# 本地预览（只绑 127.0.0.1，Ctrl-C 停止）
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html

# 交付（校验通过后才产出）
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --open --json

# 架构变更对比（PR 评审利器）
node bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

校验失败时 --json 会输出 diagnostics[]，按提示只改指定的问题点，官方建议不超过两轮修正。

使用场景

• 接手新项目：一张运行时架构图快速建立全局认知
• PR 评审：Architecture Delta 对比 Before/After 快照，新增/删除/移动一目了然
• 生产部署评审：启用 deployment-ownership 工程档案，缺 owner、缺区域隔离、跨界未命名直接校验失败
• 技术分享：自包含 HTML 直接发给同事，无需装任何软件

同类工具横评看CodeBoarding架构图教程（面向人类理解的交互式架构图），AI 查询代码结构的方案看CodeGraph代码知识图谱教程。