anymermaid

name	anymermaid
description	使用 Mermaid 语法生成图表，并通过 mmdc CLI 渲染为 SVG/PNG/PDF 文件。当用户要求创建流程图、时序图、类图、状态图、ER 图、甘特图、饼图、思维导图、时间线、Git 图、架构图、看板、象限图，或任何 Mermaid 支持的图表类型时使用此技能。当用户提到 "mermaid"、"anymermaid"、".mmd"、"mmdc"，或希望将关系、流程、架构、数据流等可视化为图表时也触发。即使用户只是说"画个图"、"画个流程图"、"画个时序图"、"做个图"而未指定工具，也应主动使用。
version	1.0.0
author	anyforge

AnyMermaid 画图技能

使用 Mermaid 的文本语法创建图表，并通过 mmdc CLI 工具渲染为图片文件（SVG/PNG/PDF）。

覆盖 26 种官方图表类型的完整语法参考、跨平台（macOS / Linux / Windows）命令、以及 puppeteer 沙箱、headless 环境、stdin 直渲、干跑校验等实战经验。

工作流程

1. 识别图表类型：根据用户需求对照图表类型表
2. 查阅语法参考：仅读取 references/syntax.md 中对应类型的章节（详见查阅语法参考）
3. 决定是否落文件：
   • 图 ≤ 15 行 且 用户不需要保留源：直接用 stdin heredoc 一步渲染，不落中间文件
   • 图 > 15 行 或 用户需要保留源：将内容写入当前工作目录下的 .mmd 文件
4. 渲染前干跑校验（可选但推荐，见干跑校验）
5. 渲染为指定格式：用 mmdc 命令渲染（见渲染输出）
6. 打开结果：见打开结果，headless 环境自动跳过
7. 保留 .mmd 文件：渲染成功后保留 .mmd 文件，便于用户不满意时修改重渲
8. 删除中间文件：仅当用户明确确认满意后，才删除 .mmd 文件

图表类型

根据用户意图选择图表类型。确定类型后，仅从 references/syntax.md 读取对应章节的语法，不需要加载其他章节。

用户意图	图表类型	Mermaid 关键字
流程、决策、工作流	流程图	graph / flowchart
参与者之间的时序交互	时序图	sequenceDiagram
类/对象结构、继承关系	类图	classDiagram
状态转换、生命周期	状态图	stateDiagram-v2
数据库表与关系	ER 图	erDiagram
项目排期、里程碑、任务	甘特图	gantt
占比、百分比	饼图	pie
Git 分支/合并历史	Git 图	gitGraph
用户体验步骤（含满意度打分）	用户旅程图	journey
围绕中心主题的层级结构	思维导图	mindmap
按时间排列的事件/路线图	时间线图	timeline
2x2 战略定位	象限图	quadrantChart
软件架构（上下文/容器/组件）	C4 图	C4Context 等
需求追溯	需求图	requirementDiagram
流量/能量流向	桑基图	sankey-beta
柱状图 / 折线图	XY 图表	xychart-beta
分列/嵌套架构块	块图	block-beta
网络协议数据包字段	数据包图	packet-beta
任务看板（列 + 卡片）	看板图	kanban
云原生系统架构	架构图	architecture-beta
多维度对比	雷达图	radar-beta
事件驱动设计	事件建模图	eventmodeling
层级占比矩形	树状图	treemap-beta
集合交集	韦恩图	venn-beta
根因分析（鱼骨图）	石川图	ishikawa-beta
战略演化映射	Wardley 地图	wardley-beta

查阅语法参考

references/syntax.md 收录了完整的图表语法，文件较长（>400 行）。为节省上下文，只加载当前需要的章节，不要整文件读入。

推荐的区间加载方法（以"用户旅程图"为例）：

1. 用 grep 定位目标章节起始行：

   grep -n "^## 用户旅程图" references/syntax.md
   

2. 用 grep 列出所有 ## 标题行，找到紧随目标章节之后的下一个标题，得到结束行：

   grep -n "^## " references/syntax.md
   

3. 用 read 的 offset / limit 只读取该区间：
   • offset = 目标章节起始行
   • limit = 下一章节起始行 - 目标章节起始行

references/syntax.md 顶部已提供目录，可先读取前 ~25 行了解章节命名，再按上述方法精确定位。

选择输出格式

根据用户请求判断：

• 画个流程图 / 未指定格式 → 默认 SVG
• png 流程图 / 导出为 png → PNG
• 画个甘特图，要 pdf → PDF

SVG 为默认格式：可缩放、清晰、适合文档嵌入。

格式	扩展名	适用场景
SVG	.svg	默认。可缩放，任意分辨率都清晰，适合文档
PNG	.png	幻灯片 / 不支持 SVG 的文档场景
PDF	.pdf	打印场景

渲染输出

前置检测

渲染前必须先检测 CLI 是否已安装。按当前操作系统选用对应命令：

# macOS / Linux / WSL / Git Bash
command -v mmdc || which mmdc

# Windows PowerShell
Get-Command mmdc -ErrorAction SilentlyContinue

