Archify 架構圖 Skill 教程：安裝、生成圖表與“圖不對”排查

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