Community影像github.com

Excalidraw 架構圖(EIP 表示法)

當被要求使用 Excalidraw 繪製、草擬或視覺化軟體架構、訊息流、事件驅動或微服務系統時使用。從簡短的 JSON 規格檔產生 .excalidraw 檔案(採用企業整合模式表示法:通道、路由器、轉換器、端點、DLQ、Saga),並附上預覽 SVG 與渲染檢查。不適用於 UI 模型、簡報或自由白板。

Excalidraw 架構圖(EIP 表示法) 是什麼?

這項技能專為需要在 Excalidraw 中繪製軟體架構圖的開發者與 AI 代理所設計,特別適用於訊息傳遞、事件驅動及微服務系統。其核心是使用一個簡潔的 JSON 規格檔(spec)作為單一事實來源,並透過 `scripts/eip_excalidraw.mjs` 腳本將其轉換為遵循 Gregor Hohpe 與 Bobby Woolf 所著《企業整合模式》表示法的 `.excalidraw` 與 `.svg` 檔案。此技能支援 Claude Code、Codex、Cursor 等多種開發代理平台。工作流程包含以下步驟:盤點參與者與通道、選擇圖表層級(脈絡、流程或端點)、撰寫規格檔、執行建置(亦可輸出 PNG 格式),以及根據檢查清單進行視覺審查與修正。它強制實施建模規則,例如每條通道都必須顯示其類型標籤與持久性設定,且至少傳送一次的通道消費者必須標示為「等冪」。此技能不適用於 UI 模型、序列圖或自由形式的白板繪圖,應明確避免這些用途。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jamescarr/diagram-skill/tree/HEAD/skills/excalidraw-architecture

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Excalidraw 架構圖(EIP 表示法) 是做什麼的?

圖即是一個小型的 JSON 規格 — 節點、邊、群組 — 加上一個產生器,它會將這些內容以 Hohpe & Woolf 表示法進行佈局。規格是事實的唯一來源;.excalidraw 檔案與預覽用的 .svg 是建置產物。

<skill-dir> 是此技能安裝所在目錄 — 例如 ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture 或 .agents/skills/excalidraw-architecture — 以及 https://github.com/jamescarr/diagram-skill 倉庫中的 skills/excalidraw-architecture 目錄。

使用時機

  • 被要求繪製、草擬或視覺化一個服務、事件或訊息架構。
  • 解釋訊息如何傳遞:哪條通道、哪個端點、失敗時發生什麼事。
  • 在脈絡、流程或端點層級記錄限界上下文的整合表面。
  • 審查訊息導向的設計,圖中必須揭露遺失的 DLQ、關聯 ID 或等冪性。

不使用時機

  • UI 模型、線框圖、簡報、自由形式白板。
  • 顯示單一程序內部呼叫的序列圖。
  • 任何交付成果不是 .excalidraw 檔案的項目。

工作流程

  1. 盤點 — 在繪製前列出:

    • 參與者:服務、外部系統、角色、儲存庫;
    • 通道:名稱、點對點 vs 發布-訂閱、金鑰/分區/排序、持久性、DLQ;
    • 訊息:名稱(命令 = 祈使句,事件 = 過去式,文件 = 名詞)和類型;
    • 每個服務的端點:閘道、寄件匣/交易、消費者樣式、競爭數量、等冪性、持久性、選擇性;
    • 路由和轉換步驟;
    • 請求-回覆配對:回覆通道、關聯、TTL;
    • 管理:探針、存放區、控制匯流排。 如果已安裝 enterprise-integration-patterns 技能,在模式選擇不明確時應閱讀該技能。
  2. 挑選層級 — context(脈絡):角色、服務、外部系統、代理器視為 message-bus、rpc/data 邊。flow(流程,預設):以端到端的方式呈現一個業務流程,包含通道與 EIP 元件。endpoint(端點):在單一服務內部 — 閘道 → 寄件匣 → 通道,或消費者 → 等冪接收器 → 啟動器。每個圖一個流程,最多 20 個節點;否則按流程拆分。

  3. 撰寫規格 — 在圖表將存放的資料夾(預設為 docs/architecture/)旁建立 <name>.spec.json,使用下方的速查表。執行 node <skill-dir>/scripts/eip_excalidraw.mjs kinds 以取得完整的分類目錄。

  4. 建置 — node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json 會寫出 <name>.excalidraw 和 <name>.svg。修正所有 error:(退出碼 2);將 warning: 視為佈局缺陷(--strict 會使警告導致退出碼 1)。--check 會驗證與佈局但不寫入檔案。 加上 --png [OUT.png] 可額外匯出由 Excalidraw 本身渲染的 PNG(手繪風格、Excalifont 字型、場景嵌入檔案中,因此可重新拖放到 excalidraw.com)— 適合嵌入 README、文件或部落格文章。它需要 Chrome 或 Chromium(CHROME 環境變數可覆蓋查找路徑)以及對 esm.sh 的網路存取;它透過 scripts/export_png.mjs 驅動瀏覽器。匯出失敗時退出碼為 3,但仍會寫入場景。

  5. 檢視 — 若有建置 PNG 則 read <name>.png,否則 read <name>.svg:img;然後進行審查清單檢查。

  6. 修正 — 每次規格變更後重新建置:

    症狀規格變更
    箭頭穿過節點route: "ortho" 或 "below",或固定 row
    標籤與節點重疊縮短 message/label,或將節點的 row 固定到遠離箭頭的位置
    箭頭縮小該欄間距中箭頭過多:將一個路線設為 below/above,或固定 row 以減少共用該垂直線的箭頭數量
    反向箭頭雜亂route: "above"
    回覆箭頭在整個圖下方迴圈route: "ortho",或將回覆通道放在請求通道旁邊
    欄位擁擠添加 lanes,或拆分圖表
    節點標籤過長將細節移至 sub
    群組成員分散固定 col/row 使成員相鄰
    框架包含非成員固定 col/row 或使用 lanes 使群組成員形成連續區塊
  7. 交付 — 交付 .spec.json、.excalidraw 和 .svg(若曾建置 PNG 則包含 .png)。說明規格是事實來源:編輯後應重新產生。之後在 Excalidraw 中手動編輯是可以的,但重建會覆寫這些編輯。

