Mermaid Workflow Skill

生成Mermaid图表定义文件，调用Mermaid CLI转换为PNG，并将图片链接插入指定Markdown文件位置。

描述

按照新的工作流程创建和处理Mermaid图表：先生成Mermaid格式的图表定义文件(.mmd)，然后调用终端命令运行mmdc (Mermaid CLI)将.mmd转换为PNG，最后将图片链接插入Markdown文件对应的位置。

激活条件

当用户需要创建或处理以下类型的图表时激活此技能：

• 技术路线图
• 系统架构图
• 流程图
• 序列图
• 类图
• 状态图
• 甘特图
• ER图
• 以及其他Mermaid支持的图表类型

核心工作流程

1. 创建Mermaid定义文件 (.mmd)
2. 转换为PNG图片 (使用mmdc CLI)
3. 插入Markdown文件 (替换占位符或插入到指定位置)

文件结构

mermaid-workflow-skill/
├── SKILL.md (本文件)
├── scripts/
│   ├── create_mermaid.py (创建Mermaid图表)
│   ├── convert_mermaid.py (转换Mermaid为PNG)
│   └── insert_to_md.py (插入图片到Markdown)
├── templates/
│   ├── roadmap.mmd (技术路线图模板)
│   ├── architecture.mmd (系统架构图模板)
│   ├── flowchart.mmd (流程图模板)
│   └── sequence.mmd (序列图模板)
└── examples/
    ├── example_roadmap.mmd (示例路线图)
    ├── example_architecture.mmd (示例架构图)
    └── example_output.md (示例输出)

依赖要求

• Mermaid CLI (mmdc): 必须安装并配置好
• Python 3.8+: 用于运行脚本
• Puppeteer配置: 用于解决mmdc沙箱问题

安装和配置

1. 安装Mermaid CLI

# 全局安装
npm install -g @mermaid-js/mermaid-cli

# 或者使用npx
npx @mermaid-js/mermaid-cli

2. 验证安装

mmdc --version
# 应该显示版本号，如：11.12.0

3. 解决沙箱问题

创建Puppeteer配置文件：

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

使用方法

基本使用流程

1. 创建Mermaid图表定义文件

python scripts/create_mermaid.py --type roadmap --title "技术路线图" --output roadmap.mmd

2. 转换为PNG图片

python scripts/convert_mermaid.py --input roadmap.mmd --output roadmap.png

3. 插入到Markdown文件

python scripts/insert_to_md.py --md-file report.md --image roadmap.png --placeholder "[ROADMAP]"

完整示例

示例1: 创建技术路线图

# 1. 创建路线图定义
python scripts/create_mermaid.py \
  --type roadmap \
  --title "AI开发技术路线图" \
  --phases "2024 Q1:基础研究,2024 Q2:原型开发,2024 Q3:测试验证,2024 Q4:产品发布" \
  --output ai_roadmap.mmd

# 2. 转换为PNG
python scripts/convert_mermaid.py \
  --input ai_roadmap.mmd \
  --output ai_roadmap.png \
  --width 1200 \
  --height 800

# 3. 插入到Markdown
python scripts/insert_to_md.py \
  --md-file ai_report.md \
  --image ai_roadmap.png \
  --section "## 技术路线图"

示例2: 创建系统架构图

# 1. 创建架构图定义
python scripts/create_mermaid.py \
  --type architecture \
  --title "微服务系统架构" \
  --layers "前端:React,网关:API Gateway,服务:UserService,OrderService,数据:MySQL,Redis" \
  --output architecture.mmd

# 2. 转换为PNG
python scripts/convert_mermaid.py --input architecture.mmd --output architecture.png

# 3. 插入到Markdown
python scripts/insert_to_md.py --md-file design.md --image architecture.png

脚本详细说明

1. create_mermaid.py

创建各种类型的Mermaid图表定义文件。

参数:

• --type: 图表类型 (roadmap, architecture, flowchart, sequence, class, state, gantt, er)
• --title: 图表标题
• --output: 输出文件路径
• 其他类型特定参数

支持的图表类型:

1. roadmap: 技术路线图
2. architecture: 系统架构图
3. flowchart: 流程图
4. sequence: 序列图
5. class: 类图
6. state: 状态图
7. gantt: 甘特图
8. er: ER图

2. convert_mermaid.py

将.mmd文件转换为PNG图片。

参数:

• --input: 输入.mmd文件
• --output: 输出.png文件
• --width: 图片宽度 (默认1200)
• --height: 图片高度 (默认800)
• --theme: 主题 (default, forest, dark, neutral)
• --background: 背景颜色 (默认白色)

3. insert_to_md.py

将PNG图片插入到Markdown文件。

参数:

• --md-file: Markdown文件路径
• --image: 图片文件路径
• --placeholder: 要替换的占位符 (可选)
• --section: 要插入的章节标题 (可选)
• --caption: 图片标题 (可选)
• --position: 插入位置 (before, after, replace)

模板系统