:: Windows cmd
where mmdc

• 已安装：返回可执行路径，直接进入下一步渲染

• 未安装：命令无输出或返回非零。此时不要自行执行 npm install 等安装命令，应停止流程并提示用户：

  未检测到 mmdc（Mermaid CLI）。请先安装后再使用本技能。任选一种：

  # 全局安装（三平台通用，需要 Node.js ≥ 18）
  npm install -g @mermaid-js/mermaid-cli
  
  # 免安装单次运行（每次会临时下载）
  npx  -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
  pnpm dlx @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
  bunx @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
  

  安装完成后告知我，我会继续渲染。

  等待用户确认安装完成后再继续，避免擅自改动用户环境。

仓库：https://github.com/mermaid-js/mermaid-cli ；官方文档：https://mermaid.nodejs.cn/

基本命令（跨平台）

推荐默认参数：渲染时始终使用 -w 1600 -s 3，确保输出清晰度与布局宽度。仅在用户明确指定其他值时覆盖。

-s（Puppeteer 缩放）只影响位图（PNG/PDF），对 SVG 无效；-w 对 SVG 依然生效——它会影响初始布局宽度，长链流程图（flowchart LR）尤其明显。因此 SVG 也建议带 -w 1600。

以下命令在 macOS / Linux / Windows 三平台完全一致（mmdc 是跨平台 Node CLI，参数与调用方式相同）：

# SVG（推荐带 -w 控制布局宽度）
mmdc -i diagram.mmd -o diagram.svg -w 1600

# PNG（推荐默认参数，确保清晰度）
mmdc -i diagram.mmd -o diagram.png -w 1600 -s 3 -b white

# PDF（自动适配图表大小）
mmdc -i diagram.mmd -o diagram.pdf -f

Windows 用 PowerShell 或 cmd 都可，命令原样输入即可。仅路径分隔符需按各自 shell 惯例（PowerShell 支持 / 与 \，cmd 用 \）。

stdin 直渲（小图）

图小于 ~15 行、且用户不需要保留 .mmd 源时，从 stdin 输入可省去创建/清理文件的开销。shell 语法各异，选一种：

# macOS / Linux / WSL / Git Bash（heredoc）
mmdc -i - -o diagram.svg -w 1600 <<'EOF'
graph TD
    A[客户端] --> B[负载均衡]
    B --> C[服务 1]
    B --> D[服务 2]
EOF

# Windows PowerShell（here-string @'...'@ 逐字量，避免变量插值）
@'
graph TD
    A[客户端] --> B[负载均衡]
    B --> C[服务 1]
    B --> D[服务 2]
'@ | mmdc -i - -o diagram.svg -w 1600

:: Windows cmd 无原生 heredoc，退回落文件的常规方式
:: 建议直接写 .mmd 文件后 `mmdc -i diagram.mmd -o diagram.svg`

常用参数

参数	说明	示例
-i, --input	输入 .mmd 文件（- 表示从 stdin 读取）	-i diagram.mmd
-o, --output	输出文件路径	-o diagram.svg
-t, --theme	主题：default、forest、dark、neutral	-t dark
-b, --backgroundColor	背景色（仅 PNG/SVG）	-b transparent
-w, --width	页面宽度 px（CLI 默认 800，本技能默认 1600）	-w 1600
-H, --height	页面高度 px（默认 600）	-H 900
-s, --scale	Puppeteer 缩放因子（仅位图，CLI 默认 1，本技能默认 3）	-s 3
-c, --configFile	Mermaid JSON 配置文件	-c config.json
-C, --cssFile	自定义 CSS 文件	-C style.css
-p, --puppeteerConfigFile	Puppeteer 启动参数（沙箱等）	-p puppeteer-config.json
-q, --quiet	静默模式，不输出日志	-q
-f, --pdfFit	PDF 自动缩放以适应图表（仅 PDF）	-f

示例

# 渲染为 SVG（默认）
mmdc -i flowchart.mmd -o flowchart.svg -w 1600

# 渲染为 PNG，推荐默认参数（宽 1600，3 倍缩放）
mmdc -i flowchart.mmd -o flowchart.png -b white -w 1600 -s 3

# 渲染为 PDF，自动缩放适配
mmdc -i gantt.mmd -o gantt.pdf -f

# 静默模式，保持终端整洁
mmdc -q -i diagram.mmd -o diagram.svg

干跑校验

写完 .mmd 后正式渲染前，可先跑一次到临时路径快速验证语法。注意各平台的临时目录：

# macOS / Linux
mmdc -q -i diagram.mmd -o /tmp/anymermaid-dryrun.svg && echo OK || echo FAIL

# Windows PowerShell
mmdc -q -i diagram.mmd -o "$env:TEMP\anymermaid-dryrun.svg"; if ($?) { "OK" } else { "FAIL" }

:: Windows cmd
mmdc -q -i diagram.mmd -o "%TEMP%\anymermaid-dryrun.svg" && echo OK || echo FAIL

• OK：语法正确，继续用正式参数渲染
• FAIL：查看错误信息定位行号，修正 .mmd 后重跑

