Pele
使用 Pele 將 Mermaid 原始碼渲染成 SVG。Pele 是一個同步函式庫：無需 Puppeteer、無需 mermaid-cli、無需 MCP 伺服器。此技能的介面為 scripts/render.mjs。
技能根目錄是包含此檔案的目錄。以下所有路徑均相對於該目錄。在將技能安裝到 Claude Code、Hermes 或 OpenCode 後，此規則仍然適用。
使用時機
- 使用者想要一個 Mermaid 圖表作為 SVG、HTML 或圖片檔案。
- 需要渲染並檢查一個
.mmd檔案或```mermaid程式碼區塊。 - 使用者要求繪製 32 種支援類型中的一種圖表，並希望得到一個檔案，而非聊天視窗中的程式碼區塊。這包括較不常見的類型：Wardley 地圖、魚骨圖、文氏圖、泳道圖、雷達圖、樹狀圖、桑基圖、鐵路語法圖、檔案樹圖、Cynefin 圖、事件模型圖。請參閱下方的圖表類型。
請勿在以下情況使用：
- Mermaid 程式碼區塊應保留在 GitHub、Obsidian 或其他檢視器已能渲染的 Markdown 中。
- 請求的成品不是 Mermaid（手繪的 Excalidraw JSON、自訂架構頁面、螢幕截圖註解）。
- 使用者需要像素完全一致的 mermaid.js 輸出。Pele 有自己的佈局。
請勿將其包裝在 MCP 伺服器中。單一腳本呼叫即為完整功能。
先決條件
- Node.js 20 或更新版本，且
npm在PATH環境變數中。 - 依賴項安裝發生在技能根目錄（此檔案旁的
package.json），絕不在使用者的專案中。
如果缺少 node_modules/pele，腳本會在那裡執行 npm install。你也可以自己執行：
npm install --no-fund --no-audit
完成驗證：node scripts/render.mjs --check 退出碼為 0，且 stderr 的 JSON 中 "ok": true，並有 pele 版本號。
圖表類型
在選擇之前，請熟悉完整列表。Pele 渲染 32 種類型，其中三分之一需要一個與使用者通常所說的名稱不同的 -beta 標頭。
node scripts/render.mjs --types
這會以 JSON 格式印出：type、確切的第一行 header、其用途，以及一個可運作的 example 路徑。references/diagram-types.md 包含相同的表格、會失敗的標頭，以及如何選擇類型。
- 選擇能展示讀者所需內容的類型，而非第一個想到的類型。按步驟區分所有者 →
swimlane。單一問題的多個原因 →ishikawa。有截止日期的任務 →gantt。資料夾佈局 →treeView。比例流量 →sankey。 - 如果請求不符合任何類型（自由形式佈局、圖片、未列出的圖表類型），請告知使用者，且不要強行將其放入流程圖中。
- 如果使用者指定了一個列表中沒有的特定圖表類型，請先告知，然後再提供最接近的支援類型。不要默默地近似處理。
流程
- 從
--types選擇類型及其確切標頭。對於任何-beta類型，或任何你對其語法不確定的類型，請先閱讀其example檔案並複製其結構。 - 將 Mermaid 原始碼寫入一個
.mmd檔案。不要將多行圖表作為 shell 引數傳遞。 - 渲染它：
node scripts/render.mjs INPUT.mmd OUTPUT.svg
- 讀取 stderr 上的 JSON 回執。完成條件包括：退出碼為 0，
"ok": true，回執中的type是你選擇的類型，且輸出檔案以<svg開頭。 - 如果
"ok": false：unsupported-diagram：第一行不是已知的標頭。如果suggest[0].header存在則使用它，否則從--types中選擇一個。syntax或semantic：使用snippet修正line/column處的原始碼，與該類型的範例比較，然後重新渲染。- 不要切換到 mermaid-cli、無頭瀏覽器或手寫 SVG。
- 報告絕對輸出路徑。除非使用者要求標記，否則不要將 SVG 貼到聊天中。不要在非零退出碼時聲稱成功。
當使用者需要一個可以在瀏覽器中開啟的檔案時，請使用 --html，或使用以 .html 結尾的輸出路徑。HTML 會內嵌 SVG 並設定 Pele 的 CSS 顏色變數。
node scripts/render.mjs --html INPUT.mmd OUTPUT.html
回執
成功時的 stderr：
{"ok":true,"type":"flowchart","width":180,"height":80,"bytes":1200,"output":"/abs/OUTPUT.svg","html":false,"pele":"1.6.0"}
失敗時的 stderr，退出碼為 1（如果無法安裝 Pele，則退出碼為 2）：
{"ok":false,"code":"syntax","message":"...","type":"flowchart","line":2,"column":5,"snippet":"..."}
code 可以是 syntax、semantic、unsupported-diagram、limit、usage、install-failed 或 render-failed。將 message 顯示為文字。它可能包含圖表原始碼。
一個 unsupported-diagram 回執也包含 hint 和 suggest：
{"ok":false,"code":"unsupported-diagram","hint":"將第一行替換為下方的標頭。許多類型需要 -beta 後綴。","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}
標記
| 標記 | 用途 |
|---|---|
--check | 載入 Pele，印出版本號，不進行渲染 |
--types | 以 JSON 格式在 stdout 上印出支援的類型、標頭和範例路徑 |
--html | 產生獨立 HTML 而非原始 SVG |
--fixed | 固定像素大小。.svg 檔案的預設值 |
--responsive | SVG 可縮小以適應其容器。stdout 和 HTML 的預設值 |
--max-width <px> | 要求 Pele 調整佈局。可將寬的 LR 流程圖在 640px 以下改為垂直方向 |
--font-size <px> | 基本字型大小 |
--font <family> | 標籤字型 |
--id-prefix <str> | 當多個 SVG 共享一個頁面時的獨特前綴 |
Stdout 輸出 SVG（或 HTML）。回執始終是 stderr 上的最後一行 JSON。
外層的 ```mermaid 程式碼區塊會被移除。Mermaid 自己的 frontmatter 則不會。
注意事項
- 檔案 SVG 預設為
responsive: false。僅當 SVG 將被嵌入並應縮小時才傳遞--responsive。 - Node 沒有 Canvas 測量器。標籤寬度可能與瀏覽器渲染結果不同。這是預期的行為。
- 除非使用者要求窄佈局，否則不要傳遞
--max-width。它可能會改變方向。 - 標頭是精確的。
radar、venn、wardley、swimlane、treeView、usecase、cynefin、railroad、agentflow都需要-beta；architecture也需要-beta。沒有fishbone標頭；請使用ishikawa-beta。 - 圖示名稱（
fa:fa-user、除了cloud、database、disk、internet、server之外的架構圖示）會呈現為空白位置而不會報錯。此腳本不提供圖示回呼。請移除圖示或用文字取代。 - 原始碼限制為 50,000 字元。輸出限制為 4,000,000。流程圖邊數限制為 5,000。
- 在使用者的儲存庫中執行
npm install將無法滿足此腳本的需求。套件位於技能根目錄中。 - 如果
node_modules存在但 Pele 載入失敗，請刪除該node_modules並在技能根目錄中執行npm install。 - 已開啟的代理會話將無法看見在會話期間安裝的技能。這是載入器快取問題，並非安裝失敗。
驗證
從技能根目錄：
npm run smoke
完成條件：退出碼為 0，且 stdout 的 JSON 包含 "ok": true、一個 pele 版本號、"types": 32、一個包含所有目錄類型的 rendered 列表，以及一個 code: "syntax" 和一個非零 line 的 syntaxError。如果 scripts/catalog.mjs 與 Pele 自身的類型列表不一致，或者某個標頭未能被識別為其類型，冒煙測試也會失敗。examples/broken.mmd 必須持續失敗。冒煙測試通過並不代表新的圖表是正確的；每個新圖表仍需要自己的回執。