Archify アーキテクチャ図スキルチュートリアル: インストール、図の生成、および「間違った図」のトラブルシューティング

技术图“能画出来”和“能拿去评审”是两回事。Archify 是一个可用于 Claude Code、Codex CLI 和 opencode 的 Agent Skill：它把自然语言描述或仓库分析结果转为独立 HTML 图表，并支持架构图、工作流、时序图、数据流图和生命周期图；生成后可切换明暗主题，导出 PNG、JPEG、WebP 或 SVG。Archify 官方仓库

它特别适合需要可验证交付物的场景：安装后能运行 doctor 和 demo，生成后能检查 HTML、SVG 与布局，而不是只收到一段无法确认正确性的 Mermaid 文本。

Archify 能画什么，先别选错图种

先根据问题选择视图，图会更清楚：

图种	适合回答的问题	提示词必须交代的内容
Architecture	服务、数据库、外部依赖如何组成系统	核心组件、主请求路径、信任边界
Workflow	CI/CD、审批、运维 Runbook 如何推进	参与者、顺序、分支和异常
Sequence	一次请求或认证过程如何交互	调用者、被调用者、返回与时序
Data Flow	数据从哪里来、如何处理、流向哪里	来源、转换、存储、PII 边界
Lifecycle	状态、重试、等待与结束条件	状态、事件、取消和终止条件

“画整个仓库”通常是图不清晰的起点。先限制到 8–12 个核心组件和一条主要路径，其他细节放到卡片或第二张图里。

安装 Archify Skill

官方推荐通过 skills CLI 全局安装：

1

npx skills add tt-a1i/archify -g

安装后，适配的 Agent 可直接使用。若只想临时试用而不做永久安装，官方示例是：

1

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

把 codex 替换为 claude-code 或 opencode 即可切换目标 Agent。手动安装也可行：将 archify.zip 解压到对应 Skill 目录，例如 Codex CLI 使用 ~/.agents/skills/ 或项目内 .agents/skills/；Claude Code 使用 ~/.claude/skills/ 或 .claude/skills/。打包版不需要额外 npm install。

先验证安装，再让 Agent 画图

不要装完就直接交给真实项目。若你是从仓库检出版本运行，先执行官方 CLI 的基础检查：

1
2
3
4


cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs examples

doctor 用于发现本地环境问题，demo 应产生可打开的示例输出。验证通过后再把 Skill 用在仓库上，能把“安装问题”和“提示词/图表问题”分开排查。

最小请求可以这样写：

1
2
3


Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary request or data path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

对于单一流程，描述实际方向而非笼统说“画登录图”：

1
2


Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->
Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.

Archify 输出为何更容易验证

Archify 不直接让模型手写最终 SVG。其流程是先生成带类型的 JSON IR，再进行 schema 验证、渲染、布局检查以及 HTML/SVG 成品检查；修改时针对 JSON IR 局部迭代，避免无关结构被一并破坏。

你也可以手动验证一个工作流图：

1
2
3


node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json
node bin/archify.mjs check /tmp/workflow.html

验证至少分两层：命令是否成功、浏览器里是否真的可读。前者能发现 schema 或渲染错误，后者才能发现边线穿过节点、文字被遮挡、信息密度过高等沟通问题。

如何检查最终图表

生成的 HTML 是独立文件，可直接用现代浏览器打开。右上角可切换主题或导出；快捷键 T 切换明暗主题，E 打开导出菜单。

交付前逐项确认：

主路径是否可以从左到右或从上到下连续读完。
每个箭头是否有明确方向，异步、失败或回滚路径是否被标记为次要分支。
组件数量是否超过读者一次能理解的范围；太多就拆图。
信任边界、数据敏感边界和外部系统是否真的画出，而非只写在说明中。
在浅色与深色主题下都检查文字、线条和图标对比度。
导出的 SVG 是否能在 README、博客或设计工具中正常打开；位图则检查分辨率和裁切。

Archify 的 SVG 会携带深浅色变量并响应 prefers-color-scheme，适合放在 README；位图导出最高可达源尺寸的 4 倍，但超大图会受浏览器画布限制而自动降级。

图不对时，按这个顺序修

不要让 Agent 反复“重新画一个更好看的”。先定位问题属于信息、布局还是渲染：

现象	常见原因	优先修法
节点太多、线像毛线团	提示词没有限定范围	只保留 8–12 个核心组件和一条主路径
关系方向错误	输入没有写清调用方向、同步/异步	明确 `A -> B`，写出返回、队列或 fallback
重要路径不突出	主路径和次要分支权重相同	指定主路径、将缓存未命中/回滚标为 secondary
图形技术标签不匹配	组件名称过于抽象	使用 `postgres`、`redis`、`aws.lambda`、`github-actions` 等语义标签
HTML 正常但 SVG 异常	导出或浏览器兼容性问题	先运行 `check`，再换浏览器检查 SVG 与本地字体回退
改一点就破坏全图	让 Agent 重画而非局部迭代	指定“只移动 auth 到左侧”“只新增 Redis”这类局部变更

问题报告也应包含三样东西：原始提示词、图种、Archify 版本。没有这些信息，别人很难稳定复现布局或渲染错误。

用 Chat 做说明，用 Skill 生成可审查图

Archify 擅长把已明确的技术关系变成图，不负责替你凭空决定系统设计。较稳的流程是：先让 Agent 输出组件清单、边界、主路径与未知项；人工确认后，再让 Archify 绘图；最后根据审查意见局部迭代。

如果你正在把 Codex 的工作方式沉淀成项目规范，也可结合 Codex Skills 怎么写自己的工作流来管理本地 Skill 目录和生效范围。

常见问题

Archify 能替代 Mermaid 吗？

它不是通用 Mermaid 主题或自由画图编辑器。它采用自己的 JSON IR 和渲染器，目标是把技术意图做成可分享、可导出的独立图表；已有 Mermaid 流程是否迁移，取决于团队的图表维护方式。

安装了但 Codex 没有使用 Skill，怎么办？

先确认安装目录与当前 Codex CLI/项目的 Skill 发现范围一致，再用临时 npx skills use ... --agent codex 复现。若仍无效，运行 doctor，并检查终端实际运行的账户、项目目录和 Skill 名称。

为什么图很漂亮但不准确？

因为图的准确性来自输入。让 Agent 先列出它从仓库中推断出的组件与调用关系，标记未知项；确认无误后再生成图。视觉检查不能替代架构事实核对。

小结

Archify 适合把架构、流程和数据关系做成可以打开、导出、检查的交付物。安装后先跑 doctor 与 demo，绘图时限定范围和主路径，交付前同时检查 HTML、导出文件和事实关系；图不对时优先修输入与视图选择，而不是反复要求“画得更漂亮”。