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 架構圖 Skill 教程：安裝、生成圖表與“圖不對”排查

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、導出文件和事實關係；圖不對時優先修輸入與視圖選擇，而不是反覆要求“畫得更漂亮”。