Beautiful Mermaid Skill

概述

Beautiful Mermaid 是一个高性能的 Mermaid 图表渲染库，专为 AI 时代设计。它将 Mermaid 语法转换为美观的 SVG 图形、PNG 位图或 ASCII 艺术字，支持同步渲染、全主题定制、CSS级样式定制，零 DOM 依赖。

核心能力

1. 支持的图表类型

• 流程图 (Flowchart)：graph TD、graph LR、graph BT、graph RL 等方向
• 序列图 (Sequence Diagram)：参与者之间的交互
• 状态图 (State Diagram)：状态转换
• 类图 (Class Diagram)：面向对象设计
• 实体关系图 (ER Diagram)：数据库设计
• XY 图表：条形图、折线图、组合图（xychart-beta 语法）

2. 输出格式

• SVG：适用于富 UI 界面，支持透明背景和内联样式
• PNG：适用于文档嵌入、高清位图输出，支持自定义尺寸和 DPI
• ASCII/Unicode：适用于终端环境，支持颜色输出

3. 主题系统

• 15 内置主题：tokyo-night、dracula、github-dark、nord 等（9 暗色 + 6 亮色）
• 完整 7 字段：每个主题包含 bg、fg、line、accent、muted、surface、border 全部字段
• Mono 模式：仅需提供背景色(bg)和前景色(fg)，自动推导整套配色
• 自定义主题：可覆盖任意元素颜色
• Shiki 集成：通过 fromShikiTheme() 直接使用 VS Code 编辑器主题

主题完整对照表

主题字段说明

推荐主题 × 预设搭配

tokyo-night   + glass     → 代码架构图的最佳组合（深蓝毛玻璃）
dracula       + gradient  → 视觉展示最强（紫色渐变阴影）
github-light  + default   → 文档嵌入首选（简洁中性）
catppuccin-mocha + glass  → 产品 Deck 展示（柔和紫色调）
nord          + modern    → 技术报告暗色版（冰蓝现代感）
one-dark      + gradient  → 紫色调视觉最强（彩色阴影）
orange-dark   + glass     → 暖色系深色主题（橙色毛玻璃）
orange-light  + modern    → 暖色系浅色主题（橙色现代感）

> AI 预览工作规则（最高优先级）：任何涉及渲染 Mermaid 图表的请求，无论用户是否已指定主题/预设，都必须先调用 preview_url 打开预览工具，让用户在 preview.html 中直观确认效果后，再执行渲染命令。

>

> 触发场景（包括但不限于）：

> - 用户询问主题/配色推荐

> - 用户已明确指定主题和预设（如"用 tokyo-night + glass 渲染"）→ 仍需先打开 preview 让用户确认，不得跳过

> - 需要查看图表效果

> - 任何使用 skill 渲染图表的场景

>

> 打开方式（唯一合法方式）：

> - 工具：preview_url

> - URL：file://{__SKILL_DIR__}/assets/preview.html（__SKILL_DIR__ 为技能安装目录的绝对路径）

>

> 唯一例外：用户明确说"直接渲染，不用预览"或"跳过预览"时，才可跳过 preview 步骤。

>

> 禁止：

> - 使用 open/start/xdg-open 等命令打开系统浏览器

> - 启动 python3 -m http.server 或任何本地 HTTP 服务

> - 用户未明确说跳过时，擅自跳过 preview 直接执行渲染

>

> 用户打开预览后，可在 Themes 和 Presets 标签页中直接点击切换对比效果。

4. 样式定制系统

• 节点样式：圆角、边框、阴影、填充色
• 连线样式：粗细、颜色、箭头、圆角
• 字体排版：支持多种字体和响应式适配
• 5种预设风格：默认、现代简约、渐变、线条轮廓、毛玻璃

使用方法

安装

npm install beautiful-mermaid
# 或
bun add beautiful-mermaid

交互式预览工具

提供可视化的样式定制界面，AI 必须用 preview_url 工具直接以文件路径打开（在 IDE 内置浏览器中显示，无需服务器）：

preview_url(`file://{__SKILL_DIR__}/assets/preview.html`)

❌ 禁止使用 open/start 命令或启动任何 HTTP 服务器。

预览工具功能：

• 15 主题即时预览：点击切换，实时查看效果
• 5 种样式预设：default / modern / gradient / outline / glass
• 自定义颜色：背景色、前景色、连线颜色
• 9 种图表类型：Flowchart、Sequence、State、Class、ER、Bar、Line、Combo、H-Bar
• 实时代码编辑器：支持自定义 Mermaid 代码，Tab 缩进，400ms debounce 自动渲染
• 状态持久化：所有选择（主题、预设、颜色、自定义代码）自动保存到 localStorage
• 一键导出：复制代码或导出带完整样式的 SVG 文件

丰富结果 HTML（多图表聚合展示）

当用户需要将多张 Mermaid 图表整合为一个专业的展示页面时，使用 scripts/rich-html.js。

生成的 HTML 包含：

• 顶部 Badge（显示主题和预设）+ 标题 + 副标题
• 标签页导航（每张图表对应一个 Tab，支持 ① ② ③ … 编号）
• 每个 Tab 内的信息卡片网格（图表类型 + 自定义元数据）
• 卡片式 SVG 图表区（带图标、标题、描述）
• 底部页脚（渲染信息）
• 完整继承用户选择的主题风格（背景、前景、强调色等）

基本用法

# 方式一：直接调用脚本
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 组）

主题继承规则

生成的 HTML 完整继承渲染时指定的主题颜色：

• 页面背景 = 主题 bg
• 卡片/导航背景 = 主题 surface
• 边框 = 主题 border
• 正文文字 = 主题 fg
• 次要文字 = 主题 muted
• 强调色（Badge、Tab 激活、数值） = 主题 accent
• SVG 图表背景 = 比 bg 略深/浅，自动计算

> AI 工作规则：生成 rich-html 后，必须用 preview_url 工具打开生成的 HTML 文件，让用户直观查看效果。

SVG 渲染

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']);

ASCII 渲染

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 │
// │   │     │   │     │   │
// └───┘     └───┘     └───┘

React 集成

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 }} />;
}

XY 图表（柱状图、折线图、组合图）

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,
});

Shiki 主题集成

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);

CLI 命令行工具

基本用法

# 渲染文件为 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

# 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

命令行参数

PNG 输出说明

PNG 格式适用于文档嵌入、PPT 演示等场景：

• 默认宽度：1200px
• 默认 DPI：144（适合屏幕显示）
• 缩放范围：0.5x - 4x (通过 -s 参数)
• DPI 范围：72 - 600 (通过 --dpi 参数，72=屏幕，300=印刷)
• 透明背景：PNG 输出支持透明背景
• 高质量：默认 100% 质量输出

# 屏幕显示 (默认 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

可用预设对比：

批量渲染

使用 --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 输出文件。

ASCII 颜色模式

通过 --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
#   ...

参数优先级

1. --bg + --fg → 自定义基础配色（line/accent/muted 自动推导）
2. --theme 名称 → 从内置 15 主题取完整 7 字段配色
3. --theme JSON → 直接使用 JSON 对象（缺省字段自动补全）
4. --preset → 应用形状预设（与任何颜色来源都可以搭配）
5. 自动推荐预设 → 不传 --preset 时，自动使用主题推荐的预设

CSS 样式注入原理

样式预设通过 CSS 变量覆盖 实现：

1. beautiful-mermaid 库使用 CSS 变量：var(--_node-fill)、var(--_line)
2. render.js 在 SVG 标签后注入