藍圖架構圖 是做什麼的？
一個像工程圖紙一樣繪製的系統：帶有網格的藍圖（或淺色「白圖」），每個元件根據類型以帶標籤的形狀呈現，請求使用實線箭頭，事件使用虛線箭頭，分組使用虛線區域，並包含圖例和標題區塊。您（或使用者）將系統描述為 diagram.json；一個腳本使用 dagre（已捆綁，無需安裝）進行佈局並繪製：
out/index.html：圖表，每個連線上有一個移動的點，事件線會流動。可從磁碟開啟，並自動縮放適配視窗。out/diagram.svg：沒有動畫的相同圖表，適用於文件、維基和幻燈片。out/diagram.png：兩倍尺寸的靜態圖像，透過無頭 Chrome 生成，適用於任何需要圖片的場合。
你需要什麼
- Node.js 18 或更新版本。建置不需要其他東西。
- Chrome、Chromium 或 Edge 用於生成 PNG。腳本會在常用位置尋找瀏覽器；如果找不到，請設定
CHROME_PATH。 - 開啟圖表或匯出時需要網際網路連線，以獲取 Google Fonts 的 JetBrains Mono 字型（如果沒有，則會回退到系統等寬字型）。
此技能的資料夾是 <skill>，即此 SKILL.md 檔案所在的資料夾。
步驟
1. 找出系統
當使用者描述系統時，使用他們的詞語。當要求讀取儲存庫時，請在繪製之前收集證據，並且只繪製你找到的內容：
- 可部署元件：
docker-compose*.yml服務、KubernetesDeployment、Helm chart、Procfile、無伺服器配置（serverless.yml、vercel.json、wrangler.toml）、Terraform 資源以及單體儲存庫中的應用程式（apps/、services/、packages/*中帶有啟動腳本的）。 - 資料儲存與中介軟體：映像和受管資源（postgres、mysql、mongo、redis、kafka、rabbitmq、sqs、s3），以及連線設定如
DATABASE_URL、REDIS_URL、KAFKA_BROKERS、儲存桶名稱。 - 連線：指向其他服務的 HTTP 用戶端和基礎 URL、gRPC stub、佇列生產者和消費者（主題和佇列名稱）、
depends_on、向第三方（Stripe、LLM API、電子郵件提供者）的對外呼叫。 - 呼叫端：網頁和行動應用程式、CLI、cron 作業、webhook。
保持 5 到 20 個節點。將副本和小型輔助工具合併到它們所屬的服務中；與其擠在一起，不如拆分成多張圖表（"sheet": "02 / 03"）。註明任何你推斷而非找到的內容，並告知使用者。
2. 編寫 diagram.json
{
"title": "訂單服務 · v2",
"subtitle": "系統架構 · 來自 /services 和 docker-compose.yml · 2026年10月21日",
"sheet": "01 / 01",
"direction": "LR",
"theme": "blueprint",
"groups": [{ "id": "core", "label": "訂單平台" }],
"nodes": [
{
"id": "gateway",
"label": "API 閘道",
"sub": "認證 · 速率限制",
"kind": "service"
},
{
"id": "orders",
"label": "訂單服務",
"sub": "v2 · Go · 6 個 Pod",
"kind": "service",
"group": "core",
"focus": true
},
{
"id": "db",
"label": "Postgres",
"sub": "訂單 · 庫存",
"kind": "database"
},
{
"id": "bus",
"label": "事件匯流排",
"sub": "Kafka · 3 個主題",
"kind": "queue"
}
],
"edges": [
{ "from": "gateway", "to": "orders", "label": "POST /orders" },
{ "from": "orders", "to": "db", "label": "SQL" },
{ "from": "orders", "to": "bus", "label": "order.created", "async": true }
]
}
| 欄位 | 說明 | 限制 |
|---|---|---|
title | 系統或視圖的名稱（必填）；也會顯示在標題區塊 | 60 |
subtitle | 圖表顯示的內容及其來源：來源和日期 | 100 |
sheet | 標題區塊中的圖表編號，例如 "02 / 03"（預設 01 / 01） | – |
direction | LR 從左到右（預設，適用於請求流程）或 TB 從上到下（管道） | – |
theme | blueprint（深藍色，預設）、whiteprint（淺色）或顏色：使用十六進位色的 { "paper", "line", "accent", "dim" } | – |
groups | 在其節點周圍繪製的區域：{ "id", "label" } | – |
nodes[].id | 字母、數字、- 或 _；邊線透過它來引用（必填） | – |
nodes[].label | 節點上的名稱（必填） | 28 |
nodes[].sub | 第二行：語言、執行階段、規模、包含的內容 | 36 |
nodes[].kind | 形狀：service（預設）、client、database、queue、cache、storage、function、external（第三方，虛線） | – |
nodes[].group | 群組 ID | – |
nodes[].focus | true 以強調色繪製：代表圖表主要關注的元件 | – |
edges[] | { "from", "to" } 節點 ID，方向表示資料或控制流程 | – |
edges[].label | 協定、端點、主題或動詞：HTTPS、POST /orders、order.created | 24 |
edges[].async | true 用於事件、佇列以及任何「發射後不理」的類型（虛線，流動） | – |
提示：
- 使用實際傳輸的內容為邊線添加標籤：端點、主題、資料表、動詞。只有在不會增加任何價值時才省略標籤。
- 邊線的方向應與請求的方向一致（從呼叫端到被呼叫端），事件的方向也應一致（從生產者到佇列再到消費者）。
- 最多將一個節點標記為
focus。 - 最多允許 40 個節點，但超過大約 20 個時，圖表會變得難以閱讀。
3. 建置並檢查
node <skill>/scripts/build.mjs diagram.json out
它會檢查檔案並一次性列出所有問題（例如邊線指向不存在的節點、標籤超出限制），然後寫入 out/index.html 和 out/diagram.svg。開啟 out/index.html 並檢查：
- 步驟 1 中的每個節點都存在，而且沒有你未發現的節點，
- 邊線方向正確且標籤可讀，
- 群組包含正確的節點。
如果佈局雜亂，請嘗試切換 direction，或重新排序 nodes 和 edges：佈局會從它們的順序開始。
4. 匯出 PNG
node <skill>/scripts/export-png.mjs out/index.html
它會將 out/diagram.png 以圖表兩倍的大小寫入；若要使用實際大小，請加上 --scale=1。
5. 交付
提供使用者 out/index.html（動畫版）、out/diagram.svg 和 out/diagram.png，以及 diagram.json，這樣當系統變更時可以更新圖表：編輯 JSON 並再次執行步驟 3 和 4。如果圖表應存放在儲存庫中，docs/architecture/ 資料夾同時存放 JSON 和 SVG 是個好選擇；SVG 可以在 GitHub 和大多數維基中呈現。
故障排除
build: fix diagram.json first：每一行都會指出是哪個節點或邊線以及需要修改的內容。- PNG 步驟顯示找不到 Chrome：請設定
CHROME_PATH，或開啟out/index.html並截圖。 - 文字顯示為不同的等寬字型：頁面無法連線到 Google Fonts。請安裝 JetBrains Mono（免費）以在離線時匹配。
- 邊線大量交叉：切換
direction，將糾結的節點在nodes中移前或移後，或者將系統拆分為兩張圖表。
檔案
scripts/build.mjs：檢查diagram.json，進行佈局並繪製 HTML 和 SVG。無需安裝任何依賴項。scripts/export-png.mjs：使用無頭 Chrome 儲存 PNG。vendor/dagre.esm.js：dagre 圖形佈局函式庫（MIT 授權），已捆綁以便無需安裝；其授權檔案為vendor/LICENSE-dagre.txt。examples/order-service/（藍圖，從左到右）和examples/rag-pipeline/（白圖，從上到下）：完整的diagram.json檔案。Lookbk 上的預覽圖即來自這些範例。NOTICE.md：此技能使用的第三方軟體和字型。