OpenMontage beautiful-mermaid 技能实战指南：基于 Beautiful Mermaid 将图表渲染为高质量 SVG 与 4K PNG

OpenMontage beautiful-mermaid 技能实战指南：基于 Beautiful Mermaid 将图表渲染为高质量 SVG 与 4K PNG

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

导读

本文聚焦 OpenMontage 仓库中随 AI Agent 技能体系一起分发的beautiful-mermaid 技能（位于 .agents/skills/beautiful-mermaid，并镜像于 .claude/skills/beautiful-mermaid，两份内容一致）。该技能封装了一条「Mermaid 代码 → SVG → HTML 包装 → 浏览器 4K 截图 → PNG」的完整渲染流水线，让 Agent 能在流程图、时序图、状态机、UML 类图与 ER 图等场景下产出可嵌入文档与视频画面的高质量矢量与位图图表。读完本文，你将掌握其完整 CLI 参数、13 种可用主题、五步渲染工作流、底层脚本实现细节与常见故障排查方法。

一、技能定位：给 Agent 补齐「画图」能力

在 OpenMontage 中，图表生成是数据可视化、解说类视频（explainer）与工程文档工作流的重要一环。仓库的 diagram_gen.py 工具声明了provider = "mermaid"，并把agent_skills = ["beautiful-mermaid", "d3-viz"]列入其能力清单——也就是说，beautiful-mermaid 被仓库设计为生成 Mermaid 图表的专属技能，供 Agent 在被要求「把 Mermaid 图渲染出来」时调用。除此之外，diagram-gen-usage.md 与 scene-director.md 也都引用了 mermaid 渲染主题。

本技能的核心能力是调用开源库Beautiful Mermaid渲染 Mermaid 图，并同时产出两种产物：

• SVG：矢量格式，任意缩放不失真，文件体积小，适合嵌入网页与文档；
• PNG：以 4K 视口（3840×2160）截取的高分辨率位图，适合投放视频画面或对格式有硬性要求的场景。

技能的 SKILL.md 声明了一个重要前置依赖：PNG 截取需要agent-browser技能，因此在使用本技能完成 PNG 出图前，必须先加载 agent-browser 相关能力。

二、支持的图类型与可用主题

支持的图类型

可用主题

技能内置13 种主题：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。

主题枚举在 render.ts 中被硬编码为THEMES常量，并且--theme参数在解析阶段就会做合法性校验：传入不在列表中的主题会打印错误与可用主题清单并以退出码 1 终止（见 render.ts）。

主题选择指南（来自 SKILL.md）

在源码层面，每个主题都对应一组精确的bg/fg十六进制色值。渲染脚本内置了一份themeConfigs映射表，例如tokyo-night为bg:#1a1b26 / fg:#a9b1d6，github-dark为bg:#0d1117 / fg:#c9d1d9，nord-light为bg:#eceff4 / fg:#2e3440，实现见 render.ts。若 Beautiful Mermaid 包自身暴露了THEMES，则优先使用包内配置，否则回退到这份内置映射。

三、高频语法模式（避坑要点）

SKILL.md 明确给出了两类高频语法的推荐写法，Agent 生成代码时应优先遵守：

边标签用管道语法

使用|label|管道语法为边附加标签，渲染稳定：

避免使用空格连字符语法（A -- label --> B），它可能造成渲染不完整。同样的警示也完整出现在语法参考文档 references/mermaid-syntax.md 中。

含特殊字符的节点标签加引号

标签中若含有括号、斜杠等特殊字符，必须用双引号包裹：

四、五步渲染工作流

Step 1：生成或校验 Mermaid 代码

若用户只给了文字描述而非代码，Agent 需要先自行生成合法的 Mermaid 语法。完整语法细节参见技能附带的 references/mermaid-syntax.md，其中覆盖 Flowchart、Sequence、State、Class、ER 图及样式语法（详见本文第六节速查）。

Step 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

脚本同时兼容bun / node / deno三种运行时（render.ts）：

bun run scripts/render.ts --code "..." --output diagram npx tsx scripts/render.ts --code "..." --output diagram deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram

执行后会在当前工作目录生成<output>.svg。

从源码看，render.ts暴露了完整的短/长参数对（render.ts）：

另一个值得注意的实现细节是依赖自动安装：脚本在运行时会探测当前运行时（Bun/Deno/node全局对象），然后尝试import('beautiful-mermaid')；若导入失败，会自动调用bun add、deno的npm:导入或npm install安装该包后再次导入（见 render.ts）。因此只要本机有 bun/npm 网络环境，脚本几乎可「开箱即用」。渲染流程通过renderMermaid(mermaidCode, themeConfig)得到 SVG 字符串，再写入${output}.svg（render.ts）。

Step 3：创建 HTML 包装文件

PNG 截图需要先在浏览器中打开，因此要先把 SVG 包装进一个最小 HTML 页面：

bun run scripts/create-html.ts --svg diagram.svg --output diagram.html

该页面会为 SVG 提供合适的内边距与背景，便于后续高质量截图。