高级配置

需要自定义主题变量、布局选项或时序图设置时，创建 JSON 配置文件：

{
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#4A90D9",
    "lineColor": "#888"
  },
  "flowchart": { "curve": "basis" }
}

mmdc -c config.json -i diagram.mmd -o diagram.svg

完整配置项见 Mermaid 配置 Schema。

Puppeteer 沙箱配置（Docker / CI / Linux / WSL 必备）

在 Docker、CI 或部分 Linux/WSL 环境下，Puppeteer 会因缺少沙箱权限报错： Failed to launch the browser process / No usable sandbox。macOS 与 Windows 桌面环境通常不需要这项配置。

创建 puppeteer-config.json：

{
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}

调用时通过 -p 传入（三平台命令一致）：

mmdc -p puppeteer-config.json -i diagram.mmd -o diagram.svg

字体缺失导致中文乱码时：

• Linux / Docker：apt-get install -y fonts-wqy-zenhei fonts-liberation
• WSL：同 Linux，或直接使用 Windows 字体挂载
• macOS / Windows：系统自带中文字体，无需处理

处理 Markdown 文件

如果 Markdown 文件中包含 ```mermaid 代码块，mmdc 可以一次性提取并渲染其中所有图表：

mmdc -i document.md -o document-rendered.md

打开结果

渲染完成后打开预览。headless / 远程环境自动跳过，仅打印绝对路径。

macOS / Linux / WSL（bash / zsh）

FILE=diagram.svg
if [ -n "$SSH_CONNECTION" ] || [ ! -t 1 ]; then
    echo "[headless] $(cd "$(dirname "$FILE")" && pwd)/$(basename "$FILE")"
else
    case "$(uname -s)" in
        Darwin) open "$FILE" ;;
        Linux)  xdg-open "$FILE" 2>/dev/null || realpath "$FILE" ;;
        MINGW*|MSYS*|CYGWIN*) start "" "$FILE" ;;
    esac
fi

WSL2 打开 Windows 端应用时用：

cmd.exe /c start "" "$(wslpath -w diagram.svg)"

Windows PowerShell

$File = "diagram.svg"
if ([Environment]::UserInteractive -and -not $env:SSH_CONNECTION) {
    Invoke-Item $File
} else {
    Write-Host "[headless] $((Resolve-Path $File).Path)"
}

Windows cmd

start "" "diagram.svg"

平台命令速查

环境	命令
macOS	open <文件>
Linux（有 GUI）	xdg-open <文件>
WSL2 → Windows 打开	cmd.exe /c start "" "$(wslpath -w <文件>)"
Windows PowerShell	Invoke-Item <文件> 或 ii <文件>
Windows cmd	start "" <文件>
SSH / CI / 无 GUI	跳过打开，仅打印绝对路径

无论是否打开，都要打印输出文件的绝对路径，便于用户手动定位。

文件命名

• 基于图表内容的有意义命名：login-flow、database-schema、deployment-architecture
• 多词名称使用小写加连字符
• 扩展名反映格式：login-flow.svg、gantt-chart.png

渲染前校验

Mermaid 对语法要求严格。写入 .mmd 文件前先检查：

• 第一行是合法的图表关键字（graph、sequenceDiagram、classDiagram 等）
• 节点 ID 不含空格（用方括号/引号包裹的 label 来显示文本）
• 标签中的特殊字符用引号包裹：A["节点 (含括号)"]
• 箭头类型合法（-->、->>、-->>、-.->、==>、-)、--x）
• 流程图关键字后需跟方向（TD、LR、BT、RL）

如果 mmdc 报解析错误，根据错误信息定位行号、修正 .mmd 文件后重试；或先跑一次干跑校验。

主题

用 -t 切换视觉主题，无需修改图表内容：

主题	适用场景
default	默认，清爽文档风格，多数场景适用
forest	绿色调，自然/环保主题
dark	暗色幻灯片 / 夜间模式文档
neutral	灰度，正式 / 印刷报告

排错

问题	原因	解决方案
解析错误 / unknown error	Mermaid 语法不合法	阅读错误信息，修正 .mmd 文件后重试
输出空白	图表关键字缺失或拼写错误	第一行必须以合法关键字开头
含特殊字符的标签出错	字符未转义	用引号包裹标签：A["节点 (文本)"]
节点 ID 含空格失败	ID 必须是单个标识符	用 camelCase 或下划线做 ID，文本放在 label 中
Puppeteer/Chrome 启动报错	无头浏览器沙箱不可用	见 Puppeteer 沙箱配置
大图被截断	默认页面过小	增大 -w / -H，或用 -s 缩放（仅位图）
SVG 布局压缩变形	未设 -w	加 -w 1600 提供足够画布宽度
中文乱码（Docker / Linux CI）	无中文字体	安装 fonts-wqy-zenhei 或类似字体包
Windows mmdc 不识别	PATH 未更新	关闭当前终端重开；或用 npx @mermaid-js/mermaid-cli
Windows PowerShell 报"脚本被禁止"	执行策略限制	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 后重试