Archify 2.17 開發版：技術圖也該有可追的交付收據

Archify 的核心概念，是讓 coding agent 產出可驗證、可追溯的技術圖表。流程上它會先將系統描述轉成 typed JSON IR，再透過 Node.js renderer 與 validator 編譯成包含 inline SVG 的獨立 HTML 檔。目前 main 分支在本次查核時宣告為 v2.17.0-dev.1，屬於開發中版本，不能直接視為 stable release。[1][2][4]

這篇接續先前的基礎介紹。舊文談過 Archify 如何把架構圖、流程圖、循序圖、資料流與生命週期圖整合進 agent 工作流；這次聚焦實務上容易混在一起的三個層次：交付產物是否通過 deterministic checks、瀏覽器渲染是否經過量測，以及人類是否實際確認過視覺易讀性。 Archify 在 2.16／2.17 把這三件事拆開，正好對應 PR、設計 review 與技術文件的交付流程。[2][3][6]

本篇僅針對固定 commit 06dd052602dd9a369e4d034e24faef0917b5a60c 進行 static repository inspection，包含檢視 README、Skill contract、schema、package metadata、changelog、license 與 update-check 原始碼。過程中並未安裝 skill，也未執行 doctor、validate、deliver、visual-check 或產生任何圖表。文內提及的所有指令與功能均屬文件或原始碼所規範的 contract，並非本機實測數據。

先看重點

• 先建立同一份 IR，再談圖。 Archify 把圖表內容固定在 typed JSON，讓 agent 可以依 diagnostics 局部修正，不需要每次從視覺 prompt 重來。
• 把「已驗證」拆成三張收據。 deterministic artifact checks、browser evidence 與人工視覺審閱各自回答不同問題，不能互相代替。
• 適合進 repo 的技術圖交付。 PR 設計說明、長期維護的文件與需分發的 standalone HTML 都是適用場景；一次性的會議草圖則選更快的工具。

先講結論： 如果團隊只是開會時想快速畫張草圖，Mermaid 或線上白板會更省事；但若這張圖要進 repo 當文件、作為 PR 的設計審查佐證，或是產出可分發的 HTML artifact，Archify 的 typed IR、驗證機制與 delivery receipt 才有接入流程的價值。

Archify 交付的是一條可追的鏈

Agent 畫圖真正棘手的地方，常常出現在來回修改兩輪之後：很難追溯它最初依據哪份結構化規格、通過了哪些檢查規則，以及哪份 HTML 才是最終交付物。

Archify 將整個流程拆解為四個階段：

這種拆法帶來很直接的好處：圖的內容、編譯結果與視覺審查各有一份獨立證據。當 reviewer 追問「這張圖依據哪份規格產出？」「進 PR 前有沒有過驗證？」「版面有人肉眼看過嗎？」，回答時就能給出具體憑據，不必含糊地回一句「都驗過了」。Skill 文件也明確界定：deliver 負責保證 deterministic artifact checks；visual-check 負責提供 bounded browser behavior；至於整體的視覺閱讀體驗，則必須由工程師或具備影像能力的 reviewer 另外判讀。[3]

typed JSON IR 讓 agent 有可修的對象

Archify 的五種 renderer 都以 JSON intermediate representation 作為輸入。schema 規範了 schema_version、diagram_type、帶有 title 的 meta，以及各模式專屬的結構陣列；各層皆以 additionalProperties: false 阻擋未定義欄位，避免 agent 拼錯 key 卻被系統默默吞掉。此外，Workflow 的 schema v2 提供了 readable layout contract，舊版 schema v1 則保留對既有 fixed geometry 的相容性。[3][5][6]

相較於把 prompt 丟給影像模型生成圖片，這種做法更符合工程需求——agent 可以精確修改 diagnostics 指出的節點或關聯，不需要整張圖重畫。Skill 要求產製新圖時必須先產生 candidate，接著執行 validate --json；若驗證失敗，再依據 diagnostics[] 裡的 subject、evidence 與 supportedFixes 進行局部修復。規範中甚至明定「驗證成功後不得再更動 candidate」，確保 receipt 雜湊能精準對應同一份 spec bytes。[3]

README 載明的基本操作路徑如下（此為已查核的文件指令，本次並未實際執行）：

npx skills add tt-a1i/archify -g

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

archify/package.json 宣告執行環境需 Node.js >=18。由於 schema 在開發階段就已編譯成 committed standalone validators，因此 README 與 schema 文件說明已安裝的 skill 在一般 runtime validation 下不需要執行 npm install 或連網。這是 package 與文件層面的設計承諾，但仍需視不同 agent host 的安裝與執行環境而定。[2][4][5]

visual-check 提供 browser evidence