create-html.ts同样支持多运行时与多参数（create-html.ts）：

背景色探测逻辑实现得较为完整（create-html.ts）：依次尝试匹配内联样式background(-color)、整幅铺满且带fill的<rect>、以及<svg>标签 style 属性中的背景色；全部失败才用白色兜底。生成的页面中.container以padding提供留白，并约束svg { min-width: 1200px; height: auto; }（create-html.ts），这是保证后续截图宽度的关键。

Step 4：用 agent-browser 截取 4K 高清 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参数给图表留出更多空间。

Step 5：清理中间文件

渲染完成后清理所有中间文件，只保留最终的.svg与.png。需要清理的对象包括：HTML 包装文件、临时保存图表代码的.mmd文件，以及其他渲染过程中产生的文件：

rm diagram.html

若创建过临时.mmd文件，一并删除。

注：仓库是只读的，以上命令均为本地个人工作目录内执行渲染/清理的方式，不涉及修改仓库内容。

五、输出产物规格

每次渲染都会同时产出两类文件：

文件默认保存到当前工作目录，除非用户明确指定其他路径。

六、Mermaid 语法速查（来自技能附带的语法参考）

下面内容整理自技能的 references/mermaid-syntax.md，供 Step 1 生成代码时对照使用。

6.1 流程图（Flowchart）

方向关键字：

• TD/TB：从上到下
• BT：从下到上
• LR：从左到右
• RL：从右到左

节点形状：

边的样式：-->箭头、---实线、-.->虚线箭头、==>粗箭头、-->|text|带标签箭头（推荐）、---|text|带标签实线（推荐）。

重要：边标签务必用管道语法-->|label|；-- label -->空格连字符写法可能造成渲染不完整。

子图（subgraph）：

6.2 时序图（Sequence）

• 箭头：->>实线箭头、-->>虚线箭头、-x/--x带叉、-)/--)空心箭头；
• 激活：箭头后+激活参与者，-取消激活。

备注与分组：

循环与分支：

6.3 状态图（State）

复合状态与备注：

6.4 类图（Class）

关系类型：<|--继承、*--组合、o--聚合、-->关联、--实线链接、..>依赖、..|>实现、..虚线链接。

基数与可见性示例：

可见性前缀：+公有、-私有、#保护、~包内。

6.5 实体关系图（ER）

• 基数标记：||恰好一个、|{一个或多个、o{零或多个、o|零或一个；
• 识别性：--实线为识别性关系，..虚线为非识别性关系；
• 属性可标注主外键：

6.6 样式与通用技巧

CSS 类与内联样式：

实用建议：含特殊字符的标签用引号包裹（如A["Label with (parens)"]）；多行标签用<br/>；注释用%%（不会渲染）；节点 ID 保持简单、把复杂内容放到标签里，例如node1["Complex Label Here"]。

七、故障排查指南

SKILL.md 给出了三类高频问题的诊断路径，结合源码可以更精准地定位：

主题未生效

检查渲染脚本输出中的bg与fg值，或直接查看 SVG 开标签内的--bg/--fgCSS 自定义属性。这两个值由 render.ts 的themeConfigs映射或 Beautiful Mermaid 包自身的THEMES提供；若包内无对应主题而脚本内置映射也缺项，颜色就会回退或丢失。

图被截断或不完整

• 检查边标签语法：用-->|label|管道写法，不要用-- label -->；
• 确认所有节点 ID 唯一；
• 检查节点标签中是否存在未闭合的括号。

渲染出空 SVG 或畸形 SVG

• 渲染前先到 mermaid.live 校验 Mermaid 语法；
• 检查是否需要转义特殊字符（用引号包裹）；
• 确保已指定流程图方向（graph TD、graph LR等）。

八、技能在仓库中的落地位置

该技能随 OpenMontage 的 Agent 技能体系双份分发：

• .agents/skills/beautiful-mermaid/SKILL.md（本技能主文档）
• .agents/skills/beautiful-mermaid/scripts/render.ts（SVG 渲染脚本）
• .agents/skills/beautiful-mermaid/scripts/create-html.ts（HTML 包装脚本）
• .agents/skills/beautiful-mermaid/references/mermaid-syntax.md（Mermaid 语法参考）
• .claude/skills/beautiful-mermaid/SKILL.md（.claude 镜像副本，内容一致）

在仓库更大的工作流里，diagram_gen.py 把beautiful-mermaid列为该图生成工具需要挂载的 Agent 技能之一，说明当你需要把 Mermaid 定义渲染成真正的图文件时，就应切换到此技能执行；skills/creative/diagram-gen-usage.md 与 skills/pipelines/explainer/scene-director.md 也沿用了 mermaid 相关能力。由此可以推断：在 OpenMontage 中，本技能既服务于纯文档配图，也被编排进解说视频场景的画面生产链路。

掌握本技能后，Agent 只要拿到一段描述或代码，就能稳定产出「主题匹配、语法严谨、双格式齐备」的图表文件，并保证成品与文档/视频背景无缝融合。

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage