Archify 架构图 Skill 教程：安装、仓库分析、验证与排错

Archify 是一个面向 Codex CLI、Claude Code、Cursor、OpenCode 和 Raven 的 Agent Skill。它把系统描述或代码仓库转换成可交互的技术图，而不是简单地把一段文字套进通用流程图模板。

生成结果以类型化 JSON IR 为事实源，经验证后交付自包含 HTML；浏览器内还可以导出 PNG、SVG、WebM 和 1200×630 分享卡。它适合架构评审、README 配图、故障路径说明和变更前后对比，但不能替代对源码、部署配置和运行日志的审查。

项目地址：tt-a1i/archify

先判断 Archify 是否适合当前任务

Archify 提供五种主要图表类型：

不要把所有信息塞进一张 Architecture 图。登录请求的缓存回退适合 Sequence；CI 的审批和回滚适合 Workflow；订单状态转换更适合 Lifecycle。

Archify 也不是 Mermaid 主题、在线托管平台或 WYSIWYG 编辑器。官方明确把自动解析 Mermaid、通用自动布局、托管分享和所见即所得编辑放在当前范围之外。

安装前检查 Node.js 与工作目录

安装命令通过 npx 运行，因此先检查 Node.js 和 npm：

1
2
3

node --version
npm --version
npx --version

如果命令不存在，先安装当前受支持的 Node.js LTS，再重新打开终端。不要在缺少 npx 时把安装失败归因于 Codex 或 Claude Code。

同时确认要在哪个仓库生成图：

1
2

git rev-parse --show-toplevel
git status --short

工作区有未提交修改时仍可分析，但图中的源码证据必须与一个明确提交对应。用于正式评审时，先记录：

1

git rev-parse HEAD

全局安装 Archify Skill

官方快速安装命令是：

1

npx skills add tt-a1i/archify -g

-g 表示全局安装。各 Agent 的常见 Skill 位置不同：

安装器会按目标 Agent 处理目录，不建议手动把同一份 Skill 复制到多个未知位置。安装完成后重启 Agent，确保新会话重新扫描 Skills。

只想在 Codex 中临时试用，可以执行：

1

npx skills use tt-a1i/archify@archify --agent codex

临时试用适合验证效果；要让团队稳定复现，应固定安装方式，并在项目文档中记录 Archify 仓库版本或提交。

验证 Agent 是否真正调用了 Archify

不要仅凭“已安装成功”判断可用。新建会话后给出一个边界明确的请求：

1
2
3

分析当前仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，标出一条主请求路径、外部依赖和信任边界。
把补充说明放进卡片，不要继续增加连线。

验收时检查三件事：

1. Agent 明确选择并调用 Archify，而不是生成 Mermaid 代码冒充结果。
2. 输出包含可以单独打开的 HTML，以及对应的类型化源数据。
3. 图中的组件、关系和边界能回到仓库或输入描述，不出现无依据服务。

若 Agent 只返回一段解释，先让它说明 Skill 是否被发现，再检查安装目录和新会话状态。

从仓库生成第一张架构图

高质量结果取决于范围。可以使用下面的提示词：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Use archify to map this repository's runtime architecture.

Scope:
- entry points and long-running processes
- API, worker, database, cache and external services
- one primary request path
- authentication and trust boundaries

Constraints:
- 8–12 main nodes
- do not infer services that are not present in source or configuration
- place evidence and secondary details in cards
- deliver the validated HTML and typed source together

对 monorepo，应先限定目录：

1
2

只分析 apps/api、packages/auth 和 packages/database。
忽略 examples、generated、vendor 和构建产物。

如果不限定范围，Agent 可能把测试、脚本和历史实现都画成生产组件，导致节点过多、边的含义不清楚。

为具体链路选择 Sequence 或 Data Flow

缓存回退适合时序图：

1
2
3
4

Use archify to draw this login sequence:
Browser -> Web App -> API -> JWT validation -> Redis session lookup.
When Redis misses, query PostgreSQL and repopulate Redis.
Show failure returns and timeout boundaries, but keep the happy path primary.

涉及隐私和数据处理时，改用 Data Flow：

1
2
3

画出用户上传文件后的数据流。
标出上传入口、病毒扫描、对象存储、元数据数据库、异步处理器和下载消费者。
明确包含个人信息的节点、跨边界传输和保留期限，不推测未提供的加密方式。

区别在于：Sequence 关注调用顺序；Data Flow 关注数据移动、转换、存储和敏感边界。

保留 JSON IR，不要只交付截图

Archify 使用类型化 JSON IR 驱动渲染。团队应同时保存：

• 原始 JSON；
• 验证后的 HTML；
• 用于文档的 SVG 或 PNG；
• 生成时对应的 Git 提交；
• 人工审查记录。

只保留 PNG 会失去可重复编辑和验证能力。HTML 适合交互查看，SVG 适合文档和版本管理，PNG 适合不支持 SVG 的平台。

建议目录示例：

1
2
3
4
5

