Cómo instalar Archify en Codex/Claude Code: genere diagramas de arquitectura, diagramas de flujo y SVG desde el almacén

给项目补架构图时，最耗时的往往不是画框，而是先读仓库、确定边界、把一条关键路径讲清楚，再导出能放进 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 时会随读者系统主题变化。提交前仍应在浅色、深色和目标渲染平台各打开一次，确认字体回退、线条和文字对比度符合预期。

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

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

1
2
3
4
5


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

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

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

1
2
3
4


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 和生成假设一并保存。这样得到的不只是“漂亮图”，而是可以随项目演进维护的技术文档。