白板（Whiteboard）
将解释转化为用户可以看到、保存并粘贴到任何地方的图表。你编写图表源码；scripts/render.mjs 脚本使用用户本地安装的CLI进行渲染，并在解析出错时精确告诉你哪里出了问题。
工作流程
-
选择图表类型和语言。 默认使用Mermaid。对于具有嵌套容器的大型架构图使用D2，仅在用户要求或项目已使用PlantUML时才使用它。每种类型的语法请参阅 references/syntax.md。
-
先阅读再绘制。 当图表描述代码时，先阅读代码。绘制实际存在的结构，使用真实名称，而不是一张泛泛的图片。对于整个项目的请求（架构、控制流程、数据模型），请遵循 references/modes.md。
-
编写源码并渲染。 通过标准输入传入源码，并附带一个简短标题（最多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>是该文件所在的文件夹。如需使用其他语言，请添加--language d2或--language plantuml。在Windows系统或当heredoc不便时，请将源码写入一个临时文件，并使用--file <路径>参数代替。 -
失败时修复并重新运行。 退出码1表示渲染器拒绝接受源码；返回信息会指出出错的行。修复该行代码，然后再次运行相同的命令。不要向用户展示未成功渲染的图表。常见修复方法列在 references/syntax.md 的末尾。
-
简要报告结果。 说明图表展示的内容，并给出脚本输出的文件路径（例如
diagrams/checkout-sequence.svg）。如果用户想将图表粘贴到 README、Issues 或 Wiki 中，请将源码放在一个围栏 ```mermaid 代码块中：GitHub、GitLab和Notion都可以渲染它。
脚本参考
| 选项 | 用途 |
|---|---|
--title <文本> | 必需。用于命名文件：diagrams/<slug>.svg 及其旁边的源文件。 |
--language <名称> | mermaid（默认）、d2 或 plantuml。 |
--file <路径> | 从文件而不是标准输入读取源码。 |
--out <目录> | 输出文件夹；默认为当前文件夹下的 diagrams。 |
--png | 同时输出PNG（用于幻灯片、聊天应用、支持显示图像的终端）。 |
--theme <名称> | default、neutral、dark 或 forest。 |
--config <文件> | Mermaid JSON 配置文件，用于设置团队颜色和字体。 |
--check | 仅做验证；不写入任何文件。 |
--open | 在用户的默认查看器中打开SVG。当用户想立即看到图表时使用。 |
--share | 将源码上传到一个秘密的GitHub Gist并打印链接。仅在用户要求分享并同意上传后才运行。 |
--json | 机器可读的输出结果。 |
--doctor | 检查Node.js、每个渲染器以及GitHub CLI，并告知需要安装什么。 |
退出码：0 渲染成功，1 源码被拒绝（修复后重新运行），2 参数错误，3 渲染器未安装。
图表不会将本地文件、环境变量或URL读取到图像中：
- Mermaid 在沙盒化的浏览器页面中渲染，无法从网络或磁盘加载任何内容。所有Mermaid语法都可以使用，但远程或本地的图像以及CSS资源将保持空白；如果图像必须出现，请将其内联为
data:URL。 - PlantUML：拒绝除简单指令（
!define、!if、!procedure、!$var、!theme <名称>、!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源码放在围栏代码块中，这样它仍然可以在GitHub上渲染，并说明它未经渲染器检查。
好的图表
- 每个图表只表达一个想法。将超过大约15个节点或20条消息的内容拆分为概览图加细节图。
- 为每条边标记流动或发生的内容（
HTTP、发布 OrderPlaced、1..*）。 - 使用代码中的名称：类名、模块名、服务名、真实端点、真实表名。
- 选择与问题匹配的图表类型：谁在什么时间调用谁 → 时序图；由哪些部分组成 → 架构/流程图；数据看起来如何 → ER或类图；某事物如何随时间变化 → 状态图。
- 节点内的文字保持简短；将细节放在边标签或注释中。