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——先規劃再撰寫
首先決定三件事:
- 訊息。 讀者應在五秒內得出什麼結論?圖表要論證某個觀點——「請求在此處扇出」、「此服務是瓶頸」、「這兩個路徑從未接觸」。如果你無法陳述論點,那你即將繪製的是帶有標籤的方塊集合。
- 類型。 架構/拓撲 → 單純的形狀與容器。隨時間互動 →
sequence_diagram。資料模型 →sql_table。剛性對齊(矩陣、儀表板、圖例密集) → 網格。關於每種結構的指引,請參閱references/diagram-patterns.md。 - 規模。 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 bundled | TALA 不在 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 選擇另一個;請及早測試圖示 |