技能使用指南

beautiful-mermaid（美丽美人鱼图表渲染工具）Skill 是什么？

beautiful-mermaid 技能可将 Mermaid 图表一键渲染为精美 SVG 或终端 ASCII 字符画，零 DOM 依赖、内置 15 套主题并支持 VS Code 主题联动，100+ 图表 500 毫秒内完成。本文详解安装步骤、核心 API、竞品对比与典型场景，帮你快速把图表能力接进 AI 编程与终端工作流。

美丽美人鱼图表渲染工具Skillbeautiful-mermaid
19 个章节 约 18 分钟阅读 AI 智能生成

美丽美人鱼图表渲染工具Skill：把 Mermaid 图表一键变成精美 SVG 与终端 ASCII 艺术

  • 零 DOM 依赖：纯 TypeScript 实现，在 Node.js、Bun、Deno 等服务端环境里也能直接渲染 Mermaid 图表，不需要浏览器。
  • 双输出形态：既能输出可嵌入网页、文档的高质量 SVG，也能输出适合终端、日志、AI 对话窗口的 ASCII/Unicode 字符画。
  • 15 个内置主题 + VS Code 主题直连：内置 zinc、tokyo-night、catppuccin、nord、dracula、github、solarized、one-dark 等主题，还能把任意 VS Code（Shiki）主题转成图表配色。
  • 极快：官方给出的性能指标为 100+ 个图表在 500 毫秒内并行渲染完成。
  • 一行安装即可用：npm install beautiful-mermaid，随后 renderMermaid / renderMermaidAscii 两个 API 覆盖绝大多数场景。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

这个技能的中文名是美丽美人鱼图表渲染工具Skill，英文名是 beautiful-mermaid，技能 ID 为 11779。

它解决的是一个非常具体的痛点：Mermaid 语法写起来很爽，但「渲染出来好看」这件事一直很麻烦。官方 Mermaid 渲染通常要跑在浏览器 DOM 环境里，样式定制能力有限；而在终端、CI 日志、AI 编程助手的对话流里，图形基本无法显示。美丽美人鱼把这件事拆成两条路——要图的场景输出 SVG，要字的场景输出 ASCII/Unicode 字符画，并且把配色、主题、字体等可控项全部暴露成参数。

安装前提

  • 需要一个 JavaScript/TypeScript 运行环境：Node.js（配合 npm）、Bun 或 pnpm 任选其一。
  • 项目中若要与 VS Code 主题联动，还需要额外引入 shiki（详情文档中给出的示例依赖）。
  • 该库为纯 TypeScript 实现，不需要安装浏览器、Canvas 或任何 DOM 相关依赖。

一键安装步骤

  1. 安装包本体（三种包管理器任选其一，均为技能详情中的官方命令）：
npm install beautiful-mermaid
# 或
bun add beautiful-mermaid
# 或
pnpm add beautiful-mermaid
  1. 在代码中导入核心 API：
import { renderMermaid, renderMermaidAscii, THEMES, fromShikiTheme } from 'beautiful-mermaid'
  1. 验证是否生效：用最短的一行图表做冒烟测试，能在控制台看到字符画即代表安装成功。
import { renderMermaidAscii } from 'beautiful-mermaid'
console.log(renderMermaidAscii('graph LR; A --> B'))
  1. 把技能挂到 AI 编程助手上：将该技能加入你的 AI 技能库后，当你在对话中提到「Mermaid 图表」「图表渲染」「流程图」「序列图」等关键词时，技能会被自动触发，由 AI 帮你生成图表代码并调用渲染能力输出结果。具体技能导入入口与命令请以你所使用的 AI 平台官方说明为准。