路线图模板 (roadmap.mmd)

%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#007bff', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0056b3', 'lineColor': '#333', 'tertiaryColor': '#f8f9fa'}}}%%
gantt
    title {{TITLE}}
    dateFormat YYYY-MM
    axisFormat %Y年%m月
    
    section 第一阶段
    任务1 :a1, {{START_DATE}}, {{DURATION_1}}
    
    section 第二阶段
    任务2 :after a1, {{DURATION_2}}
    
    section 第三阶段
    任务3 :after a2, {{DURATION_3}}

架构图模板 (architecture.mmd)

graph TB
    subgraph "{{FRONTEND_TITLE}}"
        A[{{FRONTEND_COMPONENT}}]
    end
    
    subgraph "{{API_TITLE}}"
        B[{{API_COMPONENT}}]
    end
    
    subgraph "{{SERVICE_TITLE}}"
        C[{{SERVICE_1}}]
        D[{{SERVICE_2}}]
    end
    
    subgraph "{{DATA_TITLE}}"
        E[({{DATABASE}})]
        F[{{CACHE}}]
    end
    
    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    C --> F
    D --> F

集成到OpenClaw工作流

作为独立技能使用

# 在OpenClaw会话中调用
exec("python /path/to/mermaid-workflow-skill/scripts/create_mermaid.py --type roadmap --output roadmap.mmd")

作为其他技能的组件

# 在其他技能中集成Mermaid图表生成
def generate_technical_report():
    # 1. 创建路线图
    create_mermaid_chart("roadmap", "项目路线图")
    
    # 2. 转换为图片
    convert_to_png("roadmap.mmd", "roadmap.png")
    
    # 3. 插入到报告
    insert_image_to_md("report.md", "roadmap.png", "## 项目路线图")

故障排除

常见问题

1. mmdc命令找不到

# 检查是否安装
which mmdc

# 如果使用npx
npx @mermaid-js/mermaid-cli --version

2. 沙箱错误

Error: Failed to launch the browser process! No usable sandbox!

解决方案: 使用Puppeteer配置文件

mmdc -i input.mmd -o output.png -p puppeteer-config.json

3. 中文显示问题

解决方案: 确保系统安装了中文字体

# Ubuntu/Debian
sudo apt-get install fonts-wqy-zenhei

# 或者在mmdc命令中指定字体
mmdc -i input.mmd -o output.png --fontFamily "WenQuanYi Zen Hei"

4. 图片质量不佳

解决方案: 增加图片尺寸和DPI

mmdc -i input.mmd -o output.png -w 2000 -H 1400 --scale 2

最佳实践

1. 文件命名规范

• 使用有意义的文件名: project_roadmap.mmd, system_architecture.png
• 包含版本信息: v1.0_architecture.mmd
• 使用日期戳: 20240302_roadmap.mmd

2. 版本控制

• 将.mmd文件纳入版本控制
• PNG图片可以忽略（可重新生成）
• 在README中记录图表生成命令

3. 文档化

• 为每个图表添加注释说明
• 在Markdown中提供图表说明文字
• 维护图表变更日志

4. 自动化集成

• 在CI/CD中集成图表生成
• 使用Makefile或脚本自动化流程
• 设置图表生成触发器

扩展功能

批量处理

# 批量转换所有.mmd文件
for file in *.mmd; do
    python scripts/convert_mermaid.py --input "$file" --output "${file%.mmd}.png"
done

监控和日志

# 添加日志记录
import logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

质量检查

# 检查图表语法
def validate_mermaid_syntax(mmd_content):
    # 实现语法检查逻辑
    pass

示例项目

完整工作流示例

# 创建项目目录
mkdir -p my_project/charts
cd my_project

# 1. 创建技术路线图
python ../mermaid-workflow-skill/scripts/create_mermaid.py \
  --type roadmap \
  --title "产品开发路线图" \
  --output charts/product_roadmap.mmd

# 2. 创建系统架构图
python ../mermaid-workflow-skill/scripts/create_mermaid.py \
  --type architecture \
  --title "系统架构" \
  --output charts/system_architecture.mmd

# 3. 转换为PNG
for mmd in charts/*.mmd; do
    python ../mermaid-workflow-skill/scripts/convert_mermaid.py \
      --input "$mmd" \
      --output "${mmd%.mmd}.png"
done

# 4. 创建Markdown报告
cat > report.md << EOF
# 项目报告

## 技术路线图
![产品开发路线图](charts/product_roadmap.png)

## 系统架构
![系统架构图](charts/system_architecture.png)
EOF

# 5. 插入图片（如果需要自动化插入）
python ../mermaid-workflow-skill/scripts/insert_to_md.py \
  --md-file report.md \
  --image charts/product_roadmap.png \
  --section "## 技术路线图"

更新日志

v1.0.0 (2026-03-02)

• 初始版本发布
• 支持8种Mermaid图表类型
• 完整的创建-转换-插入工作流
• 模板系统和示例

贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

许可证

MIT License