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 代码块应保留在 Markdown 中，由 GitHub、Obsidian 或其他查看器自行渲染。
- 请求的制品不是 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 | 在 stdout 上以 JSON 格式打印支持的图表类型、头部和示例路径 |
--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 自身的前置元数据不会被剥离。
陷阱
- 文件 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 必须保持失败。烟雾测试通过并不代表新图表是正确的；每个新图表仍需要其自身的收据。