Communitygithub.com

khollingworth/d2-diagram-skill

Claude Code 外掛,可繪製專業的 D2 架構圖(TALA/ELK),並具備自我檢查的渲染循環。

d2-diagram-skill 是什麼?

這個 Claude Code 技能讓 AI 助理能夠撰寫 D2 原始碼、將其渲染為 SVG,然後重複檢視與修正,直到產出值得交付的圖表。它不僅是一個繪圖工具,更強調透過「看見圖表」來迭代優化,避免產生未經檢視的內容。技能會自動檢查並安裝 d2 工具鏈,支援 TALA、ELK 與 dagre 等佈局引擎,並內建防浮水印機制。它會引導使用者依序規劃圖表訊息、選擇圖表類型(如架構圖、序列圖、C4 模型)與規模,再參考語言參考文件撰寫正確的 D2 語法,最後透過渲染腳本輸出 SVG 與 PNG。整個流程包含強制性的兩階段視覺檢查(論點有效性與佈局缺陷),並提供多種修正手段(變更方向、容器分組、調整 seed 等)。支援深色模式、GitHub 嵌入,以及透過 `--watch` 即時預覽。此技能適用於所有需要產出高品質技術圖表的開發場景,特別是當圖表需要與程式碼庫中的實際名稱保持一致時。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

在你喜歡的 AI 中提問

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

說明文件

D2 圖表

撰寫 D2 原始碼,將其渲染為 SVG,然後檢視渲染結果並修正你所看到的——形成一個循環,直到圖表值得交付。你沒看過的圖表,就是還沒完成的圖表。

參考檔案——按需載入

檔案何時閱讀
references/d2-language.md撰寫任何非單純的 D2 時——語法、形狀、容器、類別、變數,以及那些編譯成功但渲染錯誤的隱藏陷阱
references/layout-engines.md選擇或除錯佈局:TALA vs ELK vs dagre、授權、隨機種子、不同引擎的行為差異
references/diagram-patterns.md挑選圖表類型與結構——架構圖、序列圖、ERD、網格、C4;主題、圖示、深色模式、GitHub 嵌入

步驟 0——工具鏈檢查

在第一次渲染前,每個工作階段執行一次(此處的 scripts/ 指的是此技能自己的目錄——在 Claude Code 中 ${CLAUDE_SKILL_DIR} 會解析為該目錄):

bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
  • d2: ok → 繼續進行。
  • d2: MISSING → 告知使用者,然後執行 scripts/setup.sh(不帶旗標)以透過 Homebrew 安裝(若可用),或顯示列印的安裝指令。不要盲目渲染——沒有 d2,這個技能的任何功能都無法運作。
  • tala: not installed 或 unlicensed → 沒問題。ELK 是自動備用方案,且能產生良好的佈局。僅在圖表是軟體架構圖(TALA 在這種情況下明顯更好),且使用者似乎重視輸出品質時,才提及 TALA 一次;切勿嘮叨。

步驟 1——先規劃再撰寫

首先決定三件事:

  1. 訊息。 讀者應在五秒內得出什麼結論?圖表要論證某個觀點——「請求在此處扇出」、「此服務是瓶頸」、「這兩個路徑從未接觸」。如果你無法陳述論點,那你即將繪製的是帶有標籤的方塊集合。
  2. 類型。 架構/拓撲 → 單純的形狀與容器。隨時間互動 → sequence_diagram。資料模型 → sql_table。剛性對齊(矩陣、儀表板、圖例密集) → 網格。關於每種結構的指引,請參閱 references/diagram-patterns.md。
  3. 規模。 5–15 個節點閱讀效果佳;15–25 個需要容器來分組;超過 ~25 個,則分割成多個圖表或使用 layers。與其畫一幅壁畫,不如畫第二張圖表。

對於真實系統的技術圖表,請使用真實名稱——來自使用者的程式碼庫或描述的實際服務名稱、實際資料表名稱、實際事件名稱。如果可以,搜尋程式碼。Service A -> Service B 會浪費讀者的信任。

步驟 2——撰寫 D2

在撰寫任何超出單純圖表之外的內容之前,請先閱讀 references/d2-language.md。這些規則可預防 90% 的錯誤輸出:

  • 連接鍵 (keys),而非標籤 (labels)。 在 api: API Gateway 之後,撰寫 api -> db,絕不要撰寫 API Gateway -> db——後者會默默地建立重複的形狀。
  • 引用包含 # 或 ; 的標籤——未引用的 # 會在標籤中間開始註解,而未引用的 ; 會將一行分割成兩個形狀,兩者都會在編譯時不報錯。引用任何帶有標點符號的標籤是安全的習慣。
  • 透過 classes: 設定樣式,而非每個節點各自的樣式——一次定義,然後用 class: 套用。避免對個別節點使用 style.fill;硬編碼的填色會與主題衝突,並破壞深色模式的渲染。
  • 對大多數架構流程設定 direction: right(從左到右閱讀很自然)。所有引擎都遵循根層級的 direction;TALA 額外支援每個容器的 direction。
  • 將原始碼儲存為 {name}.d2,放在輸出所需的檔案旁邊(預設為專案中的 ./diagrams/)。