该技能的主要功能和特点

  • 支持 5 类主流图表：流程图（graph TD / graph LR）、状态图（stateDiagram-v2）、序列图（sequenceDiagram）、类图（classDiagram）、ER 图（erDiagram），基本覆盖日常架构设计、业务流程梳理、数据库建模的高频需求。
  • SVG 渲染（异步）：renderMermaid(diagram, options) 返回一个 SVG 字符串，可直接写入文件、作为 HTTP 响应返回，或塞进任何前端组件。
  • ASCII/Unicode 渲染（同步）：renderMermaidAscii(diagram, options) 同步返回纯文本图表，默认使用更美观的 Unicode 制表符，可通过 useAscii: true 切换为纯 ASCII 以获得最大兼容性。
  • 两色极简主题：只传 bg 和 fg 两个颜色，库会自动用 color-mix() 推导出文本透明度、节点填充、描边、连线箭头、次要标签等一整套调色板，配色门槛极低。
  • 丰富模式精细控制：需要精调时可单独指定 line、accent、muted、surface、border、font、transparent 七个维度。
  • 15 个内置主题开箱即用：zinc-light / zinc-dark、tokyo-night 系列三款、catppuccin 系列四款、nord、dracula、github-light / github-dark、solarized-light、one-dark。还能用展开运算符在预设主题上做局部覆盖。
  • VS Code 主题集成：通过 fromShikiTheme() 把任意 Shiki 主题转换成图表配色，让图表与编辑器、文档站点的视觉风格完全统一。
  • CSS 变量实时换肤：所有颜色都暴露为 CSS 自定义属性（如 --diagram-bg、--diagram-fg），浏览器中改一行变量即可切换主题，无需重新渲染图表。
  • 零 DOM 依赖 + 轻量打包：可在 Node.js 服务端、CLI 工具、无头环境中运行，这是它相对浏览器版 Mermaid 最大的结构性优势。
  • 批量并行渲染：配合 Promise.all 可并行处理大量图表，官方说明 100+ 个图表可在 500 毫秒内完成。

与普通工具相比强在哪？ 常规方案要么只能出图（且依赖浏览器）、要么只能出文本，而美丽美人鱼用同一份 Mermaid 源码同时覆盖「网页/文档」与「终端/AI 对话」两种交付形态，且把主题系统做成了可编程资产，而不只是几个预设皮肤。

如何使用该技能？

步骤 1：准备一段 Mermaid 图表源码

graph TD
    A[开始] --> B{是否有效？}
    B -->|是| C[处理]
    B -->|否| D[错误]
    C --> E[完成]
    D --> E

步骤 2：渲染成 SVG（用于网页、文档、汇报）

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// 方式一：只给两个颜色，其余自动推导
const svg1 = await renderMermaid(diagram, { bg: '#FFFFFF', fg: '#27272A' })

// 方式二：直接套用内置主题
const svg2 = await renderMermaid(diagram, THEMES['tokyo-night'])

// 方式三：在预设主题上局部覆盖强调色
const svg3 = await renderMermaid(diagram, { ...THEMES.nord, accent: '#ff6b6b' })

// 方式四：透明背景，用于叠加在卡片或海报上
const svg4 = await renderMermaid(diagram, { ...THEMES.nord, transparent: true })

输出说明：返回值为 SVG 字符串，写入 .svg 文件或直接作为 image/svg+xml 响应返回即可。

步骤 3：渲染成 ASCII / Unicode（用于终端、日志、AI 对话）

import { renderMermaidAscii } from 'beautiful-mermaid'

// 默认 Unicode，字符更美观
const text = renderMermaidAscii('graph LR; A --> B --> C')

// 纯 ASCII，兼容老终端
const ascii = renderMermaidAscii(diagram, { useAscii: true })

// 觉得太挤就调间距
const spaced = renderMermaidAscii(diagram, {
  paddingX: 4,
  paddingY: 2,
  boxBorderPadding: 1
})

输出说明：同步返回纯文本，可直接 console.log，或写进 Markdown 代码块、CI 构建日志。

步骤 4：按场景组合常见模式

