---
slug: archify-2-17-artifact-evidence
status: published
title: "Archify 2.17 開發版：技術圖也該有可追的交付收據"
excerpt: "Archify 把 agent 畫圖拆成 typed JSON、deterministic delivery、browser evidence 與人工視覺判讀；這篇整理 2.17 開發版補上的交付與授權邊界。"
category: AI
tags: [agent, architecture-diagram, diagram-as-code, coding-agent, validation]
source_repository: "https://github.com/tt-a1i/archify"
source_ref: "06dd052602dd9a369e4d034e24faef0917b5a60c"
research_boundary: "Static repository inspection only; Archify, its CLI, validators, update checker, and browser checks were not executed."
author: Seer
author_role: Author
read_time: 11 min
cover: "/static/archify-2-17-artifact-evidence-cover.png"
closing_note: ""
published_at: "2026-09-04T12:38:36Z"
updated_at: "2026-09-04T12:38:36Z"
---

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

[Archify](https://github.com/tt-a1i/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 將整個流程拆解為四個階段：

| 階段 | Archify 管什麼 | 不能因此宣稱什麼 |
|---|---|---|
| 作者／agent | 依需求選擇 architecture、workflow、sequence、dataflow 或 lifecycle，建立 typed JSON IR | 不代表系統拓撲已由工具自動發現 |
| validator | schema、跨欄位約束、layout 與 composition 規則 | 不等於圖已符合團隊的商業或架構判斷 |
| `deliver` | 將通過 gate 的候選產物以原子方式交付，並回傳 spec／artifact 的 receipt | 不等於人已看過圖是否好讀 |
| `visual-check` 與人工審閱 | 前者收集限定 viewport 的 browser evidence；後者判斷閱讀性 | browser measurement 不等於美感或溝通品質保證 |

這種拆法帶來很直接的好處：圖的內容、編譯結果與視覺審查各有一份獨立證據。當 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 載明的基本操作路徑如下（此為已查核的文件指令，本次並未實際執行）：

```bash
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 或任何識別資訊；由於本次並未實際抓取網路封包，此處僅作為原始碼與文件層面的觀察記錄，不作流量層級的背書。

## 導入場景與衝突邊界

| 場景 | 交付任務形狀 | 至少要留下的證據 | 容易衝突的邊界 |
|---|---|---|---|
| PR 設計說明 | 將架構改動轉成一份 JSON spec 與 standalone HTML | `validate` diagnostics、artifact receipt、reviewer 的閱讀確認 | IR 能描述設計決定，不能替代設計決定本身 |
| 長期維護文件 | 隨服務、資料流或流程變更更新同一份圖表規格 | spec diff、renderer output、適用 viewport 的 browser evidence | browser measurement 只驗畫面行為，資訊階層仍要由人判讀 |
| 發給外部協作方的技術說明 | 交付可開啟的 HTML 圖表與來源規格 | 已通過 gate 的 artifact、來源版本、人工簽核紀錄 | third-party marks 另受商標與品牌規範限制 |

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

## 可直接貼進 Issue 的交付模板

```markdown
### 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](https://github.com/tt-a1i/archify/tree/06dd052602dd9a369e4d034e24faef0917b5a60c)
- [2: README_ZH.md at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/README_ZH.md)
- [3: Archify Skill contract at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/archify/SKILL.md)
- [4: package metadata at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/archify/package.json)
- [5: JSON schema documentation at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/archify/schemas/README.md)
- [6: changelog at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/CHANGELOG.md)
- [7: MIT license at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/LICENSE)
- [8: third-party mark notices at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/archify/THIRD_PARTY_NOTICES.md)
- [9: update-check implementation at inspected commit](https://github.com/tt-a1i/archify/blob/06dd052602dd9a369e4d034e24faef0917b5a60c/archify/scripts/check-update.mjs)