步驟 3——渲染

一律透過配套腳本進行渲染——它會選擇佈局引擎、防止帶浮水印的輸出,並先進行驗證:

bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
  • --png 也會寫入 output.png——你需要在步驟 4 中使用它(Read 工具檢視點陣圖影像,而非 SVG)。
  • 腳本會印出 engine:(實際渲染的引擎)和 fallback:(原因,如果未使用 TALA)。僅在使用者詢問引擎或明確表示想要 TALA 時,才向使用者轉達一行摘要。
  • 有用的旗標:--theme N、--dark-theme 200(SVG 會回應讀者的色彩配置)、--sketch、--pad N、--seed N(TALA 重新隨機化)、--engine tala|elk|dagre(強制指定)、--allow-watermark(TALA 評估版)。
  • 失敗時,腳本會印出 d2 的編譯錯誤,附帶 file:line:col——在該位置修正原始碼並重新執行。如果錯誤不明確,請查看 references/d2-language.md 的陷阱章節。

除非使用者明確接受,否則切勿渲染帶有浮水印的 TALA 輸出;腳本會透過自動回退到 ELK 來強制執行此規則。

步驟 4——檢視它,然後修正它(非選擇性)

.d2 原始碼完全無法反映渲染的實際結果——佈局是引擎的決定,不是你的。使用 Read 工具開啟 PNG,並分兩階段稽核:

階段 1——它是否傳達了論點?

  • 視線是否從故事開始的地方進入,並在結束的地方離開?
  • 流程方向是否一致(沒有非預期的折返或自下而上閱讀)?
  • 容器分組是否符合你規劃的邏輯分組?
  • 最重要的元素是否在視覺上突出,還是被埋沒了?

階段 2——佈局缺陷(自動佈局引擎會產生所有這些問題):

  • 邊緣標籤遠離其邊緣,或對其描述的邊緣產生歧義
  • 邊緣在平行路徑中重疊,穿過節點或容器,或繞了荒謬的遠路
  • 文字被截斷或與形狀/圖示碰撞
  • 一個區域擁擠不堪,而另一個區域卻空空如也;容器遠大於其內容
  • 節點太小,導致標籤佔主導地位,或節點大小極不一致
  • 任何你如果展示給使用者看,就必須道歉解釋的事物

使用 D2 的槓桿來修正,而非手動調整像素(自動佈局意味著你改變輸入,而非座標):變更 direction;使用容器分組或重新分組;縮短邊緣標籤(長標籤在 ELK 上最容易偏移);將平行邊緣合併為一個帶標籤的邊緣;使用 near 將圖例/標題移出流程;將過載的圖表分割成 layers;調整 --pad;在 TALA 上,使用 --seed N 重新隨機化(嘗試 2–3 個種子——佈局會有顯著變化);作為最後手段,為此圖表的形狀切換引擎(請參閱 references/layout-engines.md)。

重新渲染、重新檢視、重複。預留二到四個渲染循環——第一次渲染就能通過這兩個階段的案例很少見。完成意味著:兩個階段都乾淨,且圖片中沒有任何需要道歉或解釋的內容。

步驟 5——交付

  • 確認最終的 .svg(和 .d2 原始碼)路徑——務必給使用者兩者;.d2 才是可編輯的成品。
  • 如果圖表將放在 GitHub README 或文件站點中,請提供深色模式適用的變體:使用 --dark-theme 200 重新渲染(單一 SVG 會跟隨讀者的色彩配置)。PNG/<picture> 嵌入的模式在 references/diagram-patterns.md 中。
  • 如果使用者將自行迭代圖表,請提及 d2 --watch input.d2 以在瀏覽器中即時預覽。

疑難排解

症狀原因 / 修正方式
d2: command not found執行 scripts/setup.sh(引導式安裝)
D2_LAYOUT "tala" is not bundledTALA 不在 PATH 中——腳本自動回退到 ELK;僅在使用者需要時才安裝 TALA
輸出中出現 UNLICENSED 文字TALA 沒有授權——渲染腳本會自動使用 ELK 重新渲染;授權金鑰需放在 TSTRUCT_TOKEN 或 ~/.config/tstruct/auth.json
PNG 匯出失敗,SVG 正常首次 PNG 渲染會下載無頭瀏覽器;重試一次。如果被封鎖(離線/CI),請交付 SVG,並使用任何可用的 SVG 點陣化工具將其轉換以進行檢查
在 --layout tala 下編譯錯誤,但 ELK 可正常渲染d2/TALA 版本不一致——腳本會自動回退;建議更新兩者
圖示從輸出中遺失圖示 URL 回傳 403/404——移除該圖示或從 icons.terrastruct.com 選擇另一個;請及早測試圖示

相關技能