Beautiful Mermaid 是一个将 Mermaid 图表渲染为 SVG 和 PNG 图像的工具，基于 Beautiful Mermaid 库实现。当用户要求渲染 Mermaid 图表时使用。
【依赖】 渲染 PNG 需要 agent-browser 技能，在进行 PNG 捕获前需先加载该技能。
【支持的图表类型】
- Flowchart：流程图、决策树、CI/CD 流水线
- Sequence：API 调用、OAuth 流程、数据库事务
- State：状态机、连接生命周期
- Class：UML 类图、设计模式
- Entity-Relationship：数据库模式、数据模型
【可用主题】 Default、Dracula、Solarized、Zinc Dark、Tokyo Night、Tokyo Night Storm、Tokyo Night Light、Catppuccin Latte、Nord、Nord Light、GitHub Dark、GitHub Light、One Dark。若未指定主题，则使用 default。
【常用语法模式】 流程图边标签使用管道语法： A -->|label| B A ---|label| B 避免使用空格-短横线语法，可能导致渲染不完整： A -- label --> B # 可能引发问题
含特殊字符的节点标签需加引号： A["Label with (parens)"] B["Label with / slash"]
【工作流程】 第 1 步：生成或校验 Mermaid 代码。若用户提供的是描述而非代码，则生成有效的 Mermaid 语法。完整语法细节可参考 references/mermaid-syntax.md。
第 2 步：渲染 SVG。运行渲染脚本生成 SVG 文件： bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default 或从文件读取： bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night 其他运行时： npx tsx scripts/render.ts --code "..." --output diagram deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram 这会在当前工作目录生成 <output>.svg。
第 3 步：创建 HTML 包装文件。运行 HTML 包装脚本以准备截图： bun run scripts/create-html.ts --svg diagram.svg --output diagram.html 这会创建一个最小 HTML 文件，以适当的留白和背景显示 SVG。
第 4 步：使用 agent-browser 捕获高分辨率 PNG。使用 agent-browser CLI 捕获高质量截图，完整 CLI 文档参见 agent-browser 技能。
设置 4K 视口以进行高分辨率捕获
agent-browser set viewport 3840 2160
打开 HTML 包装文件
agent-browser open "file://$(pwd)/diagram.html"
等待渲染完成
agent-browser wait 1000
捕获整页截图
agent-browser screenshot --full diagram.png
关闭浏览器
agent-browser close 对于复杂图表需要更高分辨率时，可进一步增大视口，或在创建 HTML 包装文件时使用 --padding 选项为图表提供更多空间。
第 5 步：清理中间文件。渲染完成后移除所有中间文件，仅保留最终的 .svg 和 .png。需清理的文件包括：HTML 包装文件（如 diagram.html）、用于存放图表代码的临时 .mmd 文件、渲染过程中创建的其他文件。 rm diagram.html 若创建了临时 .mmd 文件，也一并移除。
【输出】 始终同时生成两种输出：
- SVG：矢量格式，可无限缩放，文件体积小
- PNG：高分辨率栅格图，以 4K（3840×2160）视口捕获，图表宽度最小 1200px 除非用户明确指定其他路径，文件保存到当前工作目录。
【主题选择指南】 default：浅灰背景，通用场景 dracula：深紫背景，偏好深色模式 tokyo-night：深蓝背景，现代深色美学 tokyo-night-storm：更深的蓝色，更高对比度 nord：深色北极风，柔和沉稳的视觉效果 nord-light：浅色北极风，柔和色调的浅色模式 github-dark：GitHub 深色，匹配 GitHub 界面 github-light：GitHub 浅色，匹配 GitHub 界面 catppuccin-latte：暖色浅色，柔和粉彩美学 solarized：棕褐/奶油色，Solarized 配色方案 one-dark：Atom 深色，Atom 编辑器美学 zinc-dark：中性深色，极简、无色彩偏向
【故障排查】 主题未应用：检查渲染脚本输出中的 bg 和 fg 值，或查看 SVG 开头标签中的 --bg 和 --fg CSS 自定义属性。 图表被截断或不完整：检查边标签语法，使用 -->|label| 管道记法而非 -- label -->；确认所有节点 ID 唯一；检查节点标签中是否有未闭合的括号。 渲染产生空或格式错误的 SVG：在 https://mermaid.live 校验 Mermaid 语法；检查需要转义的特殊字符（用引号包裹）；确保指定了流程图方向（graph TD、graph LR 等）。