--- slug: archify-agent-skill-verifiable-interactive-diagrams title: "Archify：讓 Coding Agent 產生可驗證、可互動的架構圖" status: published excerpt: "Archify 用 typed JSON IR 與本機 CLI，讓 Coding Agent 交付可驗證、可互動的架構圖。" category: AI tags: [agent, architecture-diagram, diagram-as-code, codex, claude-code] author: Seer author_role: Author read_time: 12 min cover: "/static/archify-agent-skill-verifiable-interactive-diagrams-cover.png" closing_note: "" published_at: "2026-08-31T19:16:40Z" updated_at: "2026-08-31T19:16:40Z" --- Agent 畫架構圖，第一版方塊和箭頭通常很快。真正容易出事的是第二輪：想改一條路徑，整張圖跟著漂移；線穿過節點；label 蓋住另一條線；export 後才發現字太小；圖上寫了某個 service，卻沒人知道它對應哪個 commit。 [Archify](https://github.com/tt-a1i/archify) 想處理的就是這段。它把「Agent 直接吐最終圖片」拆成一條可檢查的 pipeline：coding agent 先寫 typed JSON IR，本機 CLI 再做 schema、語意、layout／composition 與 artifact checks，全部通過後才交付自包含 HTML 與 inline SVG。[1][2] Archify 的產品層是 **Agent Skill 加上本機 Node.js renderer／validator**。Hosted 畫圖網站與 Mermaid theme 屬於不同類工具。它把 Agent 的判斷留在內容選擇與 layout，把可重複的檢查交給 deterministic code。 > 本文以 `main` commit `5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115` 與 stable release `v2.16.0` 為界。文中能力說明以該版本的 README、schema、CLI source、release 與 license 為準；實際安裝與 runtime 結果仍會隨環境改變。[2][8] ## 它把畫圖拆成 Agent 判斷與 deterministic compiler Archify 的輸入可以是一段系統描述，也可以是 Agent 對 repository 的分析。Agent 先產生一份結構化 JSON：有哪些 component、boundary、connection，哪條是主路徑，哪些資訊該放進 summary card；HTML 留給 renderer 統一產生。 JSON 進入 Archify 後，才開始跑 schema validation、跨欄位語意檢查、route／label／node composition checks。最後輸出的是一個帶 inline SVG 和 viewer runtime 的 HTML 檔。[3][5] ```mermaid flowchart LR A["系統描述或 Repo 證據"] --> B["Coding Agent + Archify Skill"] B --> C["Typed JSON IR"] C --> D["Schema / Semantic / Composition Validation"] D -->|通過| E["Atomic Deliver"] D -->|失敗| F["Structured Diagnostics"] F --> C E --> G["Standalone HTML + Inline SVG"] G --> H["Visual Check + 人工 Review"] G --> I["PNG / SVG / WebM / Share Card"] ``` 這條 pipeline 的價值，在於每一層都有不同責任。Agent 負責判斷哪些資訊值得出現在圖上；JSON IR 讓修改可以被 diff；validator 擋掉結構與幾何錯誤；browser review 才負責最後的視覺判斷。 如果讓 LLM 一次生成幾千行 HTML、CSS、SVG 和 JavaScript，後續通常很難只改一個節點。Archify 把真正需要反覆修改的內容留在 JSON，viewer 與 export code 則由 renderer 統一產生。 先把它放進實際工作流看，邊界會比較清楚： | 使用場景 | Archify 提供什麼 | 後續還需要什麼 | |---|---|---| | Repo architecture review | Source-backed Architecture、stable IDs、delivery receipt | 人工確認 component 選擇，以及 runtime／deployment 事實 | | CI/CD 或 Agent runbook | Workflow lanes、branch、main path 與 structured diagnostics | 真實 owner、approval policy、failure／rollback path | | API／cache 行為說明 | Sequence participant、message、return 與 guided view | Trace、log、latency 等 observability evidence | | Data governance review | Data Flow stage、flow、classification 與 boundary | 真實 lineage、PII policy、retention／access control | | Job／order／agent state machine | Lifecycle state、retry、wait 與 terminal outcome | 實作 code、test 與 production transition evidence | Archify 能把這些已知事實整理成可檢查 artifact；它不會代替 source code、telemetry、policy 或人的架構判斷。[2][3] ## 五種圖，不用拿一張 flowchart 硬講所有事情 Archify 目前有五個 typed renderer。每個 renderer 都有自己的 schema 與 structural arrays，會按圖型檢查不同結構。[2][5] | 圖型 | 適合回答的問題 | 主要資料結構 | |---|---|---| | **Architecture** | 系統有哪些服務、storage 與 trust boundary？ | `components`、`boundaries`、`connections` | | **Workflow** | 流程怎麼推進，在哪裡審批、分支或回滾？ | `lanes`、`phases`、`mainPath`、`nodes`、`edges` | | **Sequence** | 一次 request、cache miss 或 auth flow 怎麼發生？ | `participants`、`segments`、`messages`、`activations` | | **Data Flow** | 資料從哪裡來，在哪裡轉換或跨越 PII 邊界？ | `stages`、`nodes`、`flows` | | **Lifecycle** | 狀態如何等待、重試、取消與抵達 terminal outcome？ | `lanes`、`states`、`transitions` | 這個拆法讓 validator 能理解不同圖型的結構。Sequence 可以檢查 participant 與 message；Lifecycle 可以檢查 state 與 transition；Architecture 才需要 component、boundary 與 repository evidence。 所有 schema 都要求 `schema_version`、`diagram_type`、`meta.title` 與對應的結構陣列。各層設有 `additionalProperties: false`，欄位拼錯時會直接失敗，不會默默忽略後產出一張看似正常的圖。[5] ## 先釐清安裝：它走 Agent Skill 發行 最快的安裝方式是透過 `skills` CLI： ```bash npx skills add tt-a1i/archify -g ``` 這會把 Archify 安裝成 Agent Skill。Repo 內的 `archify/package.json` 明確設為 `private: true`，用途是替 Skill 內的 CLI、測試與開發 dependency 定義 package metadata；公開文件也沒有提供 `npm install archify` 的 application library 路徑。[2][4] 如果只想暫時交給 Codex 使用，README 提供這條： ```bash npx skills use tt-a1i/archify@archify --agent codex ``` README 目前列出的主要 surface 包含 Cursor、Claude Code、Codex CLI 與 OpenCode。Raven 走手動 ZIP；DeepSeek Harness 則是 community developer-preview integration，不能寫成 DeepSeek 官方能力。[2] 執行環境需要 Node.js 18 以上。一般使用者不必先學 JSON schema，可以直接在 agent chat 描述： ```text Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. ``` 這個 prompt 只提供拓樸骨架。若要讓圖能拿去做 architecture review，需求最好再補 scope、主要路徑、external dependency、trust boundary，以及希望控制在多少個核心 component。 例如 repo-backed 的 prompt 可以寫： ```text Analyze this repository, then use archify to create a high-level runtime architecture diagram. Show 8–12 core components, one primary path, external dependencies, and trust boundaries. Put supporting detail in cards instead of adding more edges. ``` 這段要求 Agent 先讀 repo，再把主線壓在 8–12 個 component。它沒有要求「把所有檔案畫進去」，因為架構圖資訊越多，不代表越容易讀。 ## `validate` 和 `deliver` 才是 Archify 真正有差的地方 Archify 把 AJV Draft 2020-12 schema 預編譯成 committed standalone ESM validator。安裝後跑 schema validation 不需要再 `npm install`，也不需要連網下載 AJV。[5] 手動整合或除錯時，可以直接跑 CLI： ```bash node bin/archify.mjs doctor node bin/archify.mjs guide "Show an API request with a Redis cache miss" --json node bin/archify.mjs validate architecture diagram.json --quality showcase --json node bin/archify.mjs deliver architecture diagram.json diagram.html --quality showcase --json node bin/archify.mjs visual-check diagram.html --json ``` `guide` 只建議該用哪一種圖與 recipe，不會直接生成成品。`validate` 負責 schema、語意與 composition diagnostics；`deliver` 才是正式 handoff；`visual-check` 則收集 browser evidence。[3][6] 驗證失敗時，JSON receipt 可以帶回 stable rule code、subject、measured evidence 與 `supportedFixes`。Agent 可直接針對被點名的 node、relationship 或 label 修改 JSON，不必從 Node stack trace 猜問題位置。[3] `deliver` 的處理更接近一個小型 transaction。它先讀一次 specification，將 exact bytes 凍結到 output 同 filesystem 的 staging directory，render candidate、執行 artifact checks，再計算 specification 與 artifact 的 SHA-256 和 byte count。最後一個 commit point 才用 rename 替換 output；前面任一步失敗，上一份可信檔案都應保留。[6] 這能解決一個常見問題：Agent 產出新版圖失敗時，不應順便把上一版可用 HTML 蓋掉。Archify 把「產生 candidate」和「交付 trusted artifact」分開，讓 CI 或 agent controller 可以根據 exit code 與 receipt 決定下一步。 ## 自動檢查能擋錯，不能替你判斷好不好看 `visual-check` 會透過 Chrome／Chromium DevTools 測量四個 desktop viewport：1440×900、1600×1000、1920×1080、2048×1320，並產生 light／dark screenshot、contact sheet 與 JSON receipt。[6] 不過 receipt 的 `visualReview` 永遠維持 `pending`。Exit 0 只代表 containment 與 capture 通過；構圖品質與技術敘事仍要人工判斷。若找不到 Chrome，狀態會是 `skipped`。[3][6] 這個邊界值得保留。程式可以檢查 overflow、edge 穿過 node、label 和 route 太近、非有限座標或錯誤 schema；它很難替讀者判斷主線是否明顯、視覺權重是否合理、哪個資訊應該刪掉。 所以完整 handoff 仍然是： ```text validate → deliver → visual-check → 人工看最終 HTML ``` 只跑到 `deliver`，可以說 deterministic checks 通過。要寫 `visual_review: passed`，仍得真的看過最後產物。 ## 成品是可互動的單檔 HTML Archify 生成的 HTML 帶有 viewer runtime。讀者可以 search node、focus、查看 Semantic Passport、沿 authored relationship 查 upstream／downstream、找兩點間的 directed route、播放 guided view，或切到 Presentation Stage。[2][3] 圖的樣式目前有 Classic、Signal Flow、Blueprint、Editorial，theme 可以切 dark／light。這些 preset 只改 presentation，不改 semantic ID、topology 與 geometry。[5][10] Export menu 可以產生 PNG、JPEG、WebP、SVG、WebM，以及 1200×630 Share Card。Route／Reach Share Card 則保留完整圖當 context，再標示當前選定路徑或 authored reachability。[2][3] 這裡不能把 route 或 reach 寫成 runtime trace、blast radius 或 impact analysis。Viewer 查的是 JSON 中已 authored 的 relationship；它沒有觀察 production traffic，也沒有執行 static call graph 或 distributed tracing。[3] Canonical export 也會移除 finder、focus、story、route、camera 和其他暫時 viewer state。換句話說，你在畫面上探索某條路徑，不會偷偷改掉下一張普通 SVG 或 PNG 的 canonical meaning。[3] ## Repository evidence 能釘 source，但不會自動發現真實架構 Architecture mode 可以選擇加入 public GitHub evidence。JSON 先宣告 repository URL 與完整 commit SHA，component 再掛 1–3 個 repo-relative source path 和 optional line range。執行時必須提供 `--repo-root`，Archify 會核對 local origin、commit、blob 與 requested lines。[5] 這項能力讓圖上的 node 可以連回「哪一個 revision 的哪一段 source」。它仍不會替你判斷所有 component，也不會從 code 自動推導 production deployment、owner、network policy 或 runtime causality。 Architecture 還有 opt-in 的 `deployment-ownership` engineering profile，可以要求每個 non-external component 有 owner、位於單一 region、database 在 security group 內，跨 boundary 的 connection 要寫出 mechanism。[5] 這些檢查只驗證 authored IR 是否完整。若 owner 或 region 本來不知道，正確做法是先補來源，或不要開 profile；不能讓 Agent 為了過 validator 自己發明答案。 ## 它跟 Mermaid 的關係，比「漂亮版 Mermaid」更遠 Archify 可以接受 Mermaid 當輸入，但目前沒有 Mermaid parser。Skill 會讓 Agent 讀 `flowchart`、`sequenceDiagram` 或 `stateDiagram` 的語意，再重新 author Archify JSON；renderer 不會直接解析原 Mermaid 後換 theme。[3][7] Roadmap 記錄過一次 auto-layout＋Archify CSS 的 blind comparison。維護者認為自動排版版本沒有比 stock Mermaid 明顯更好，只有手動／Agent deliberate placement 的版本達到目標，因此停止 parser 與 general auto-layout 路線。[7] 這個決定也帶來清楚的取捨： | 情境 | Mermaid | Archify | |---|---|---| | Markdown 內的小型圖 | 文字短、容易 diff、直接 render | 成本偏高 | | 快速表達 flow | 語法直接，自動 layout | 要多一層 JSON IR 與 validation | | PR／ADR／架構提案的正式 artifact | 需要自己補視覺與 QA | 有 typed source、receipt、interactive viewer、export | | 手動拖拉編輯 | 不適合 | 也不適合；它沒有 WYSIWYG | | 任意大型 graph 自動排版 | Mermaid／其他 graph engine 較接近需求 | General auto-layout 明確不在 scope | | Hosted collaboration | 可接其他平台 | Archify 本身不提供 hosted sharing | 若需求只是 README 裡畫 Browser → API → DB，Mermaid 仍是最省事的選擇。Archify 比較適合「架構圖本身就是交付物」的情境：要進 review、提案、文件首頁、release 或簡報，而且後續還會反覆修改。 ## 單檔 HTML 不等於完全零外連 Archify 的 HTML 不需要 hosted viewer runtime，SVG、互動與 export code 都跟著檔案走。這使它可以直接放進 artifact、release 或靜態網站。[2][6] 但目前 template 會非阻塞嘗試載入 Google Fonts。網路失敗不會擋 first paint，字型會回退到本機或 system monospace。因此這裡應寫成「不依賴 hosted Archify runtime」，不能宣稱保證零外部 request。 Skill 本身還有 optional update reminder。它會 GET 固定的 GitHub Pages stable manifest，成功後約 72 小時才再檢查；不會下載、安裝或覆寫更新。README 說 request 不帶版本、Agent、project data、prompt、account／device ID 或 ETag，但 server 仍會看到一般 HTTP metadata，例如 IP 與時間。[2][11] 如果環境要求完全關閉這段 network 與 reminder-state write，可以設： ```bash export ARCHIFY_UPDATE_CHECK_DISABLED=1 ``` 這個設定適合 air-gapped、嚴格 CI 或不希望 Skill 主動查版本的環境。它不會把 Google Fonts link 從已生成 HTML 移除；那是另一個 artifact-level 邊界。 ## 導入前，我會先看這四件事 第一，團隊是不是已經用 coding agent。Archify 的核心是 Skill 讓 Agent author JSON；若流程裡沒有 Cursor、Claude Code、Codex 或 OpenCode，直接手寫 JSON 的吸引力會小很多。 第二，圖是不是正式 deliverable。若架構圖需要 source evidence、review receipt、share card、presentation 或多輪修改，這套 pipeline 有明確價值。一次性草圖則未必值得多一層工具。 第三，能不能接受 Agent 參與 layout。Archify 明確不走 generic auto-layout。Agent 的 hierarchy、spacing、route 與 emphasis 判斷是產品的一部分，也代表模型和 prompt 仍會影響品質。 第四，能不能保留人工 review。Validator 能擋掉很多機械錯誤，卻不能證明資訊取捨正確。Repo evidence 也只證明引用的 commit／file／line，不能證明圖已完整描述 production。 ## 我會怎麼選 文件內的小圖，我會繼續用 Mermaid。它短、可 diff、render surface 多，幾行文字就能把 flow 說清楚。 當架構圖要進 PR review、ADR、技術提案或簡報，而且希望保留可修改 source、validation receipt、互動探索與多格式 export，Archify 就開始合理。它的目的很明確：把 Agent 畫圖變成一條可以檢查、失敗時不會蓋掉舊成品的交付流程。 目前 `v2.16.0` 以 MIT license 發布，root license 同時保留 tt-a1i 與原始 Cocoon AI `architecture-diagram-generator` 的 attribution。[8][9] 如果要導入，我會先選一張 8–12 個核心 component 的真實架構圖做 pilot。先比較 JSON 是否容易修、validator 是否真的減少返工、最終 HTML 是否比 Mermaid 更適合 review，再決定要不要把它放進固定文件流程。 ## Sources - [1：Archify official repository](https://github.com/tt-a1i/archify) - [2：Archify README at inspected commit](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/README_EN.md) - [3：Archify Skill contract at inspected commit](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/SKILL.md) - [4：Archify package metadata at inspected commit](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/package.json) - [5：Archify JSON IR schema contract](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/schemas/README.md) - [6：Archify delivery contract](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/references/delivery-contract.md) - [7：Archify roadmap and Mermaid boundary](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/ROADMAP.md) - [8：Archify v2.16.0 release](https://github.com/tt-a1i/archify/releases/tag/v2.16.0) - [9：Archify MIT license](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/LICENSE) - [10：Archify official project page](https://tt-a1i.github.io/archify/) - [11：Archify update manifest contract](https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/scripts/update-contract.mjs)