Archify 架構圖 Skill 教學：安裝、儲存庫分析、驗證與疑難排解

Archify 是一個面向 Codex CLI、Claude Code、Cursor、OpenCode 和 Raven 的 Agent Skill。它把系統描述或程式碼儲存庫轉換成可互動的技術圖，而不是簡單地把一段文字套進通用流程圖模板。

產生結果以類型化 JSON IR 為事實來源，經驗證後交付自包含 HTML；瀏覽器內也可以匯出 PNG、SVG、WebM 和 1200×630 分享卡。它適合架構評審、README 配圖、故障路徑說明和變更前後對比，但不能取代原始碼、部署設定和運行日誌的審查。

項目地址：tt-a1i/archify

先判斷 Archify 是否適合目前任務

Archify 提供五種主要圖表類型：

不要把所有資訊塞進一張 Architecture 圖。登入要求的快取回退適合 Sequence；CI 的核准和回溯適合 Workflow；訂單狀態轉換較適合 Lifecycle。

Archify 也不是 Mermaid 主題、線上主機平台或 WYSIWYG 編輯器。官方明確把自動解析 Mermaid、通用自動佈局、託管分享和所見即所得編輯放在目前範圍之外。

安裝前檢查 Node.js 與工作目錄

安裝指令透過 npx 執行，因此先檢查 Node.js 和 npm：

1
2
3

node --version
npm --version
npx --version

如果指令不存在，先安裝目前支援的 Node.js LTS，再重新開啟終端。不要在缺少 npx 時把安裝失敗歸因於 Codex 或 Claude Code。

同時確認要分析哪個儲存庫：

1
2

git rev-parse --show-toplevel
git status --short

工作區有未提交修改時仍可分析，但圖中的源碼證據必須與一個明確提交對應。用於正式評審時，先記錄：

1

git rev-parse HEAD

全域安裝 Archify Skill

官方快速安裝指令是：

1

npx skills add tt-a1i/archify -g

-g 表示全域安裝。各 Agent 的常見 Skill 位置不同：

安裝器會依目標 Agent 處理目錄，不建議手動把同一份 Skill 複製到多個未知位置。安裝完成後重新啟動 Agent，確保新會話重新掃描 Skills。

只想在 Codex 中臨時試用，可以執行：

1

npx skills use tt-a1i/archify@archify --agent codex

臨時試用適合驗證效果；要讓團隊穩定重現，應固定安裝方式，並在專案文件中記錄 Archify 儲存庫版本或提交。

驗證 Agent 是否真正呼叫了 Archify

不要僅憑「已安裝成功」判斷可用。新建會話後給予一個邊界明確的請求：

1
2
3

分析当前仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，标出一条主请求路径、外部依赖和信任边界。
把补充说明放进卡片，不要继续增加连线。

驗收時檢查三件事：

1. Agent 明確選擇並呼叫 Archify，而不是產生 Mermaid 程式碼冒充結果。
2. 輸出包含可以單獨開啟的 HTML，以及對應的類型化來源資料。
3. 圖中的元件、關係和邊界都能追溯到儲存庫或輸入描述，不出現無依據的服務。

若 Agent 只回傳一段解釋，先讓它說明 Skill 是否被發現，再檢查安裝目錄和新會話狀態。

從儲存庫產生第一張架構圖

高品質結果取決於範圍。可以使用下面的提示詞：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Use archify to map this repository's runtime architecture.

Scope:
- entry points and long-running processes
- API, worker, database, cache and external services
- one primary request path
- authentication and trust boundaries

Constraints:
- 8–12 main nodes
- do not infer services that are not present in source or configuration
- place evidence and secondary details in cards
- deliver the validated HTML and typed source together

對 monorepo，應先限定目錄：

1
2

只分析 apps/api、packages/auth 和 packages/database。
忽略 examples、generated、vendor 和构建产物。

如果不限定範圍，Agent 可能把測試、腳本和歷史實作都畫成生產組件，導致節點過多、邊的意義不清楚。

為特定連結選擇 Sequence 或 Data Flow

快取回退適合時序圖：

1
2
3
4

Use archify to draw this login sequence:
Browser -> Web App -> API -> JWT validation -> Redis session lookup.
When Redis misses, query PostgreSQL and repopulate Redis.
Show failure returns and timeout boundaries, but keep the happy path primary.

涉及隱私和資料處理時，改用 Data Flow：

1
2
3

画出用户上传文件后的数据流。
标出上传入口、病毒扫描、对象存储、元数据数据库、异步处理器和下载消费者。
明确包含个人信息的节点、跨边界传输和保留期限，不推测未提供的加密方式。

差別在於：Sequence 專注於呼叫順序；Data Flow 專注於資料移動、轉換、儲存和敏感邊界。

保留 JSON IR，不要只交付截圖

Archify 使用類型化 JSON IR 驅動渲染。團隊應同時保存：

• 原始 JSON；
• 驗證後的 HTML；
• 文檔所使用的 SVG 或 PNG；
• 生成時對應的 Git 提交；
• 人工審查記錄。

只保留 PNG 會失去可重複編輯和驗證能力。 HTML 適合交互查看，SVG 適合文件和版本管理，PNG 適合不支援 SVG 的平台。

建議目錄範例：

1
2
3
4
5

