Archify：讓 Coding Agent 產生可驗證、可互動的架構圖

Agent 畫架構圖，第一版方塊和箭頭通常很快。真正容易出事的是第二輪：想改一條路徑，整張圖跟著漂移；線穿過節點；label 蓋住另一條線；export 後才發現字太小；圖上寫了某個 service，卻沒人知道它對應哪個 commit。

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]

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 能把這些已知事實整理成可檢查 artifact；它不會代替 source code、telemetry、policy 或人的架構判斷。[2][3]

五種圖，不用拿一張 flowchart 硬講所有事情

Archify 目前有五個 typed renderer。每個 renderer 都有自己的 schema 與 structural arrays，會按圖型檢查不同結構。[2][5]

這個拆法讓 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：

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 提供這條：

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 描述：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

這個 prompt 只提供拓樸骨架。若要讓圖能拿去做 architecture review，需求最好再補 scope、主要路徑、external dependency、trust boundary，以及希望控制在多少個核心 component。

例如 repo-backed 的 prompt 可以寫：

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：

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 仍然是：

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]

這個決定也帶來清楚的取捨：

若需求只是 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，可以設：

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
• 2：Archify README at inspected commit
• 3：Archify Skill contract at inspected commit
• 4：Archify package metadata at inspected commit
• 5：Archify JSON IR schema contract
• 6：Archify delivery contract
• 7：Archify roadmap and Mermaid boundary
• 8：Archify v2.16.0 release
• 9：Archify MIT license
• 10：Archify official project page
• 11：Archify update manifest contract

<!-- [1] https://github.com/tt-a1i/archify [2] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/README_EN.md [3] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/SKILL.md [4] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/package.json [5] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/schemas/README.md [6] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/references/delivery-contract.md [7] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/ROADMAP.md [8] https://github.com/tt-a1i/archify/releases/tag/v2.16.0 [9] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/LICENSE [10] https://tt-a1i.github.io/archify [11] https://github.com/tt-a1i/archify/blob/5de7275fe87a66a19d52a4d9b0b3a4f2a5a90115/archify/scripts/update-contract.mjs -->