Anymermaid Skill

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 读取对应章节的语法，不需要加载其他章节。

查阅语法参考

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 为默认格式：可缩放、清晰、适合文档嵌入。

渲染输出

前置检测

渲染前必须先检测 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
  

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

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

仓库： ；官方文档：

基本命令（跨平台）

推荐默认参数：渲染时始终使用 -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`

常用参数

示例

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

平台命令速查

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

文件命名

• 基于图表内容的有意义命名：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 切换视觉主题，无需修改图表内容：

排错