Archify on KnightLiブログ

Archify を Codex/Claude Code にインストールする方法: ウェアハウスからアーキテクチャ図、フローチャート、SVG を生成する

Wed, 15 Jul 2026 22:06:00 +0800

给项目补架构图时，最耗时的往往不是画框，而是先读仓库、确定边界、把一条关键路径讲清楚，再导出能放进 README 或文档的文件。Archify 是面向 Codex CLI、Claude Code 和 opencode 的 Agent Skill：它会生成一个独立 HTML 图表，支持架构、工作流、时序、数据流和生命周期视图，并可导出 PNG、JPEG、WebP 与 SVG。Archify 官方仓库

这篇只讲从安装到交付 SVG 的完整路径。遇到布局错乱、校验失败等问题，可再看 Archify 的图表验证与排错方法。

选择全局、项目级还是临时试用

先按使用范围选择安装方式：

方式	适合谁	结果
全局安装	经常在多个仓库画图的个人	所支持 Agent 都可发现 Archify
项目级安装	团队希望仓库内统一使用	Skill 跟随项目，便于协作复现
临时试用	只想先验证效果	不建立永久安装

官方推荐的全局安装命令：

`1`	`npx skills add tt-a1i/archify -g`

临时用 Codex 试运行：

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

把 codex 换成 claude-code 或 opencode，即可切换对应 Agent。安装后若工具没有马上发现新 Skill，重启当前终端/Agent 会话，再确认当前账户和项目目录没有切换。

手动安装到 Codex CLI 与 Claude Code

不能使用 skills CLI 时，下载官方 archify.zip 并解压到对应目录即可；打包版不需要额外 npm install。

Codex CLI 的目录是：

1
2

~/.agents/skills/       # 用户级
.agents/skills/         # 项目级

Claude Code 的目录是：

1
2

~/.claude/skills/       # 用户级
.claude/skills/         # 项目级

项目级安装适合需要把图表提示词、项目术语和生成习惯固定下来的团队；用户级安装更适合个人临时分析不同仓库。无论哪种方式，都应避免在同一项目中混放多个版本，否则 Agent 可能读到旧 Skill。

从仓库生成第一张架构图

打开仓库后，不要只说“画架构图”。先限制范围、读者和主路径，减少 Agent 将每个目录都塞进图里的倾向：

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.

建议先让 Agent 在聊天中列出它识别的组件和不确定点，再生成图。比如它不能确定 Redis 是缓存还是队列、某个服务是否直接访问数据库时，应先标出假设，别让一张视觉上完整的图掩盖事实错误。

生成架构图时，优先提供语义明确的技术标签：postgres、redis、aws.lambda、github-actions、openai 等。Archify 会据此对前端、后端、存储、云基础设施、安全与外部系统进行视觉归类。

从仓库生成流程图与时序图

架构图回答“系统有什么”，流程图回答“事情怎么发生”。对 CI/CD、审批、Agent 工具调用或运维 Runbook，可使用明确的参与者、顺序、分支和异常：

1
2

Use archify to draw a CI/CD workflow: pull request -> tests -> approval -> build image -> staging ->
smoke test -> production. Show rollback as a secondary failure path.

对单次认证、缓存回退或异步调用，则用时序视图并写清调用方向：

1
2

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

一个实用原则：架构图、流程图、时序图分别交付，不要试图用一张图同时解释组件、部署、数据表、错误码和所有分支。读者需要的是一条能被验证的叙事，而不是组件清单。

生成后先交付 HTML，再导出 SVG

Archify 生成的是可在现代浏览器直接打开的独立 HTML 文件，无需额外服务或框架。先打开 HTML 检查主路径、文案和边界，再决定导出格式：

格式	适合放在哪里
Copy PNG	Slack、Notion、GitHub 评论和快速评审
PNG/JPEG/WebP	幻灯片、文档、网站和打印
SVG	README、博客、Figma、Illustrator 和无损缩放

在图表右上角的 Export 菜单导出，快捷键 E 可打开该菜单；T 切换明暗主题。位图最高可按源尺寸 4 倍原生渲染，超大图会因浏览器画布限制自动降低分辨率。

SVG 更适合代码仓库：Archify 导出的 SVG 同时包含深浅主题变量和 prefers-color-scheme，放入 GitHub README 时会随读者系统主题变化。提交前仍应在浅色、深色和目标渲染平台各打开一次，确认字体回退、线条和文字对比度符合预期。

把图表变成可复现的仓库资产

不要只保留一张最终截图。建议为每张长期维护的图保存：

docs/architecture/
  runtime-architecture.svg
  deploy-workflow.svg
  prompts.md
  assumptions.md

prompts.md 记录生成提示词、图种、范围和版本；assumptions.md 记录从代码无法直接确认的关系。下次架构变化时，先更新假设和提示词，再让 Agent 对现有结构做局部调整，如“新增 Redis”“把 auth 移到左侧”“突出 rollback path”。这样比重新生成整张图更稳定。

若需要机器级校验，可在 Archify 仓库检出中运行：

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

它会检查环境、JSON schema 和 HTML 成品；但仍需人工核对系统事实，因为校验器不能判断 Agent 是否误解了你的业务关系。

常见问题

安装后 Codex 或 Claude Code 找不到 Archify，怎么办？

先确认安装目录是否对应当前工具和范围：Codex 用 .agents/skills/，Claude Code 用 .claude/skills/。然后重启会话、检查项目根目录，并避免同时存在多个旧版本。临时 npx skills use ... --agent codex 是区分“发现机制问题”和“Skill 本身问题”的快捷方法。

为什么生成的图没有反映真实仓库？

Skill 只能基于它读到的代码和你的说明推断。先要求它输出组件清单与未知项，补充运行环境、外部依赖、边界和主路径，再生成图；不要将图表的美观误认为架构事实已被验证。

SVG 为什么在 README 里看起来不一样？

检查 GitHub/浏览器的深浅主题、字体回退和 SVG 尺寸属性。Archify 的 SVG 会根据 prefers-color-scheme 调整主题，因此本地浅色预览与他人深色主题下的显示本来就可能不同；应在两种主题下检查可读性。

小结

Archify 的高效用法是：按范围安装到 Codex 或 Claude Code，先让 Agent 从仓库梳理组件与未知项，再分别生成架构图、流程图或时序图，最后将经过人工事实核对的 SVG 和生成假设一并保存。这样得到的不只是“漂亮图”，而是可以随项目演进维护的技术文档。

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

Wed, 15 Jul 2026 22:02:00 +0800

技术图“能画出来”和“能拿去评审”是两回事。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 的基础检查：

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、导出文件和事实关系；图不对时优先修输入与视图选择，而不是反复要求“画得更漂亮”。

Archify on KnightLiブログ

Archify を Codex/Claude Code にインストールする方法: ウェアハウスからアーキテクチャ図、フローチャート、SVG を生成する

选择全局、项目级还是临时试用

手动安装到 Codex CLI 与 Claude Code

从仓库生成第一张架构图

从仓库生成流程图与时序图

生成后先交付 HTML，再导出 SVG

把图表变成可复现的仓库资产

常见问题

安装后 Codex 或 Claude Code 找不到 Archify，怎么办？

为什么生成的图没有反映真实仓库？

SVG 为什么在 README 里看起来不一样？

小结

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

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

安装 Archify Skill

先验证安装，再让 Agent 画图

Archify 输出为何更容易验证

如何检查最终图表

图不对时，按这个顺序修

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

常见问题

Archify 能替代 Mermaid 吗？

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

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

小结

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