docs/architecture/
├── runtime.architecture.json
├── runtime.architecture.html
├── runtime.architecture.svg
└── README.md

在 README.md 中記錄範圍和提交：

1
2
3
4

Source revision: 4f2c1ab
Scope: apps/api, packages/auth, packages/database
Excluded: tests, generated, vendor
Review status: manually checked

用儲存庫 CLI 驗證與交付

如果需要直接呼叫 Archify 儲存庫內的驗證器，先複製專案並進入目錄：

1
2
3

git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

可以先查看內建範例：

1
2

node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"

驗證一個 Workflow JSON：

1
2
3
4

node bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

產生一次性可交付 HTML：

1
2
3
4
5
6

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

失敗時讀取 diagnostics[]、規則碼、具體物件和 supportedFixes，只修改被指出的問題。不要看到一次驗證失敗就讓 Agent 重寫整張圖。

本地預覽的安全邊界

需要邊改邊看時可用 preview：

1
2
3
4

node bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase

官方預覽模式只綁定 127.0.0.1 的隨機端口，並只監聽指定 JSON 檔案。候選文件未通過驗證時，瀏覽器繼續顯示上一份合格結果。

不要為了遠端存取把預覽服務改成 0.0.0.0。需要分享時交付自包含 HTML，或在受控文件系統中發佈靜態匯出檔。

用 Architecture Delta 檢討變更

設計或 PR 評審可以比較兩個已驗證快照：

1
2
3
4
5

node archify/bin/archify.mjs compare architecture \
  base.json \
  head.json \
  architecture-delta.html \
  --json

結果顯示 Before、Delta 和 After，並區分已新增、刪除、修改、移動或重路由的事實。它比較的是兩份已編寫並通過驗證的結構，不會自動判斷風險、影響範圍或是否可以合併。

因此仍需手動回答：

• 變化是否來自真實程式碼和配置；
• 信任邊界是否改變；
• 資料儲存或外部依賴是否新增；
• 部署順序和回滾是否需要調整；
• 測試是否覆蓋新的路徑。

圖表產生後如何驗收

先檢查事實，再檢查視覺：

事實檢查

• 入口是否與真實啟動指令一致；
• 服務關係是否能在程式碼、設定或文件中找到；
• 同步呼叫與非同步訊息是否區分；
• 資料庫、快取、佇列沒有被混成同一種儲存；
• 信任邊界和外部系統沒有被遺漏；
• 圖中沒有 Agent 自行補出的「常見組件」。

視覺檢查

• 主路徑能在數秒內辨識；
• 節點沒有互相遮擋；
• 連線沒有穿過標籤；
• 次要資訊沒有壓過主要關係；
• 深色和淺色主題都可讀；
• 導出的 SVG、PNG 與 HTML 表現一致。

可交付性檢查

• HTML 在斷網環境可以開啟；
• JSON 和 HTML 使用相同版本；
• 檔案名稱穩定，不含臨時隨機名稱；
• 圖中不包含金鑰、內網位址或客戶資料；
• Git 提交和產生範圍有記錄。

常見疑難排解

Agent 找不到 Archify

重新確認安裝和會話：

1

npx skills add tt-a1i/archify -g

然後完全退出並重新啟動 Codex 或 Claude Code。若同時存在多個 Skill 目錄，檢查 Agent 實際讀取哪一個，不要繼續重複安裝。

產生的是 Mermaid，而不是 Archify HTML

在提示詞中明確寫「use archify」並要求交付 validated HTML 和 typed source。仍未呼叫時，說明 Skill 未被發現或被其他規則覆蓋。

圖中元件過多

把請求縮小到一個執行時間路徑，限制 8–12 個主節點，並把日誌、指標、測試和輔助腳本移到說明卡。

圖的結構與原始碼不一致

先固定 Git 提交和分析目錄，再逐項刪除無法找到證據的節點。不要用「通常會有 Redis」這類經驗補全實際儲存庫。

驗證失敗但舊圖仍顯示

這是 last-good 預覽機制。檢視 diagnostics[]，修正目前候選；不要把舊圖仍可見誤判為新版本驗證成功。

SVG 在文件平台顯示異常

先在瀏覽器直接開啟 SVG，檢查字型、外部資源和裁切範圍。無法穩定展示時使用 PNG，但繼續保留 SVG 和 JSON 原始檔。

一份可重複使用的驗收清單

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[ ] 已记录 Archify 安装方式和版本
[ ] 已记录仓库 Git 提交与分析范围
[ ] 图表类型与问题匹配
[ ] 主路径、外部依赖和信任边界明确
[ ] JSON IR 与 HTML 同时保存
[ ] validate 或 deliver 返回成功
[ ] 图中每个关键关系都有输入或源码依据
[ ] 深色与浅色主题可读
[ ] SVG/PNG 导出可打开
[ ] 不包含密钥、内网地址或客户数据
[ ] 人工评审没有把图当作运行时事实证明

總結

Archify 的價值不是“一句話自動畫圖”，而是把技術描述整理為類型化、可驗證、可互動的交付物。可靠流程應為：限定範圍，選擇正確圖種，產生 JSON IR，透過驗證，人工核對事實，再交付 HTML 和靜態導出。

對程式碼儲存庫尤其要保留 Git 提交和分析範圍。圖表可以幫助團隊討論架構，但原始碼、設定、測試和執行資料仍是最終依據。