2.14 版加入的 visual-check 會針對 1440×900、1600×1000、1920×1080 與 2048×1320 檢查 first-screen containment，並擷取 light／dark 模式的 evidence。這對抓出桌機環境下的橫向 overflow、首屏大片留白或圖形過小等可量化問題相當有用。[3][6]

這項檢查無法直接等同於「視覺品質保證」。Skill contract 將 machine-readable measurements 與截圖定義為 browser evidence，並要求團隊仍需留存人工視覺審查紀錄。這能防止團隊將「viewport 沒有跑版」誤判成「架構表達清楚、重點突出、文字易讀」。

實務上建議將交付 checklist 拆為三軌：JSON／artifact receipt 交給 CI 驗證；visual-check 的數據作為 browser gate；最後由設計或技術 reviewer 快速掃過主路徑、資訊階層與文字密度。這是建議的工作流程，而非 Archify 內建的自動化行為。

目前版本更重視 distribution 的邊界

固定 commit 的 changelog 將 v2.17.0-dev.1 標示為 Unreleased。這一版主要補齊兩項 distribution hygiene：保留 Cocoon AI 的 MIT copyright notice，並在 source／Skill distribution 中完整保留第三方 mark notices。前者關係到 packaged license 的 provenance，後者則釐清內建品牌圖示的使用邊界。[6]

需要注意的是，根目錄 LICENSE 的 MIT 授權不能隨意套用到所有品牌素材。THIRD_PARTY_NOTICES.md 寫得很清楚：Archify 的 MIT 只涵蓋 Archify 本身的 code 與 content，第三方 marks 的版權、商標規範與 brand guideline 依然獨立有效。以 Simple Icons 為例，即使 collection 本身以 CC0 釋出，也不代表其中每個品牌圖示都能無條件商用或再分發。若要將帶有第三方 mark 的圖表用於行銷文宣、商業簡報或產品頁面，仍須自行確認個別商標的授權條款。[7][8]

更新通知是可關閉的資訊提示

2.16 版加入了一個非強制、notification-only 的 skill update check。根據 README 說明，該功能僅在有新版時顯示提示，不會自動下載或安裝；固定的 manifest 位址為 GitHub Pages 上的 stable.json，使用者可透過設定 ARCHIFY_UPDATE_CHECK_DISABLED=1 完全關閉連線請求與通知狀態寫入。固定 commit 中的 check-update.mjs 也確實包含這段 disable 邏輯。[2][6][9]

這項功能應就其設計範疇來理解：它純粹是 packaged skill 的版本通知機制，而非 telemetry 系統，但也不代表安裝後完全零網路行為。README 載明請求時不會傳送本地版本、專案路徑、prompt 或任何識別資訊；由於本次並未實際抓取網路封包，此處僅作為原始碼與文件層面的觀察記錄，不作流量層級的背書。

導入場景與衝突邊界

一次性的會議草圖、尚未形成的探索問題，以及需要自動從 repo 還原 runtime topology 的任務，不該硬塞進這條流程。Archify 不會從程式碼反推實際拓撲，也不會替你決定資料邊界、服務職責或架構權衡；agent 與開發者填入 IR 的內容才是圖表資訊的來源。

可直接貼進 Issue 的交付模板

### Diagram delivery
- 圖表類型：architecture / workflow / sequence
  dataflow / lifecycle
- 要回答的問題：
- IR source：`<path-or-commit>`
- Artifact：`<html-path-or-url>`
- Deterministic checks：pass / diagnostics link
- Browser evidence：viewport、截圖或量測紀錄
- Human review：reviewer、日期、待修正項目
- 已知邊界：圖表未涵蓋的服務、資料或執行期行為

這份模板的目的，是在 ticket 裡把需求、產物和驗證拆開記錄。當內容變更時，下一位維護者可以直接追到 IR、HTML 與 review 結果。

結論：把「已驗證」拆成可以追問的三句話

Archify 在 2.17 開發版持續推進的方向，是將技術圖表做成規格嚴謹、可追溯的交付 artifact。團隊討論「這張圖有沒有驗證過」時，可以改問三個更精確的問題：spec 有沒有通過 deterministic checks？畫面有沒有 browser evidence？最後，有沒有人實際確認過它的易讀性？

這三個問題對應不同的負責角色與檢驗憑據。把界線劃分清楚，agent 生成的技術圖表就能進入日常工程流程，也能讓後續 review 有可追的依據。

Sources

• 1: Archify repository at inspected commit
• 2: README_ZH.md at inspected commit
• 3: Archify Skill contract at inspected commit
• 4: package metadata at inspected commit
• 5: JSON schema documentation at inspected commit
• 6: changelog at inspected commit
• 7: MIT license at inspected commit
• 8: third-party mark notices at inspected commit
• 9: update-check implementation at inspected commit