Archify 怎麼安裝到 Codex/Claude Code：從倉庫生成架構圖、流程圖與 SVG

給項目補架構圖時，最耗時的往往不是畫框，而是先讀倉庫、確定邊界、把一條關鍵路徑講清楚，再導出能放進 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 和生成假設一併保存。這樣得到的不只是“漂亮圖”，而是可以隨項目演進維護的技術文檔。