使用模式 关键写法
CLI 工具读文件转字符画 readFileSync(process.argv[2], 'utf-8') + renderMermaidAscii
跟随系统深色模式 matchMedia('(prefers-color-scheme: dark)') 决定用 tokyo-night 还是 github-light
批量渲染 Promise.all(diagrams.map(d => renderMermaid(d, THEMES['one-dark'])))
HTTP 服务 Express 路由中渲染后 res.type('image/svg+xml').send(svg)
文件监视自动更新 fs.watch('diagram.mmd') 后重新渲染并写入 output.svg
编辑器配色联动 fromShikiTheme(highlighter.getTheme('vitesse-dark')) 后传给 renderMermaid

步骤 5：排查常见问题

  • 语法报错：该库不校验 Mermaid 语法，请先用官方 Mermaid 在线编辑器验证源码。
  • 颜色不生效：必须传十六进制色值（如 #1a1b26），不支持 rgb() 写法。
  • 字体缺失：SVG 默认使用 Inter，可用 font 选项覆盖。
  • ASCII 太窄：调大 paddingX 与 boxBorderPadding。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
美丽美人鱼（beautiful-mermaid） 零 DOM 依赖的 Mermaid 渲染库，双输出形态 SVG（异步）+ ASCII/Unicode（同步）、15 个内置主题、Shiki 主题集成、CSS 变量换肤 低，npm install 一行安装，两个核心 API AI 编程助手、终端工作流、文档站、批量图表生成 优势：无需浏览器、主题体系可编程、批量渲染快；不足：仅支持 5 类图表，不自带语法校验
Mermaid 官方库（mermaid.js） 浏览器端 Mermaid 渲染标准实现 图表类型最全、生态最大、在线编辑器完善 中，通常需 DOM 环境或 headless 浏览器 前端页面内嵌图表、官方编辑器 优势：图表类型覆盖最广、社区资源多；不足：服务端渲染需额外方案，终端场景基本不可用
Mermaid CLI（mmdc） 命令行批量转图片 把 .mmd 转成 SVG/PNG/PDF 中高，依赖 Puppeteer/无头浏览器 CI 中生成图片资源 优势：可产出位图；不足：依赖重、启动慢，无 ASCII 输出
mermaid-ascii（Go 实现） 终端字符画渲染 把 Mermaid 转成 ASCII 文本 中，需 Go 环境或预编译二进制 纯终端场景 优势：字符画引擎成熟；不足：无 SVG 输出、无主题系统。美丽美人鱼的 ASCII 引擎正是移植自该项目

选型建议：只要场景中出现「终端」「AI 对话」「服务端」「无需浏览器」中的任意一项，美丽美人鱼就是更轻的选择；如果必须产出 PNG/PDF 位图，则仍需搭配 Mermaid CLI 之类的工具。

该技能的典型应用场景与实际体验情况

场景一：AI 编程助手的图表即时反馈

角色：使用 AI 结对编程的开发者。 痛点：AI 在对话里生成的 Mermaid 代码无法直接看到效果，只能复制到在线编辑器里粘贴预览，来回打断思路。 使用方式：技能被激活后直接调用 renderMermaidAscii()，把流程以字符画形式回显在对话窗口或终端里。 实际体验：这是它最顺手的场景。同步 API 意味着不需要等待 Promise、不需要任何额外环境，字符画在终端里即时出现；缺点是复杂图表在窄终端下会换行错位，需要调 paddingX 或改用 SVG。

场景二：文档站点的主题一致性

角色：维护技术文档站的前端/文档工程师。 痛点：文档站用 Shiki 高亮代码，但图表配色是另一套，视觉割裂。 使用方式：用 fromShikiTheme() 读取站点正在使用的 Shiki 主题，转换后直接传给 renderMermaid()，让图表配色与代码块完全同源。 实际体验：这是相当巧妙的设计点——不需要手工调色，主题换一次，图表跟着换。配合 CSS 变量还能实现用户点击「深色/浅色」按钮时图表即时切换而无需重新渲染。

场景三：CI/CD 与运维日志中的流程可视化

