OpenMontage beautiful-mermaid 技能实战指南基于 Beautiful Mermaid 将图表渲染为高质量 SVG 与 4K PNG【免费下载链接】OpenMontageWorlds 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 相关能力。二、支持的图类型与可用主题支持的图类型类型典型用途Flowchart流程图业务流程、决策树、CI/CD 流水线Sequence时序图API 调用、OAuth 流程、数据库事务State状态图状态机、连接生命周期Class类图UML 类图、设计模式表达Entity-Relationship实体关系图数据库 Schema、数据模型可用主题技能内置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主题背景适合场景default浅灰通用场景dracula深紫偏好深色模式tokyo-night深蓝现代深色审美tokyo-night-storm更深蓝更高对比度nord深北极色柔和、平静的视觉nord-light浅北极色柔和浅色模式github-darkGitHub 深色匹配 GitHub 界面github-lightGitHub 浅色匹配 GitHub 界面catppuccin-latte暖浅色柔和粉彩审美solarized棕褐色/奶油色Solarized 配色体系one-darkAtom 深色Atom 编辑器风格zinc-dark中性深色极简、无色彩倾向在源码层面每个主题都对应一组精确的bg/fg十六进制色值。渲染脚本内置了一份themeConfigs映射表例如tokyo-night为bg:#1a1b26 / fg:#a9b1d6github-dark为bg:#0d1117 / fg:#c9d1d9nord-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.tsbun 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短参数长参数说明备注-i--input输入.mmd文件路径与--code至少必填其一文件不存在会报错退出-c--code直接传入 Mermaid 代码字符串与--input至少必填其一-o--output输出文件名不含扩展名必填缺省会打印帮助并退出-t--theme主题名默认default非法值列出全部主题并退出退出码 1-h--help打印帮助—另一个值得注意的实现细节是依赖自动安装脚本在运行时会探测当前运行时Bun/Deno/node全局对象然后尝试import(beautiful-mermaid)若导入失败会自动调用bun add、deno的npm:导入或npm install安装该包后再次导入见 render.ts。因此只要本机有 bun/npm 网络环境脚本几乎可「开箱即用」。渲染流程通过renderMermaid(mermaidCode, themeConfig)得到 SVG 字符串再写入${output}.svgrender.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短参数长参数说明默认值-s--svg输入 SVG 文件必填-o--output输出 HTML 文件必填-p--paddingSVG 四周留白像素40-b--background背景色未指定时自动从 SVG 探测自动探测失败回退#ffffff-h--help打印帮助—背景色探测逻辑实现得较为完整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文件一并删除。注仓库是只读的以上命令均为本地个人工作目录内执行渲染/清理的方式不涉及修改仓库内容。五、输出产物规格每次渲染都会同时产出两类文件产物特征SVG矢量格式无限缩放文件体积小PNG高分辨率位图在 4K3840×2160视口下截取图表最小宽度 1200px文件默认保存到当前工作目录除非用户明确指定其他路径。六、Mermaid 语法速查来自技能附带的语法参考下面内容整理自技能的 references/mermaid-syntax.md供 Step 1 生成代码时对照使用。6.1 流程图Flowchart方向关键字TD/TB从上到下BT从下到上LR从左到右RL从右到左节点形状语法形状A[Text]矩形A(Text)圆角矩形A([Text])椭圆/胶囊形A[[Text]]子程序A[(Text)]圆柱形数据库A((Text))圆形AText]非对称形A{Text}菱形决策A{{Text}}六边形A[/Text/]、A[\Text\]平行四边形A[/Text\]、A[\Text/]梯形边的样式--箭头、---实线、-.-虚线箭头、粗箭头、--|text|带标签箭头推荐、---|text|带标签实线推荐。重要边标签务必用管道语法--|label|-- label --空格连字符写法可能造成渲染不完整。子图subgraph6.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.tsSVG 渲染脚本.agents/skills/beautiful-mermaid/scripts/create-html.tsHTML 包装脚本.agents/skills/beautiful-mermaid/references/mermaid-syntax.mdMermaid 语法参考.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 只要拿到一段描述或代码就能稳定产出「主题匹配、语法严谨、双格式齐备」的图表文件并保证成品与文档/视频背景无缝融合。【免费下载链接】OpenMontageWorlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考