建模規則

每條規則都是一個圖表必須可見的主張;當無法成立時,應明確繪製例外狀況。

  • 每個通道都要顯示其類型標籤以及金鑰/分區/排序標籤(tags)。
  • 每個至少傳送一次通道的消費者都必須帶有 idempotent — 或者圖表必須說明原因。徽章僅存在於應用程式家族節點上,因此 saga、路由器或聚合器必須在 sub 中說明其去重規則(dedupe by orderId)。
  • 每個消費者可能失敗的通道都有一個 dead-letter-channel shadow;驗證失敗則獲得一個 invalid-message-channel。對於未繪製或故意省略的 DLQ,必須在通道的 sub 或 note 中說明。
  • 請求-回覆 = 一個帶有 reply_to 和 correlation 的命令邊,加上一條虛線的回覆邊回來。
  • 聚合器、分散-收集和 saga 節點必須在 sub 中帶有完成規則(計數/逾時)。
  • 交易內的發布 = 一個 outbox 徽章或 outbox 節點,絕不能是提交後的裸發布。
  • 轉換器位於限界上下文邊界(框架)上。
  • 競爭消費者顯示 competing:N;持久訂閱帶有 durable。
  • 探針是以 tap 邊連接到 message-store。
  • 智慧端點,愚蠢管道:路由邏輯存在於路由器節點中,絕不能暗示在通道內部。
  • 同步呼叫是 rpc 邊,並且是例外情況,而非預設方式。
  • 跨越邊界的內部記錄需要一個 content-filter 或 claim-check 參考。

規格速查表

按 EIP 章節分類的節點 — 完整的分類對照表在 references/spec.md 中:

章節種類使用時機
通道channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus訊息在參與者之間移動;選定 p2p 或 pub-sub,然後設定失敗通道。
訊息message command-message document-message event-message訊息本身是主題,而非端點。
路由content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga一個訊息有多個可能的目的地,或需要重新組合各部分。
轉換message-translator envelope-wrapper content-enricher content-filter claim-check normalizer有效負載或其封裝在跳躍之間發生變化。
端點message-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapter服務如何連接到通道並消費它。
系統管理wire-tap detour message-history smart-proxy test-message channel-purger可觀測性、探測與操作。
基礎設施message-broker messaging-bridge outbox inbox代理器本身、代理器間連結、交易性發布/消費。
參與者與儲存庫service external-system actor datastore message-store schema-registry note誰擁有通道端點;狀態、結構描述與註解存放何處。

徽章(僅適用於應用程式家族節點;藥丸形狀呈現簡短文字):

群組徽章
端點gateway(訊息閘道)、mapper(訊息映射器)、activator(服務啟動器)、adapter(通道配接器)
消費polling(輪詢消費者)、event-driven(事件驅動消費者)、competing / competing:N(競爭消費者,在最多三個方塊的堆疊上呈現 competing ×N)、dispatcher(訊息分派器)、selective(選擇性消費者)、durable(持久訂閱者)
交易tx(交易用戶端)、outbox(交易性寄件匣)、inbox(交易性收件匣)、idempotent(等冪接收器)
韌性bulkhead、retry、circuit-breaker — 韌性模式,非 EIP

邊:

邊種類筆畫寬度箭頭標記
message(無類型)實線 #1e1e1e2→ arrow無
message type: command實線2→ triangle«C»
message type: event實線2→ arrow«E»
message type: document實線2→ arrow«D»
message type: reply虛線2→ arrow«R»
rpc實線1→ arrow無
data點線1→ arrow無
tap點線1circle → arrow無
dlq虛線 #c92a2a1→ arrow無
control虛線 #868e961┤ bar無

邊的欄位:from、to、kind、type、message、label、seq、route、correlation、reply_to、ttl、sequence、style、color。節點欄位:id、kind、label、sub、badges、tags、group、lane、col、row、shadow、attach、link。

審查檢查清單

  • 存在標題;它命名的是流程,而非整個系統。
  • 每條箭頭都標有訊息或呼叫。
  • 每條通道都帶有它的種類標籤和金鑰/分區標籤。
  • 每條通道的 DLQ 決策都可見。
  • 當出現超過 6 種種類時,必須有圖例。
  • 建置後沒有留下 warning:。
  • 群組框架僅包含它們的成員。
  • 最多 20 個節點。

技術堆疊映射

技術堆疊繪製方式
Kafka 主題pubsub-channel;消費者群組 → competing:N;持久訂閱 → durable
RabbitMQ 佇列p2p-channel;交換器 → message-broker 或 content-based-router;DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
EventBridge 規則content-based-router
Step Functionsprocess-manager 或 saga
Lambda 消費者帶有 event-driven 的 service
資料庫datastore;稽核/重播副本 → message-store
合作夥伴 APIexternal-system,虛線

手動編輯

references/excalidraw-format.md 列出了在進行手動編輯後,能保持 Excalidraw 的綁定、文字和框架有效的 JSON 不變項。

相關技能