菜单
将 Mermaid 图表渲染为美观的 SVG、PNG 或 ASCII 艺术字。支持流程图、序列图、状态图、类图、ER图、XY图表（含柱状图、折线图、组合图等）等6种核心图表类型，提供17个内置主题（15个上游+2个本地扩展）和自定义主题能力，支持CSS级样式定制和交互式预览。适用于在终端、聊天界面或网页中可视化数据流、系统架构、状态机等。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/chouraycn/beautiful-mermaid --skill beautiful-mermaid命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | beautiful-mermaid |
| version | 1.1.5 |
| icon | beautiful-mermaid.png |
| description | 将 Mermaid 图表渲染为美观的 SVG、PNG 或 ASCII 艺术字。支持流程图、序列图、状态图、类图、ER图、XY图表（含柱状图、折线图、组合图等）等6种核心图表类型，提供17个内置主题（15个上游+2个本地扩展）和自定义主题能力，支持CSS级样式定制和交互式预览。适用于在终端、聊天界面或网页中可视化数据流、系统架构、状态机等。 |
| description_zh | 将 Mermaid 图表渲染为美观的 SVG、PNG 或 ASCII 艺术字 |
| description_en | Render Mermaid diagrams as beautiful SVG, PNG or ASCII art |
| homepage | https://github.com/chouraycn/beautiful-mermaid |
| author | chouray (https://github.com/chouraycn) |
| keywords | ["mermaid","diagram","flowchart","sequence-diagram","svg","ascii"] |
| triggers | ["mermaid图表","渲染mermaid","流程图","序列图","状态图","类图","ER图","ASCII图表","SVG图表","PNG图表","导出mermaid","样式定制","自定义样式","xychart","柱状图","折线图","数据图表","架构图","系统架构图","时序图","关系图","生成图表","图形化","可视化","画图","绘图","绘制图表","产品流程图","业务流程图","客户流程","试妆流程","购买流程","[Truncated]"] |
目录名要求：skill 目录名必须为 beautiful-mermaid，不是 beautiful-mermaid-main 或其他名称。
如果目录名不对，手动重命名：
mv ~/.workbuddy/skills/beautiful-mermaid-main ~/.workbuddy/skills/beautiful-mermaid
# 或项目级
mv 项目目录/.workbuddy/skills/beautiful-mermaid-main 项目目录/.workbuddy/skills/beautiful-mermaid
Beautiful Mermaid 是一个高性能的 Mermaid 图表渲染库，专为 AI 时代设计。它将 Mermaid 语法转换为美观的 SVG 图形、PNG 位图或 ASCII 艺术字，支持同步渲染、全主题定制、CSS级样式定制，零 DOM 依赖。
| 说明 | 地址 |
|---|---|
| 本 Skill | https://github.com/chouraycn/beautiful-mermaid |
| 上游项目 | https://github.com/lukilabs/beautiful-mermaid |
graph TD、graph LR、graph BT、graph RL 等方向xychart-beta 语法）以下图表类型暂不支持，渲染会报错 Invalid mermaid header：
| 图表类型 | 语法示例 | 状态 |
|---|---|---|
| Mindmap（思维导图） | mindmap root((中心)) A B C | 上游 Issue #59 跟踪 |
| Pie Chart（饼图） | pie title "标题" "A": 10 "B": 20 | 上游 Issue #59 跟踪 |
| Gantt（甘特图） | gantt title 项目计划 ... | 上游 Issue #59 跟踪 |
| Git Graph | gitGraph ... | 上游 Issue #59 跟踪 |
| User Journey | journey ... |
| 上游 Issue #59 跟踪 |
| C4 Context | C4Context ... | 计划外 |
上游进度：lukilabs/beautiful-mermaid Issue #59 正在开发 Mermaid v11 新图表支持。预计未来版本会添加。
临时替代方案：如果需要这些图表类型，可以：
orange-dark（暖色暗色）、orange-light（暖色亮色）—— 独立维护，上游更新时不丢失bg、fg、line、accent、muted、surface、border 全部字段fromShikiTheme() 直接使用 VS Code 编辑器主题.mmd 文件架构说明：主题采用「上游 + 本地」分层设计。上游主题同步自 lukilabs/beautiful-mermaid 库；本地主题（orange 系）在
styles.js中独立定义，通过{ ...UPSTREAM_THEMES, ...LOCAL_THEMES }合并，确保上游更新时本地扩展不会丢失。
完整主题列表和推荐搭配请参考下方 API 参考 部分的 主题对照表。
语义角色颜色由系统根据主题背景亮度（感知亮度 < 128 判定为暗色主题）自动选择：
| 角色 | 亮色主题（fill / stroke / text） | 暗色主题（fill / stroke / text） |
|---|---|---|
critical | #FFF7ED / #F97316 / #9A3412 | #431407 / #F97316 / #FDBA74 |
success | #F0FDF4 / #22C55E / #166534 | #052e16 / #22C55E / #86EFAC |
danger | #FEF2F2 / #EF4444 / #991B1B | #450a0a / #EF4444 / #FCA5A5 |
info | #EFF6FF / #3B82F6 / #1D4ED8 | #172554 / #3B82F6 / #93C5FD |
muted | #F4F4F5 / #A1A1AA / #52525B | #27272A / #71717A / #A1A1AA |
本节包含 AI 助手使用此 skill 时必须遵守的工作规则。
检查是否有上次渲染记录：
.workbuddy/last-render.json 文件弹窗询问用户：
您有以下选择：
1. 继续完善 - 继承上次的主题和预设，继续优化
2. 全新开始 - 创建全新的图表（上次的主题/预设会丢失）
请选择：___
Step 1 — 打开预览工具（第一优先级）
首先通过 execute_command 工具执行 find 命令找到 skill 实际安装目录（目录名取决于 zip 文件名，不一定是 beautiful-mermaid）：
// 使用 execute_command 执行 find 命令查找
// 返回结果示例：/Users/chouray/.workbuddy/skills/beautiful-mermaid/SKILL.md
// 取其父目录即为 SKILL_DIR
得到 SKILL_DIR 后，立即执行：
// 优先从 last-render.json 读取上次的主题/预设，传递到 URL 参数
// 这样 preview.html 会自动继承上次的样式（用户无需重新选择）
const lastRender = readRenderState(); // 读取 .workbuddy/last-render.json
const themeParam = lastRender ? `?theme=${lastRender.theme}&preset=${lastRender.preset}` : '';
preview_url("file://" + SKILL_DIR + "/assets/preview.html" + themeParam)
beautiful-mermaid 作为目录名Step 2 — 记录用户选择（关键：主题必须保留到最终输出）
tokyo-night）和预设（如 glass）Step 3 — 生成 .mmd 文件
Step 4 — 执行渲染，传递 Step 2 记录的主题
--theme 和 --preset 参数node scripts/render.jsnode scripts/rich-html.js# SVG / PNG / ASCII
node scripts/render.js <file.mmd> -t <主题> -p <预设> -o output.svg
# HTML（必须用 rich-html.js，不可用 render.js -f html 替代）
node scripts/rich-html.js "<标题>" --diagrams <file.mmd> --theme <主题> --preset <预设> --output result.html
preview_url 打开生成的 HTML 结果（file:// + 绝对路径）当 AI 无法明确判断用户意图时（即用户既没有明确说"继续"，也没有明确说"新任务"，但 AI 感觉可能涉及之前的内容时），必须主动弹出确认对话框，不得自行猜测继续。
触发条件：
确认方式：
ask_followup_question 工具提供选项：
【强制规则】AI 在打开 preview.html 后的行为：
问题描述：使用 subgraph 子图分区语法时，某些主题（特别是 zinc-light 的 outline 预设）与 subgraph 配合时，Mermaid 布局引擎在计算子图边界时容易出错，导致节点重叠或连线错乱。
解决方案：
zinc-light + outline 预设处理复杂子图AA、BB、CC、A1、B2 等简单字母组合start_node、process_step、decision_point、end_result 等描述性名称| 图表复杂度 | 推荐主题 | 推荐预设 | 说明 |
|---|---|---|---|
| 简单流程图（无 subgraph） | 任意主题 | 任意预设 | 所有主题和预设都兼容 |
| 中等复杂度（1-2层 subgraph） | 除 zinc-light 外 | 除 outline 外 | zinc-light + outline 可能布局异常 |
| 复杂架构图（多层嵌套 subgraph） | tokyo-night、github-dark、nord | glass、default | 布局引擎最稳定 |
| XY图表 | 所有主题 | 所有预设 | 完全兼容 |
当用户请求以下图表类型时，必须明确告知用户暂不支持，并提供替代方案：
| 图表类型 | 替代方案 |
|---|---|
| Mindmap（思维导图） | 使用流程图 graph TD 替代，或使用 mermaid.live 导出后用本 skill 转换样式 |
| Pie Chart（饼图） | 使用 XY 柱状图替代 |
| Gantt（甘特图） | 使用流程图 + 状态图组合 |
| Git Graph | 使用 mermaid.live |
| User Journey | 使用流程图 |
当用户明确说以下话术时，执行继续任务流程：
Step 1 — 读取现有文件 + 上次渲染状态
.workbuddy/last-render.json 获取上次渲染时使用的主题和预设Step 2 — 理解修改需求
Step 3 — 修改 .mmd 文件
Step 4 — 重新渲染
必须完整执行以下5个步骤：
Step 1 — 打开预览或读取上次状态
Step 2 — 记录用户选择
Step 3 — 生成/修改 .mmd 文件
Step 4 — 必须执行渲染命令
Step 5 — 必须预览结果
preview_url 工具被调用任何涉及渲染 Mermaid 图表的请求，无论用户是否已指定主题/预设，都必须先调用 preview_url 打开预览工具。
打开方式（唯一合法方式）：
preview_urlfile:// + skill目录 + assets/preview.html唯一例外：用户明确说"直接渲染，不用预览"或"跳过预览"时，才可跳过 preview 步骤。
# @roles 注释声明节点角色，告别写死 HEX 颜色，主题切换时颜色自动跟随npm install beautiful-mermaid
# 或
bun add beautiful-mermaid
提供可视化的样式定制界面，AI 必须用 preview_url 工具直接以文件路径打开（在 IDE 内置浏览器中显示，无需服务器）：
// 第1步：用 execute_command 执行 find 命令查找 beautiful-mermaid 的 SKILL.md
// find ~/.workbuddy/skills -name "SKILL.md" -exec grep -l "name: beautiful-mermaid" {} \;
// 结果示例：/Users/chouray/.workbuddy/skills/beautiful-mermaid/SKILL.md
// 取其父目录作为 SKILL_DIR
// 第2步：读取 .workbuddy/last-render.json（如果有）
// 第3步：用实际路径打开（传递 theme/preset 参数以便继承上次样式）
const lastRender = loadRenderState(); // 读取 .workbuddy/last-render.json
const themeParam = lastRender ? `?theme=${lastRender.theme}&preset=${lastRender.preset}` : '';
preview_url("file://" + SKILL_DIR + "/assets/preview.html" + themeParam)
⚠️ 重要：skill 安装目录名 = zip 文件名（不含 .zip），不一定是
beautiful-mermaid。若用户将 zip 改名，安装目录也会变。每次使用前必须用execute_command的 find 命令动态检测实际目录名，不得硬编码。
❌ 禁止使用 open/start 命令或启动任何 HTTP 服务器。
预览工具功能：
当用户需要将多张 Mermaid 图表整合为一个专业的展示页面时，使用 scripts/rich-html.js。
生成的 HTML 包含：
# 方式一：直接调用脚本
node scripts/rich-html.js "标题" \
--diagrams file1.mmd file2.mmd file3.mmd \
--theme tokyo-night --preset glass \
--subtitle "副标题" \
--output result.html
# 方式二：通过 npm script（等效）
npm run rich-html -- "标题" \
--diagrams file1.mmd file2.mmd file3.mmd \
--theme tokyo-night --preset glass \
--subtitle "副标题" \
--output result.html
node scripts/rich-html.js "示例集" \
--batch assets/examples \
--theme dracula --preset gradient \
--output examples-report.html
# npm 方式
npm run rich-html -- "示例集" --batch assets/examples --theme dracula --preset gradient --output examples-report.html
在 .mmd 文件中通过注释声明元数据，显示在信息卡片中：
# @title 用户下单完整流程
# @desc 从进入活动页到订单完成的端到端链路，含限流、库存扣减、异步建单
# @icon 🛒
# @type Flowchart
# @meta 关键节点:8 个|覆盖阶段:全链路|主题:Tokyo Night|限流策略:Redis Lua
graph TD
A[用户进入秒杀页] --> B{限流检查}
...
元数据字段说明：
@title：Tab 名称和卡片标题@desc：卡片描述（小字，显示在标题下方）@icon：图标 emoji（默认根据图表类型自动推断）@type：图表类型说明（自动推断，可手动覆盖）@meta：信息卡片内容，格式 标签:值|标签:值（最多 4 组）@roles：语义角色声明（见下方说明）用 # @roles 注释声明哪些节点属于哪种语义角色。渲染时自动根据主题亮暗选择对应颜色套装，无需写死 HEX 颜色。
用法格式：
# @roles 角色名:节点ID,节点ID 角色名:节点ID ...
可用角色（5 个）：
| 角色 | 含义 | 亮色主题 | 暗色主题 |
|---|---|---|---|
critical | 关键节点 / 触发入口 | 橙底 #FFF7ED，橙边 #F97316 | 深橙底 #431407，橙边 #F97316 |
success | 成功 / 完成 / 正向结果 | 绿底 #F0FDF4，绿边 #22C55E | 深绿底 #052e16，绿边 #22C55E |
danger | 失败 / 降级 / 风险 | 红底 #FEF2F2，红边 #EF4444 | 深红底 #450a0a，红边 #EF4444 |
info | 重要处理 / 关键步骤 | 蓝底 #EFF6FF，蓝边 #3B82F6 | 深蓝底 #172554，蓝边 #3B82F6 |
muted | 次要 / 跳过 / 禁用 | 灰底 #F4F4F5，灰边 #A1A1AA | 深灰底 #27272A，灰边 #71717A |
完整示例：
# @title 秒杀预加载流程
# @roles critical:A info:E,F success:K,G danger:H muted:Z
flowchart TD
A[距离开始 < 5分钟] --> B{用户在线?}
B -->|是| E[资源分类预加载]
B -->|否| Z[等待用户上线]
E --> F[CDN 预热]
F --> G[标记准备就绪]
G --> K[进入等待期]
F --> H{预热失败?}
H -->|是| Z
H -->|否| K
渲染后：
图例：当 .mmd 中有 @roles 声明时，Rich HTML 卡片底部会自动出现「节点角色」图例条，列出所有角色及对应节点 ID。
生成的 HTML 完整继承渲染时指定的主题颜色：
bgsurfaceborderfgmutedaccentbg 略深/浅，自动计算AI 工作规则：生成 rich-html 后，必须用
preview_url工具打开生成的 HTML 文件，让用户直观查看效果。
import { renderMermaidSVG, THEMES } from 'beautiful-mermaid';
// 使用内置主题
const svg = renderMermaidSVG(`graph TD
A[开始] --> B{判断}
B -->|是| C[执行操作]
B -->|否| D[结束]`, THEMES['tokyo-night']);
// 使用自定义主题
const customSvg = renderMermaidSVG(diagramCode, {
bg: '#1a1b26',
fg: '#a9b1d6',
accent: '#7aa2f7',
transparent: true,
});
// 使用 CSS 变量（支持实时主题切换）
const cssVarSvg = renderMermaidSVG(diagramCode, {
bg: 'var(--background)',
fg: 'var(--foreground)',
transparent: true,
});
// 异步渲染（适用于 async 上下文）
const asyncSvg = await renderMermaidSVGAsync(diagramCode, THEMES['dracula']);
import { renderMermaidASCII } from 'beautiful-mermaid';
// Unicode 模式（默认）
const unicode = renderMermaidASCII(`graph LR
A --> B --> C`);
// 纯 ASCII 模式
const ascii = renderMermaidASCII(`graph LR
A --> B --> C`, { useAscii: true });
// 带颜色输出
const colored = renderMermaidASCII(`graph LR
A --> B --> C`, { colorMode: 'truecolor' });
// 输出示例：
// ┌───┐ ┌───┐ ┌───┐
// │ │ │ │ │ │
// │ A │────►│ B │────►│ C │
// │ │ │ │ │ │
// └───┘ └───┘ └───┘
import { renderMermaidSVG } from 'beautiful-mermaid';
function MermaidDiagram({ code }: { code: string }) {
const { svg, error } = React.useMemo(() => {
try {
return {
svg: renderMermaidSVG(code, {
bg: 'var(--background)',
fg: 'var(--foreground)',
transparent: true,
}),
error: null,
};
} catch (err) {
return { svg: null, error: err as Error };
}
}, [code]);
if (error) return <pre>{error.message}</pre>;
return <div dangerouslySetInnerHTML={{ __html: svg }} />;
}
import { renderMermaidSVG } from 'beautiful-mermaid';
// 柱状图
const bar = renderMermaidSVG(`xychart-beta
title "Monthly Revenue"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Revenue ($K)" 0 --> 500
bar [180, 250, 310, 280, 350, 420]`, THEMES['tokyo-night']);
// 折线图
const line = renderMermaidSVG(`xychart-beta
title "User Growth"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
line [1200, 1800, 2500, 3100, 3800, 4500]`, THEMES['github-dark']);
// 组合图（柱状 + 折线）
const combo = renderMermaidSVG(`xychart-beta
title "Sales with Trend"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
bar [300, 380, 280, 450, 350, 520]
line [300, 330, 320, 353, 352, 395]`, THEMES['dracula']);
// 交互式 XY 图表（鼠标悬停显示 tooltip）
const interactive = renderMermaidSVG(chartCode, {
bg: '#1a1b26',
fg: '#a9b1d6',
accent: '#7aa2f7',
interactive: true,
});
import { getSingletonHighlighter } from 'shiki';
import { renderMermaidSVG, fromShikiTheme } from 'beautiful-mermaid';
// 使用任意 VS Code 主题
const highlighter = await getSingletonHighlighter({
themes: ['vitesse-dark', 'rose-pine', 'material-theme-darker']
});
const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'));
const svg = renderMermaidSVG(code, colors);
# 渲染文件为 SVG
node scripts/render.js diagram.mmd -o output.svg
# 使用指定主题
node scripts/render.js diagram.mmd -t dracula -o output.svg
# 渲染为 PNG (高清位图)
node scripts/render.js diagram.mmd -f png -o output.png
# PNG 自定义尺寸 (宽度)
node scripts/render.js diagram.mmd -f png -w 2400 -o output.png
# PNG 高清缩放 (2x)
node scripts/render.js diagram.mmd -f png -s 2 -o output.png
# PNG 高 DPI (印刷质量)
node scripts/render.js diagram.mmd -f png --dpi 300 -o output.png
# 渲染为 ASCII (终端)
node scripts/render.js diagram.mmd -f ascii
# 渲染为内嵌 SVG 的 HTML 页面
node scripts/render.js diagram.mmd -f html -t tokyo-night -p glass -o output.html
# XY 图表启用交互式 tooltip
node scripts/render.js chart.mmd --interactive -o chart.svg
# 直接传入代码 (注意：Mermaid 代码中换行用 \n)
node scripts/render.js -c "graph TD\nA --> B" -o output.svg
| 参数 | 说明 |
|---|---|
--format, -f | 输出格式: svg (默认) | ascii | png | html |
--theme, -t | 主题名称: tokyo-night, dracula, nord 等 17 个，或自定义 JSON |
--output, -o | 输出文件路径（批量模式为输出目录） |
--code, -c | 直接传入 Mermaid 代码 |
--bg | 背景色 (如: #f7f7fa) |
--fg | 前景色/文字颜色 (如: #27272a) |
--line | 连线颜色 (如: #6b7280) |
--preset, -p | 样式预设: default | modern | gradient | outline | glass（可与 --theme 联用） |
--width, -w | PNG 输出宽度 (默认: 1200px) |
--scale, -s | PNG 缩放比例 (默认: 1, 范围: 0.5-4) |
--dpi | PNG 输出 DPI (默认: 144, 范围: 72-600) |
--interactive | 启用交互式 tooltip (仅 XY 图表) |
--color-mode | ASCII 颜色模式: none | auto | ansi16 | ansi256 | truecolor | html |
--batch | 批量模式: 渲染指定目录下所有 .mmd 文件 |
--list-themes | 列出所有可用主题及其推荐预设搭配 |
--help, -h | 显示帮助信息 |
PNG 格式适用于文档嵌入、PPT 演示等场景：
-s 参数)--dpi 参数，72=屏幕，300=印刷)# 屏幕显示 (默认 144 DPI)
node scripts/render.js diagram.mmd -f png -o screen.png
# 印刷质量 (300 DPI)
node scripts/render.js diagram.mmd -f png --dpi 300 -o print.png
# 2K 高清 (2400px)
node scripts/render.js diagram.mmd -f png -w 2400 -o hd.png
# 4K 超清 (4800px)
node scripts/render.js diagram.mmd -f png -s 4 -o 4k.png
# 图标尺寸 (600px)
node scripts/render.js diagram.mmd -f png -w 600 -o icon.png
通过 --preset 参数使用与 preview.html 一致的样式预设。推荐与 --theme 联用：
# ✅ 推荐：主题 + 预设自由组合
node scripts/render.js diagram.mmd -t tokyo-night -p glass -o output.svg
node scripts/render.js diagram.mmd -t dracula -p gradient -o output.svg
node scripts/render.js diagram.mmd -t catppuccin-mocha -p glass -f png -o output.png
# 也支持自定义颜色 + 预设
node scripts/render.js diagram.mmd --bg '#f7f7fa' --fg '#27272a' --line '#6b7280' -p modern -o output.svg
node scripts/render.js diagram.mmd --bg '#f7f7fa' --fg '#27272a' --line '#6b7280' -p gradient -o output.svg
node scripts/render.js diagram.mmd --bg '#f7f7fa' --fg '#27272a' --line '#6b7280' -p outline -o output.svg
node scripts/render.js diagram.mmd --bg '#f7f7fa' --fg '#27272a' --line '#6b7280' -p glass -f png -o output.png
可用预设对比：
| 预设 | 圆角 | 边框 | 阴影 | 场景 |
|---|---|---|---|---|
| default | 8px | 2px | 中等 | 通用场景 |
| modern | 16px | 1px | 柔和 | 现代产品 UI |
| gradient | 12px | 0px | 彩色 | 视觉展示 |
| outline | 4px | 2px | 无 | 技术文档 |
| glass | 12px | 1px | 高模糊 | 深色叠加 |
使用 --batch 参数可以一次渲染目录下所有 .mmd 文件：
# 批量渲染为 SVG（输出到源目录）
node scripts/render.js --batch ./diagrams -t dracula
# 批量渲染为 PNG，输出到指定目录
node scripts/render.js --batch ./diagrams -f png -t tokyo-night -o ./output
# 批量渲染为 ASCII
node scripts/render.js --batch ./examples -f ascii --color-mode ansi256
批量模式会遍历指定目录下的所有 .mmd 文件，自动按文件名生成对应的 .svg/.png/.txt 输出文件。
通过 --color-mode 参数控制 ASCII 渲染的着色方式：
# 无颜色（纯 ASCII）
node scripts/render.js diagram.mmd -f ascii --color-mode none
# 256 色模式（兼容更多终端）
node scripts/render.js diagram.mmd -f ascii --color-mode ansi256
# HTML 模式（可在网页中展示）
node scripts/render.js diagram.mmd -f ascii --color-mode html
--theme 与 --preset 联用（推荐）--preset 现在可以与 --theme 联用，不再互斥：
# ✅ 推荐：--theme + --preset 自由组合
node scripts/render.js diagram.mmd -t dracula -p gradient -o out.svg
node scripts/render.js diagram.mmd -t tokyo-night -p glass -o out.svg
node scripts/render.js diagram.mmd -t github-light -p modern -o out.svg
# ✅ 仍然支持：--preset 配合 --bg/--fg
node scripts/render.js diagram.mmd --bg '#f7f7fa' --fg '#27272a' -p modern -o out.svg
# ✅ 自动推荐预设：只指定 --theme，自动使用该主题的推荐预设
node scripts/render.js diagram.mmd -t dracula -o out.svg
# 输出: ✓ SVG 已保存: out.svg + preset:gradient (dracula 推荐 gradient)
# 列出所有主题及其推荐预设
node scripts/render.js --list-themes
# 输出示例:
# ● 暗色主题 (Dark):
# tokyo-night → 推荐预设: glass
# dracula → 推荐预设: gradient
# ...
# ● 亮色主题 (Light):
# github-light → 推荐预设: default
# ...
--bg + --fg → 自定义基础配色（line/accent/muted 自动推导）--theme 名称 → 从内置 17 主题取完整 7 字段配色--theme JSON → 直接使用 JSON 对象（缺省字段自动补全）--preset → 应用形状预设（与任何颜色来源都可以搭配）--preset 时，自动使用主题推荐的预设样式预设通过 CSS 变量覆盖 实现：
var(--_node-fill)、var(--_line)<svg> 标签后注入 <style> 标签!important 覆盖 CSS 变量和元素属性/* 注入的 CSS 结构 */
svg {
--_text: #27272a !important;
--_line: #6b7280 !important;
--_node-fill: #f7f7fa !important;
}
rect { rx: 16px !important; } /* 圆角 */
path { stroke-width: 1.5px !important; } /* 线宽 */
const monoTheme = {
bg: '#0f0f0f', // 背景色
fg: '#e0e0e0', // 前景色
};
const richTheme = {
bg: '#0f0f0f', // 背景色
fg: '#e0e0e0', // 前景色
accent: '#ff6b6b', // 箭头/高亮色
muted: '#666666', // 次要文字/标签
surface: '#1a1a1a', // 节点填充色
border: '#333333', // 边框色
};
⚠️ 强制规则：Step 1 不可跳过。即使用户已指定主题和预设，AI 也必须先打开 Playground 让用户在 preview.html 中确认效果，再执行 Step 2 渲染。唯一例外：用户明确说"跳过预览"。
Step 1 — 在 Playground 中确认风格（强制）
AI 先通过 search_file 工具找到实际安装目录，再用 preview_url 工具打开（传递 last-render.json 中的 theme/preset 以便继承）：
const lastRender = loadRenderState();
const themeParam = lastRender ? `?theme=${lastRender.theme}&preset=${lastRender.preset}` : '';
preview_url("file://" + SKILL_DIR + "/assets/preview.html" + themeParam)
用户在页面中选择主题和预设后，底部会实时显示 CLI 命令栏：
node scripts/render.js input.mmd -t dracula -p gradient -o output-dracula-gradient.svg
Step 2 — 将选定风格传递给生成
Playground 提供三种传递方式：
| 按钮 | 内容 | 用途 |
|---|---|---|
| CLI 命令栏（点击） | node scripts/render.js ... -t <theme> -p <preset> | 直接在终端粘贴执行 |
| Copy Config | JSON（含 theme、preset、颜色对象、CLI命令） | AI / 脚本读取，参数化批量生成 |
| Copy Code | renderMermaidSVG(code, THEMES['...']) | 嵌入 JS/TS 代码 |
Step 3 — 统一管理生成的文件
mermaid-{theme}-{preset}.svg，方便按风格整理Step 4（可选）— 多图表丰富展示 HTML
当用户有多张 Mermaid 图表需要整合展示时（如系统设计文档、架构评审、技术报告），使用 scripts/rich-html.js，生成带标签页导航和信息卡片的专业展示页面：
# 使用 Step 1 中用户确认的主题和预设
node scripts/rich-html.js "报告标题" \
--diagrams file1.mmd file2.mmd file3.mmd \
--theme <用户确认的主题> --preset <用户确认的预设> \
--subtitle "副标题" \
--output result.html
生成后必须用 preview_url 打开结果 HTML，让用户预览效果。
工作流关键点：rich-html.js 不需要单独指定颜色，只需传入 Step 1 中用户已在 preview.html 中确认的
--theme和--preset，所有颜色自动继承。
当用户要求将多张图表整合为报告/文档/展示页面时，必须使用
scripts/rich-html.js，不要手动拼接 HTML。
# 方式一：直接调用脚本
node scripts/rich-html.js "<标题>" \
--diagrams <file1.mmd> [file2.mmd ...] \
--theme <主题> --preset <预设> \
--subtitle "<副标题>" \
--output <输出路径.html>
# 方式二：npm script（等效，-- 之后的参数透传）
npm run rich-html -- "<标题>" \
--diagrams <file1.mmd> [file2.mmd ...] \
--theme <主题> --preset <预设> \
--output <输出路径.html>
rich-html.js 自动从 --theme 和 --preset 继承所有颜色，AI 无需手动指定任何颜色值：
| 页面元素 | 来源 |
|---|---|
| 页面背景 | 主题 bg |
| 卡片/导航背景 | 主题 surface |
| 边框线 | 主题 border |
| 正文文字 | 主题 fg |
| 次要文字/标签 | 主题 muted |
| 强调色（Badge/激活Tab/数值） | 主题 accent |
| SVG 图表背景 | bg 自动加深/变浅 |
为了让信息卡片显示有意义的内容，在图表文件中添加注释元数据：
# @title 用户下单完整流程
# @desc 从进入活动页到订单完成的端到端链路
# @icon 🛒
# @meta 关键节点:8 个|覆盖阶段:全链路|主题:Tokyo Night|限流:Redis Lua
graph TD
...
生成 HTML 后，必须调用 preview_url 工具打开文件，让用户直接在 IDE 内预览：
preview_url("file:///绝对路径/result.html")
⛔ 本节是 rich-html.js 内部实现参考文档，AI 工作流中禁止使用。 AI 必须调用
scripts/rich-html.js生成 HTML，不得绕过脚本手动拼接 HTML。 详见上方「多图表丰富展示 HTML 规范」章节（从第 911 行开始）。
当用户要求将 Mermaid 图表输出为独立 HTML 文件时，AI 必须严格按照本节模板生成，否则会出现样式串扰、SVG 裁剪、线条无颜色等问题。
① 每个 SVG 必须有唯一 id
用 injectStylesToSVG(svg, theme, preset, 'diagram-flow') 第 4 个参数传入不同 id。
内联多个 SVG 时，每张图用不同 id（如 diagram-flow、diagram-seq、diagram-3）。
② 内部 <style> 选择器必须用 id 作用域化
generateCSSStyles 会自动完成（传入 svgId 参数后），输出：
#diagram-flow { --_line: #A1A1AA; } /* ✅ 有 id 作用域，不会污染其他 SVG */
#diagram-flow text { ... }
#diagram-flow path { ... }
而非裸选择器：
svg { --_line: #A1A1AA; } /* ❌ 内联进 HTML 后会影响所有 SVG */
text { ... }
path { ... }
③ 外层 CSS 必须同时设 max-width: 100% + height: auto
max-width: 100% 单独不够。当容器宽度窄于 SVG 的硬编码宽度时，SVG 宽度被压缩，
但若不设 height: auto，高度不跟随缩放，图表下半部分被截断。
/* ✅ 正确：两个属性必须同时设置 */
.diagram-wrap svg {
display: block;
max-width: 100%;
height: auto; /* CRITICAL: 缺少这行会导致窄屏下图表被垂直截断 */
width: auto;
}
SVG 内部元素使用 stroke="var(--_line)"，该变量通过 CSS 从 --line 映射而来。
injectStylesToSVG 会自动在 <svg style="..."> 属性中内联所有 --_xxx 精确颜色值，
确保在 Figma、Inkscape、系统预览等独立软件中打开时线条也有正确颜色。
核心修复：
<!-- 修复后的 SVG 开标签（--_line 等变量直接内联在 style 属性中） -->
<svg id="diagram-flow"
style="background:#FFF;--_line:#A1A1AA;--_arrow:#A1A1AA;--_text:#27272A;..."
width="229" height="606" viewBox="0 0 229 606">
overflow: hidden — 这会截断超出容器的 SVG 内容height: 400px）再嵌入 SVG — SVG 会被截断#id 作用域化后还是会互相影响max-width:100% 和 height:auto — 只写前者会在窄屏裁剪import { renderMermaidSVG } from 'beautiful-mermaid';
import { injectStylesToSVG, resolveTheme } from './scripts/styles.js';
const theme = resolveTheme('zinc-light');
// 多张图时：每张图传入不同的 svgId（第 4 个参数）
const flowSVG = injectStylesToSVG(renderMermaidSVG(flowCode, theme), theme, 'default', 'diagram-flow');
const seqSVG = injectStylesToSVG(renderMermaidSVG(seqCode, theme), theme, 'default', 'diagram-seq');
<style>
/* ✅ 正确：max-width + height:auto 同时设置 */
.diagram-wrap svg {
display: block;
max-width: 100%;
height: auto; /* CRITICAL：防止窄屏垂直裁剪 */
width: auto;
}
</style>
<div class="diagram-wrap">
<!-- flowSVG 已含 id="diagram-flow" 和作用域化 <style> -->
</div>
AI 在将 SVG 写入 HTML 前，必须确认：
<svg id="diagram-xxx"> — 每张图有唯一 id，多图时 id 不重复<svg width="XXX" height="YYY"> — width 和 height 都是具体像素数值，不是 100%<svg viewBox="0 0 XXX YYY"> — viewBox 存在<style> 选择器以 #id 开头（如 #diagram-flow {），无裸 svg { 或 text {style 属性含 --_line、--_arrow 等直接颜色值max-width: 100% + height: auto<!-- ❌ 错误1：裸选择器污染（两张图样式互串） -->
<style>svg { --_line: red; } text { color: blue; }</style>
<!-- ❌ 错误2：只设 max-width，窄屏下图表被竖向截断 -->
.diagram-wrap svg { max-width: 100%; } /* 缺 height:auto */
<!-- ❌ 错误3：固定容器高度截断图表 -->
<div style="height:400px; overflow:hidden">
<svg width="800" height="600" ...>...</svg>
</div>
<!-- ✅ 正确：id 作用域 + max-width/height:auto + 具体宽高 -->
.diagram-wrap svg { display:block; max-width:100%; height:auto; width:auto; }
<svg id="diagram-flow" width="229" height="606" viewBox="0 0 229 606" style="--_line:#A1A1AA;...">
<style>#diagram-flow { --_line: #A1A1AA; } #diagram-flow path { stroke:#A1A1AA; }</style>
</svg>
当 AI 拿到「Copy Config」的内容后，可直接解析并用于批量渲染：
{
"theme": "dracula",
"preset": "gradient",
"themeColors": { "bg": "#282a36", "fg": "#f8f8f2", ... },
"cliCommand": "node scripts/render.js input.mmd -t dracula -p gradient -o output-dracula-gradient.svg",
"npmUsage": "renderMermaidSVG(code, THEMES['dracula'])"
}
AI 工作流示例：
tokyo-night + glass，点「Copy Config」theme / preset，用 -t tokyo-night -p glass 批量渲染所有 .mmd 文件graph TB
User[用户] -->|HTTP| Nginx[Nginx]
Nginx -->|反向代理| App[应用服务器]
App -->|查询| Redis[(Redis缓存)]
App -->|读写| MySQL[(MySQL数据库)]
graph TD
Start([开始]) --> Input[输入数据]
Input --> Validate{验证?}
Validate -->|通过| Process[处理数据]
Validate -->|失败| Error[显示错误]
Process --> Save[保存结果]
Save --> End([结束])
Error --> Input
sequenceDiagram
participant U as 用户
participant A as API网关
participant S as 服务
participant D as 数据库
U->>A: 发送请求
A->>S: 转发请求
S->>D: 查询数据
D-->>S: 返回数据
S-->>A: 处理结果
A-->>U: 响应
stateDiagram-v2
[*] --> 待处理
待处理 --> 处理中: 开始处理
处理中 --> 已完成: 处理成功
处理中 --> 失败: 处理失败
失败 --> 待处理: 重试
已完成 --> [*]
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
class Cat {
+meow()
}
Animal <|-- Dog
Animal <|-- Cat
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
PRODUCT ||--o{ LINE-ITEM : "is in"
CUSTOMER {
int id PK
string name
string email
}
ORDER {
int id PK
date created
string status
}
xychart-beta
title "Monthly Revenue"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Revenue ($K)" 0 --> 500
bar [180, 250, 310, 280, 350, 420]
xychart-beta
title "User Growth"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
line [1200, 1800, 2500, 3100, 3800, 4500]
xychart-beta
title "Sales with Trend"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
bar [300, 380, 280, 450, 350, 520]
line [300, 330, 320, 353, 352, 395]
renderMermaidSVG(text, options?): string将 Mermaid 代码渲染为 SVG 字符串。同步，可直接用于 React useMemo()。
参数：
text: string - Mermaid 图表代码options?: RenderOptions - 渲染选项RenderOptions：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
bg | string | #FFFFFF | 背景色（支持 CSS 变量） |
fg | string | #27272A | 前景色（支持 CSS 变量） |
line | string? | — | 连线颜色 |
accent | string? | — | 箭头、高亮色 |
muted | string? | — | 次要文字、标签 |
surface | string? | — | 节点填充色 |
border | string? | — | 节点边框色 |
font | string | Inter | 字体族 |
transparent | boolean | false | 透明背景 |
padding | number | 40 | 画布内边距 (px) |
nodeSpacing | number | 24 | 同级节点水平间距 |
layerSpacing | number | 40 | 层间垂直间距 |
componentSpacing | number | 24 | 断开组件间距 |
interactive | boolean | false | XY 图表悬浮 tooltip |
返回： string - SVG 字符串
renderMermaidSVGAsync(text, options?): Promise<string>异步版本，相同输出。适用于 async 上下文。
renderMermaidASCII(text, options?): string将 Mermaid 代码渲染为 ASCII/Unicode 艺术字。同步。
参数：
text: string - Mermaid 图表代码options?: AsciiRenderOptions - 渲染选项AsciiRenderOptions：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
useAscii | boolean | false | 使用 ASCII（true）或 Unicode（false） |
paddingX | number | 5 | 节点水平间距 |
paddingY | number | 5 | 节点垂直间距 |
boxBorderPadding | number | 1 | 节点框内边距 |
colorMode | string | 'auto' | 'none' | 'auto' | 'ansi16' | 'ansi256' | 'truecolor' | 'html' |
theme | Partial<AsciiTheme> | — | 自定义 ASCII 颜色 |
返回： string - ASCII 字符串
parseMermaid(text): MermaidGraph将 Mermaid 代码解析为结构化图对象（用于自定义处理）。支持流程图和状态图。
fromShikiTheme(theme): DiagramColors从 Shiki 主题对象提取图表颜色。映射关系：
| 编辑器颜色 | 图表角色 |
|---|---|
editor.background | bg |
editor.foreground | fg |
editorLineNumber.foreground | line |
focusBorder / keyword token | accent |
| comment token | muted |
editor.selectionBackground | surface |
editorWidget.border | border |
THEMES内置主题集合，每个主题包含完整 7 字段（bg/fg/line/accent/muted/surface/border）。完整色值见"核心能力 → 主题完整对照表"。
| 主题名 | 类型 | accent 色 | 推荐预设 |
|---|---|---|---|
tokyo-night | 暗色 | #7aa2f7 | glass |
tokyo-night-storm | 暗色 | #7aa2f7 | modern |
tokyo-night-light | 亮色 | #34548a | modern |
dracula | 暗色 | #bd93f9 | gradient |
github-dark | 暗色 | #4493f8 | modern |
github-light | 亮色 | #0969da | default |
nord | 暗色 | #88c0d0 | modern |
nord-light | 亮色 | #5e81ac | outline |
one-dark | 暗色 | #c678dd | gradient |
catppuccin-mocha | 暗色 | #cba6f7 | glass |
catppuccin-latte | 亮色 | #8839ef | modern |
solarized-dark | 暗色 | #268bd2 | modern |
solarized-light | 亮色 | #268bd2 | outline |
zinc-light | 亮色 | #3F3F46 | outline |
zinc-dark | 暗色 | #A1A1AA | glass |
orange-dark | 暗色 | #f97316 | glass |
orange-light | 亮色 | #ea580c | modern |
DEFAULTS默认颜色值（完整 7 字段）：
{
bg: '#FFFFFF', // 画布背景
fg: '#27272A', // 主文字
line: '#A1A1AA', // 连线
accent: '#3F3F46', // 强调色
muted: '#71717A', // 次要色
surface: '#F4F4F5', // 节点填充次级色
border: '#D4D4D8', // 节点边框
}
// 导入样式预设模块
import { STYLE_PRESETS, generateCSSStyles, injectStylesToSVG } from './scripts/styles.js';
import { renderMermaidSVG } from 'beautiful-mermaid';
// 1. 渲染基础 SVG
const svg = renderMermaidSVG(code, {
bg: '#f7f7fa',
fg: '#27272a',
line: '#6b7280'
});
// 2. 应用样式预设 (Node.js 环境)
const styledSvg = injectStylesToSVG(svg, {
bg: '#f7f7fa',
fg: '#27272a',
line: '#6b7280'
}, 'modern');
// 3. 获取 CSS 字符串（可选）
const css = generateCSSStyles({ bg: '#f7f7fa', fg: '#27272a' }, 'modern');
console.log(css);
npm audit 输出，及时升级 beautiful-mermaid 至包含安全修复的最新版本。renderMermaidSVG 和 renderMermaidASCII 都是同步函数，可直接用于 React 的 useMemorenderMermaidSVGAsync 返回 Promise<string>，适用于 async 上下文--preset 与 --theme 可以自由联用：-t dracula -p gradient 完全合法；不传 --preset 时自动使用该主题的推荐预设<style> 标签位于 <svg> 之后，使用 !important 确保覆盖var(--xxx) 作为颜色值，SVG 可实时响应主题变化xychart-beta 语法，accent 颜色驱动图表系列配色linkStyle 内联边样式覆盖style A fill:#xxx 或 classDef xxx fill:#yyy 写死颜色——这些硬编码颜色会被 cleanHardcodedColors() 清除。应改用 # @roles 声明语义角色，颜色由主题自动决定@roles 仅对当前 .mmd 文件生效；节点 ID 区分大小写，须与 Mermaid 代码里的 ID 完全一致render.js 生成的 SVG 也支持语义角色着色（含 PNG 导出）；rich-html.js 额外显示图例条