角色：DevOps 工程师。 痛点：流水线状态、部署链路、数据流关系写在日志里全是文字，排查时理解成本高。 使用方式：在构建脚本或服务端代码中同步渲染 ASCII 图，随日志一起输出。 实际体验：零 DOM 依赖是关键——不需要在构建镜像里塞一个 Chromium。上手成本极低，一个 import 加一行调用即可；注意终端字体需支持 Unicode 制表符，老环境要加 useAscii: true。

场景四：批量图表生成与静态站点构建

角色：内容运营 / 技术写作者。 痛点：一篇文章里有十几张架构图，逐张导出图片效率低下。 使用方式：Promise.all 并行渲染所有图表，统一写入 output.svg 或用 fs.watch 监听源文件变化自动重渲染。 实际体验：官方数据是 100+ 图表在 500 毫秒内完成，实际体感确实很轻快。需要注意的是该库不做语法校验，源文件写错时会直接抛错，建议在批量脚本里加 try/catch 并单独记录出错的文件名。

该技能能为用户带来的价值

1. 把「画图」从手工劳动变成代码资产。 图表以 Mermaid 源码形式进入版本库，一处修改、全局生效，而渲染交给一行 API，配合文件监视器可做到保存即更新。

2. 消除环境依赖，降低部署门槛。 零 DOM 依赖意味着渲染逻辑可以跑在任何 Node 环境里，不需要浏览器、不需要无头 Chromium、不需要在容器里装一堆系统库，镜像体积和构建时间都能省下来。

3. 主题体系从「选皮肤」升级为「可编程配色」。 两色极小配置即可生成完整调色板，把配色这件事的输入从七八个变量压缩到两个；需要精调时又能展开到七个维度。配合 Shiki 集成和 CSS 变量，长期看能显著降低多端视觉一致性的维护成本。

4. 让终端与 AI 对话也能「看见」结构。 ASCII/Unicode 输出把图表能力延伸到了那些天生不支持图形的地方——这恰恰是 AI 编程工作流的主战场。

5. 性能带来的批量可行性。 100+ 图表 500 毫秒内的渲染速度，让「每次构建都重新生成全部图表」成为可接受的策略，从而彻底摆脱手工导出图片的流程。

常见问题 FAQ

Q1：这个技能怎么安装？需要什么前置条件？ 用 npm install beautiful-mermaid（或 bun add / pnpm add）安装后，从包中导入 renderMermaid、renderMermaidAscii、THEMES、fromShikiTheme 即可使用。前置条件只有一个 JavaScript/TypeScript 运行环境，不依赖浏览器或 DOM。若要接入 AI 编程助手，请按其平台的技能导入方式添加，具体入口以官方说明为准。

Q2：这个技能收费吗？ 该库以开源包形式发布在 npm 上，仓库与 NPM 包地址在技能详情中均有给出。至于商用授权范围、是否需要署名等细节，请以仓库中的许可证和官方说明为准。使用该技能本身不涉及额外的付费调用。

Q3：它和 Mermaid 官方库有什么区别？我该选哪个？ 官方 mermaid.js 图表类型最全、生态最成熟，但通常需要 DOM 环境，终端场景基本不可用。美丽美人鱼主打零 DOM 依赖和「SVG + ASCII」双输出，并把主题做成了可编程资产。如果你的场景是服务端渲染、终端输出、AI 助手内联展示，选它更合适；如果需要极冷门的图表类型或必须产出 PNG 位图，官方生态或 Mermaid CLI 更稳妥。

Q4：支持哪些图表类型？支不支持思维导图、甘特图？ 根据技能详情，目前支持流程图、状态图、序列图、类图和 ER 图共 5 类，未包含思维导图、甘特图、时序甘特等类型。若有这类需求，需要回到 Mermaid 官方渲染方案。

Q5：图表渲染出来颜色不对或报错怎么办？ 按文档列出的四个高频原因逐项排查：一是 Mermaid 语法本身有误（该库不校验语法，请先用官方在线编辑器验证）；二是颜色值写成了 rgb() 形式，必须用十六进制；三是 SVG 字体缺失，可用 font 选项覆盖默认的 Inter；四是 ASCII 输出过窄，调大 paddingX 和 boxBorderPadding。