Mermaid 图像生成器

使用 mermaid.ink 在线渲染 API，将 Mermaid 图表语法转换为 PNG/SVG 图像。零依赖 —— 仅使用 Node.js 内置模块和 curl。

快速开始

# 从 .mmd 文件转换
node scripts/mermaid-to-image.js diagram.mmd output.png

# 从标准输入（stdin）读取
echo "flowchart LR; A --> B" | node scripts/mermaid-to-image.js - output.png

# 生成 SVG 格式
node scripts/mermaid-to-image.js diagram.mmd output.svg

适用场景

在以下情况下使用该能力：

• 用户要求“绘制图表”、“创建流程图”、“生成可视化内容”
• 用户需要为 PPT、文档或演示文稿准备图表图像
• 用户希望将 Mermaid 代码转换为可分享的图像文件
• 本地 Mermaid CLI（mmdc）不可用，或存在依赖问题

脚本用法

基础转换

node scripts/mermaid-to-image.js <输入> <输出>

输入方式：

• 文件路径：例如 diagram.mmd
• 标准输入：使用 -（直接通过管道传入 Mermaid 代码）

输出格式：由输出文件扩展名决定（.png 或 .svg）

示例

示例 1：将文件转换为 PNG

node scripts/mermaid-to-image.js flowchart.mmd flowchart.png

示例 2：从标准输入读取（管道方式）

cat <>Bob: Hello
    Bob-->>Alice: Hi
EOF

示例 3：为网页生成 SVG

node scripts/mermaid-to-image.js architecture.mmd architecture.svg

支持的 Mermaid 图表类型

本能力支持全部 Mermaid 图表类型：

Mermaid 代码示例

流程图

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

序列图

sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: POST /login
    API->>Database: Query
    Database-->>API: Result
    API-->>User: Response

类图

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal: +int age
    Animal: +String gender
    Animal: +isMammal()

API 详情

服务： mermaid.ink
端点：

• PNG： https://mermaid.ink/img/{base64_code}
• SVG： https://mermaid.ink/svg/{base64_code}

优势：

• ✅ 无需本地依赖（不需 Chrome/Puppeteer）
• ✅ 免费且响应迅速
• ✅ 输出高质量 PNG/SVG 图像
• ✅ 可在无头（headless）环境中运行

限制：

• 需联网访问
• 图表代码将发送至外部服务（请勿用于含敏感信息的图表）

错误处理

脚本已内置常见错误处理机制：

❌ 文件未找到：diagram.mmd
❌ API 请求失败：400 Bad Request
❌ 连接 mermaid.ink 失败：连接超时

排查建议：

1. 检查网络连接是否正常
2. 在 https://mermaid.live 验证 Mermaid 语法是否正确
3. 确认输出目录存在（脚本会自动创建目标目录）

集成模式

为用户生成图表时的标准流程：

1. 编写 Mermaid 代码 → 保存为 .mmd 文件，或直接通过 stdin 输入
2. 运行转换脚本 → 生成 PNG/SVG 图像
3. 交付图像 → 作为附件返回、或保存至指定路径

典型工作流示例：

# 1. 创建图表文件
cat > openclaw-flow.mmd < OpenClaw
    OpenClaw --> Tools
EOF

# 2. 转换为图像
node scripts/mermaid-to-image.js openclaw-flow.mmd openclaw-flow.png

# 3. 使用图像（如：发送消息、保存等）

最佳实践

1. 保持图表简洁 —— 节点数建议控制在 15 个以内以保障可读性
2. 使用有意义的标签 —— 图表自身应具备自解释性
3. 先验证语法再转换 —— 在 mermaid.live 中完成语法校验
4. 合理选择格式 —— PPT 推荐 PNG；网页/技术文档推荐 SVG
5. 添加注释 —— 使用 %% 在图中嵌入说明性注释

安全须知

• 图表代码将通过网络发送至 mermaid.ink API
• 请勿在图表中包含任何敏感信息
• 涉及敏感数据时，请改用本地 Mermaid CLI（mmdc）进行离线渲染