whiteboard 是做什麼的？
將說明轉換為使用者可以查看、保存且隨處貼上的圖表。您撰寫圖表原始碼；scripts/render.mjs 會使用使用者本地安裝的 CLI 進行渲染，並在解析失敗時準確告訴您哪裡出錯。
工作流程
-
選擇圖表類型和語言。 預設使用 Mermaid。大型架構圖（含巢狀容器）使用 D2，僅在使用者要求或專案已使用 PlantUML 時才使用它。每種類型的語法請參閱 references/syntax.md。
-
繪製前先閱讀。 當圖表描述程式碼時，請先閱讀程式碼。繪製實際存在的內容，使用真實名稱，而非泛型圖片。針對整個專案的請求（架構、控制流程、資料模型），請遵循 references/modes.md。
-
撰寫原始碼並渲染。 透過標準輸入（stdin）傳遞原始碼，並附上簡短標題（最多 80 個字元）。標題會用來命名檔案，因此重新繪製相同圖表時請重複使用相同的標題：
node <skill-dir>/scripts/render.mjs --title "結帳循序圖" <<'EOF' sequenceDiagram Browser->>API: POST /checkout API->>Payments: charge(card) Payments-->>API: ok API-->>Browser: 201 Created EOF<skill-dir>是本檔案所在的資料夾。若使用 D2 或 PlantUML，請加上--language d2或--language plantuml。在 Windows 系統或 heredoc 不方便使用時，請將原始碼寫入暫存檔案，並改用--file <path>參數。 -
失敗時修正並重新執行。 退出碼 1 表示渲染器拒絕了原始碼；錯誤訊息會指出錯誤的行號。修正該行後再次執行相同指令。請勿將未渲染成功的圖表交給使用者。常見修正方法列於 references/syntax.md 結尾。
-
簡短回報。 說明圖表顯示的內容，並提供腳本輸出的檔案路徑（例如
diagrams/checkout-sequence.svg）。如果使用者想將圖表貼到 README、Issue 或 Wiki，請在 fenced ```mermaid 區塊中提供原始碼：GitHub、GitLab 與 Notion 皆可渲染此格式。
腳本參考
| 選項 | 用途 |
|---|---|
--title <text> | 必要。命名檔案：diagrams/<slug>.svg 及其旁的原始碼檔案。 |
--language <name> | mermaid（預設）、d2 或 plantuml。 |
--file <path> | 從檔案讀取原始碼，而非從標準輸入。 |
--out <dir> | 輸出資料夾；預設為目前資料夾中的 diagrams。 |
--png | 同時輸出 PNG 格式（適用於簡報、聊天應用程式、可顯示圖片的終端機）。 |
--theme <name> | default、neutral、dark 或 forest。 |
--config <file> | Mermaid 的 JSON 設定檔，用於團隊配色與字型。 |
--check | 僅驗證；不寫入任何檔案。 |
--open | 在使用者預設的檢視器中開啟 SVG。當使用者想立刻看到圖表時使用。 |
--share | 將原始碼上傳至秘密的 GitHub Gist，並列印連結。僅在使用者要求分享且同意上傳後執行。 |
--json | 輸出機器可讀的結果。 |
--doctor | 檢查 Node、各渲染器及 GitHub CLI，並告知需要安裝的項目。 |
退出碼：0 渲染成功，1 原始碼被拒絕（修正後重新執行），2 參數錯誤，3 渲染器未安裝。
圖表絕不會讀取本機檔案、環境變數或 URL 到圖片中：
- Mermaid 在沙盒化的瀏覽器頁面中渲染，該頁面無法從網路或磁碟載入任何內容。任何 Mermaid 語法皆可使用，但遠端或本機圖片及 CSS 資源會保持空白；若需顯示圖片，請將其內嵌為
data:URL。 - PlantUML：除了簡單的指令（
!define、!if、!procedure、!$var、!theme <name>、!include <stdlib>…）之外，%getenv與類似的內建函式，以及<img:…>皆被拒絕。請改為內嵌內容。 - D2：拒絕
@匯入。包含圖示、區塊字串、HTML 或 URL 的圖表僅會渲染為 SVG，且其中的連結會保持為可點擊的連結。
僅在使用者明確要求包含外部檔案或圖片時，才能使用 WHITEBOARD_ALLOW_INCLUDES=1 重新執行。
使用相同標題重新繪製時，較早的檔案會保留在 diagrams/.versions/<slug>/<n>/ 中，因此在圖表上疊代絕不會遺失先前的版本。
當渲染器遺失時
退出碼 3 會列印安裝指令。請告知使用者需要執行的指令，除非使用者要求，否則請勿自行安裝全域套件：
- Mermaid：
npm i -g @mermaid-js/mermaid-cli - D2：
brew install d2，或參閱 https://d2lang.com/tour/install - PlantUML：
brew install plantuml或apt install plantuml（需安裝 Java）
如果渲染器已安裝但找不到（常見於未包含登入 shell 之 PATH 的桌面應用程式），請將 WHITEBOARD_MMDC、WHITEBOARD_D2 或 WHITEBOARD_PLANTUML 設定為其完整路徑。Mermaid 渲染使用 mermaid-cli 附帶的瀏覽器與 Mermaid 套件；若腳本找到 mmdc 但找不到其套件，請將 WHITEBOARD_MERMAID_CLI_DIR 設定為 @mermaid-js/mermaid-cli 資料夾。當完全無法安裝任何工具時，請將 Mermaid 原始碼放在 fenced 區塊中，使其仍可在 GitHub 上渲染，並說明其未經渲染器檢查。
好的圖表
- 一個圖表只表達一個想法。將超過約 15 個節點或 20 則訊息的內容拆分為概覽圖加上細節圖。
- 為每一條連線標示流動或發生的內容（
HTTP、發佈 OrderPlaced、1..*）。 - 使用程式碼中的名稱：類別、模組與服務的名稱、實際端點、實際資料表。
- 選擇與問題相符的類型：誰在何時呼叫誰 → 循序圖；組成部分是什麼 → 架構圖/流程圖；資料長什麼樣 → ER 圖或類別圖；事物隨時間如何變化 → 狀態圖。
- 節點內文字保持簡短；細節放在連線標籤或註解中。