Beautiful Mermaid 是一个将 Mermaid 图表渲染为 SVG 和 PNG 图像的工具，基于 Beautiful Mermaid 库实现。当用户要求渲染 Mermaid 图表时可以使用它。
用途
该技能用于把 Mermaid 图表代码或描述转换为可用的图像文件，输出 SVG 矢量图和 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。
主题选择参考：default 为浅灰背景，适合通用场景；dracula 为深紫背景，适合偏好深色模式；tokyo-night 为深蓝背景，适合现代深色审美；tokyo-night-storm 为更深蓝背景，对比度更高；nord 为深色北极风，适合柔和冷静的视觉；nord-light 为浅色北极风，适合柔和色调的浅色模式；github-dark 与 github-light 匹配 GitHub 界面；catppuccin-latte 为暖色浅色，适合柔和粉彩审美；solarized 为棕褐/奶油色，采用 Solarized 配色；one-dark 为 Atom 深色，适合 Atom 编辑器审美；zinc-dark 为中性深色，极简且无色彩偏向。
使用方式
依赖：PNG 渲染需要 agent-browser 技能，进行 PNG 截取前需先加载它。
工作流程：
第 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
除非用户明确指定其他路径，文件保存到当前工作目录。
常见语法模式
流程图边标签：使用管道语法为边添加标签：
A -->|label| B A ---|label| B
避免使用空格-短横线语法，它可能导致渲染不完整：
A -- label --> B # 可能引发问题
含特殊字符的节点标签：将含特殊字符的标签用引号包裹：
A["Label with (parens)"] B["Label with / slash"]
故障排查
主题未应用：检查渲染脚本输出中的 bg 和 fg 值，或查看 SVG 开头标签中的 --bg 和 --fg CSS 自定义属性。
图表被截断或不完整：检查边标签语法，使用 -->|label| 管道写法而非 -- label -->；确认所有节点 ID 唯一；检查节点标签中是否有未闭合的括号。
渲染产生空或格式错误的 SVG：在 https://mermaid.live 校验 Mermaid 语法；检查需要转义的特殊字符（用引号包裹）；确保指定了流程图方向（graph TD、graph LR 等）。
更新检查
在会话中首次使用时，静默检查是否有新版本：获取 https://raw.githubusercontent.com/abpai/skills/main/versions.json，将 beautiful-mermaid 的版本与此文件元数据中的 metadata.version 比较。如果远程版本更新，则在主任务前暂停并询问：beautiful-mermaid 有可用更新（本地 {X.Y} → 远程 {A.B}）。是否希望我先为你更新？我可以为你运行 npx skills update beautiful-mermaid。如果用户同意，则在继续前运行更新；如果用户拒绝，则继续使用当前本地版本。如果获取失败或无法访问网络，则静默跳过。
适用场景
适用于需要将 Mermaid 图表渲染为图像文件的场景，例如生成流程图、时序图、状态图、类图或实体关系图，并希望获得 SVG 矢量图或高分辨率 PNG 位图。
限制
PNG 渲染依赖 agent-browser 技能。渲染完成后需清理中间文件，仅保留最终 .svg 和 .png。主题未指定时使用 default。若获取更新信息失败或无法访问网络，则静默跳过更新检查。