docs/architecture/
├── runtime.architecture.json
├── runtime.architecture.html
├── runtime.architecture.svg
└── README.md

在 README.md 中记录范围和提交：

1
2
3
4

Source revision: 4f2c1ab
Scope: apps/api, packages/auth, packages/database
Excluded: tests, generated, vendor
Review status: manually checked

用仓库 CLI 验证和交付

如果需要直接调用 Archify 仓库内的验证器，先克隆项目并进入目录：

1
2
3

git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

可以先查看内置示例：

1
2

node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"

验证一个 Workflow JSON：

1
2
3
4

node bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

生成一次性可交付 HTML：

1
2
3
4
5
6

node bin/archify.mjs deliver workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --open \
  --json

失败时读取 diagnostics[]、规则代码、具体对象和 supportedFixes，只修改被指出的问题。不要看到一次验证失败就让 Agent 重写整张图。

本地预览的安全边界

需要边改边看时可使用 preview：

1
2
3
4

node bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase

官方预览模式只绑定 127.0.0.1 的随机端口，并只监听指定 JSON 文件。候选文件未通过验证时，浏览器继续显示上一份合格结果。

不要为了远程访问把预览服务改成 0.0.0.0。需要分享时交付自包含 HTML，或在受控文档系统中发布静态导出文件。

用 Architecture Delta 审查变更

设计或 PR 评审可以比较两个已验证快照：

1
2
3
4
5

node archify/bin/archify.mjs compare architecture \
  base.json \
  head.json \
  architecture-delta.html \
  --json

结果展示 Before、Delta 和 After，并区分已添加、删除、修改、移动或重路由的事实。它比较的是两份已编写并通过验证的结构，不会自动判断风险、影响范围或是否可以合并。

因此仍需人工回答：

• 变化是否来自真实代码和配置；
• 信任边界是否改变；
• 数据存储或外部依赖是否新增；
• 部署顺序和回滚是否需要调整；
• 测试是否覆盖新的路径。

图表生成后如何验收

先检查事实，再检查视觉：

事实检查

• 入口是否与真实启动命令一致；
• 服务关系是否能在代码、配置或文档中找到；
• 同步调用与异步消息是否区分；
• 数据库、缓存、队列没有被混成同一种存储；
• 信任边界和外部系统没有被遗漏；
• 图中没有 Agent 自行补出的“常见组件”。

视觉检查

• 主路径能在数秒内识别；
• 节点没有互相遮挡；
• 连线没有穿过标签；
• 次要信息没有压过主要关系；
• 深色和浅色主题都可读；
• 导出的 SVG、PNG 与 HTML 表达一致。

可交付性检查

• HTML 在断网环境可以打开；
• JSON 和 HTML 使用相同版本；
• 文件名稳定，不含临时随机名称；
• 图中不包含密钥、内网地址或客户数据；
• Git 提交和生成范围有记录。

常见故障排查

Agent 找不到 Archify

重新确认安装和会话：

1

npx skills add tt-a1i/archify -g

然后完全退出并重启 Codex 或 Claude Code。若同时存在多个 Skill 目录，检查 Agent 实际读取哪一个，不要继续重复安装。

生成的是 Mermaid，而不是 Archify HTML

在提示词中明确写“use archify”并要求交付 validated HTML 和 typed source。仍未调用时，说明 Skill 未被发现或被其他规则覆盖。

图中组件过多

把请求缩小到一个运行时路径，限制 8–12 个主节点，并把日志、指标、测试和辅助脚本移到说明卡片。

图的结构与源码不一致

先固定 Git 提交和分析目录，再逐项删除无法找到证据的节点。不要用“通常会有 Redis”这类经验补全实际仓库。

验证失败但旧图仍显示

这是 last-good 预览机制。查看 diagnostics[]，修正当前候选；不要把旧图仍可见误判为新版本验证成功。

SVG 在文档平台显示异常

先在浏览器直接打开 SVG，检查字体、外部资源和裁剪范围。无法稳定展示时使用 PNG，但继续保留 SVG 和 JSON 源文件。

一份可复用的验收清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[ ] 已记录 Archify 安装方式和版本
[ ] 已记录仓库 Git 提交与分析范围
[ ] 图表类型与问题匹配
[ ] 主路径、外部依赖和信任边界明确
[ ] JSON IR 与 HTML 同时保存
[ ] validate 或 deliver 返回成功
[ ] 图中每个关键关系都有输入或源码依据
[ ] 深色与浅色主题可读
[ ] SVG/PNG 导出可打开
[ ] 不包含密钥、内网地址或客户数据
[ ] 人工评审没有把图当作运行时事实证明

总结

Archify 的价值不是“一句话自动画图”，而是把技术描述整理为类型化、可验证、可交互的交付物。可靠流程应当是：限定范围，选择正确图种，生成 JSON IR，通过验证，人工核对事实，再交付 HTML 和静态导出。

对代码仓库尤其要保留 Git 提交和分析范围。图表可以帮助团队讨论架构，但源码、配置、测试和运行数据仍是最终依据。