{"skill":{"slug":"mermaid-workflow-skill","displayName":"Mermaid Workflow Skill","summary":"生成Mermaid图表定义文件，调用Mermaid CLI转换为PNG，并将图片链接插入指定Markdown文件位置。","description":"# Mermaid Workflow Skill\n\n## 描述\n按照新的工作流程创建和处理Mermaid图表：先生成Mermaid格式的图表定义文件(.mmd)，然后调用终端命令运行mmdc (Mermaid CLI)将.mmd转换为PNG，最后将图片链接插入Markdown文件对应的位置。\n\n## 激活条件\n当用户需要创建或处理以下类型的图表时激活此技能：\n- 技术路线图\n- 系统架构图\n- 流程图\n- 序列图\n- 类图\n- 状态图\n- 甘特图\n- ER图\n- 以及其他Mermaid支持的图表类型\n\n## 核心工作流程\n1. **创建Mermaid定义文件** (.mmd)\n2. **转换为PNG图片** (使用mmdc CLI)\n3. **插入Markdown文件** (替换占位符或插入到指定位置)\n\n## 文件结构\n```\nmermaid-workflow-skill/\n├── SKILL.md (本文件)\n├── scripts/\n│   ├── create_mermaid.py (创建Mermaid图表)\n│   ├── convert_mermaid.py (转换Mermaid为PNG)\n│   └── insert_to_md.py (插入图片到Markdown)\n├── templates/\n│   ├── roadmap.mmd (技术路线图模板)\n│   ├── architecture.mmd (系统架构图模板)\n│   ├── flowchart.mmd (流程图模板)\n│   └── sequence.mmd (序列图模板)\n└── examples/\n    ├── example_roadmap.mmd (示例路线图)\n    ├── example_architecture.mmd (示例架构图)\n    └── example_output.md (示例输出)\n```\n\n## 依赖要求\n- **Mermaid CLI (mmdc)**: 必须安装并配置好\n- **Python 3.8+**: 用于运行脚本\n- **Puppeteer配置**: 用于解决mmdc沙箱问题\n\n## 安装和配置\n\n### 1. 安装Mermaid CLI\n```bash\n# 全局安装\nnpm install -g @mermaid-js/mermaid-cli\n\n# 或者使用npx\nnpx @mermaid-js/mermaid-cli\n```\n\n### 2. 验证安装\n```bash\nmmdc --version\n# 应该显示版本号，如：11.12.0\n```\n\n### 3. 解决沙箱问题\n创建Puppeteer配置文件：\n```json\n{\n  \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\"]\n}\n```\n\n## 使用方法\n\n### 基本使用流程\n\n#### 1. 创建Mermaid图表定义文件\n```bash\npython scripts/create_mermaid.py --type roadmap --title \"技术路线图\" --output roadmap.mmd\n```\n\n#### 2. 转换为PNG图片\n```bash\npython scripts/convert_mermaid.py --input roadmap.mmd --output roadmap.png\n```\n\n#### 3. 插入到Markdown文件\n```bash\npython scripts/insert_to_md.py --md-file report.md --image roadmap.png --placeholder \"[ROADMAP]\"\n```\n\n### 完整示例\n\n#### 示例1: 创建技术路线图\n```bash\n# 1. 创建路线图定义\npython scripts/create_mermaid.py \\\n  --type roadmap \\\n  --title \"AI开发技术路线图\" \\\n  --phases \"2024 Q1:基础研究,2024 Q2:原型开发,2024 Q3:测试验证,2024 Q4:产品发布\" \\\n  --output ai_roadmap.mmd\n\n# 2. 转换为PNG\npython scripts/convert_mermaid.py \\\n  --input ai_roadmap.mmd \\\n  --output ai_roadmap.png \\\n  --width 1200 \\\n  --height 800\n\n# 3. 插入到Markdown\npython scripts/insert_to_md.py \\\n  --md-file ai_report.md \\\n  --image ai_roadmap.png \\\n  --section \"## 技术路线图\"\n```\n\n#### 示例2: 创建系统架构图\n```bash\n# 1. 创建架构图定义\npython scripts/create_mermaid.py \\\n  --type architecture \\\n  --title \"微服务系统架构\" \\\n  --layers \"前端:React,网关:API Gateway,服务:UserService,OrderService,数据:MySQL,Redis\" \\\n  --output architecture.mmd\n\n# 2. 转换为PNG\npython scripts/convert_mermaid.py --input architecture.mmd --output architecture.png\n\n# 3. 插入到Markdown\npython scripts/insert_to_md.py --md-file design.md --image architecture.png\n```\n\n## 脚本详细说明\n\n### 1. create_mermaid.py\n创建各种类型的Mermaid图表定义文件。\n\n**参数:**\n- `--type`: 图表类型 (roadmap, architecture, flowchart, sequence, class, state, gantt, er)\n- `--title`: 图表标题\n- `--output`: 输出文件路径\n- 其他类型特定参数\n\n**支持的图表类型:**\n1. **roadmap**: 技术路线图\n2. **architecture**: 系统架构图\n3. **flowchart**: 流程图\n4. **sequence**: 序列图\n5. **class**: 类图\n6. **state**: 状态图\n7. **gantt**: 甘特图\n8. **er**: ER图\n\n### 2. convert_mermaid.py\n将.mmd文件转换为PNG图片。\n\n**参数:**\n- `--input`: 输入.mmd文件\n- `--output`: 输出.png文件\n- `--width`: 图片宽度 (默认1200)\n- `--height`: 图片高度 (默认800)\n- `--theme`: 主题 (default, forest, dark, neutral)\n- `--background`: 背景颜色 (默认白色)\n\n### 3. insert_to_md.py\n将PNG图片插入到Markdown文件。\n\n**参数:**\n- `--md-file`: Markdown文件路径\n- `--image`: 图片文件路径\n- `--placeholder`: 要替换的占位符 (可选)\n- `--section`: 要插入的章节标题 (可选)\n- `--caption`: 图片标题 (可选)\n- `--position`: 插入位置 (before, after, replace)\n\n## 模板系统\n\n### 路线图模板 (roadmap.mmd)\n```mermaid\n%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#007bff', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0056b3', 'lineColor': '#333', 'tertiaryColor': '#f8f9fa'}}}%%\ngantt\n    title {{TITLE}}\n    dateFormat YYYY-MM\n    axisFormat %Y年%m月\n    \n    section 第一阶段\n    任务1 :a1, {{START_DATE}}, {{DURATION_1}}\n    \n    section 第二阶段\n    任务2 :after a1, {{DURATION_2}}\n    \n    section 第三阶段\n    任务3 :after a2, {{DURATION_3}}\n```\n\n### 架构图模板 (architecture.mmd)\n```mermaid\ngraph TB\n    subgraph \"{{FRONTEND_TITLE}}\"\n        A[{{FRONTEND_COMPONENT}}]\n    end\n    \n    subgraph \"{{API_TITLE}}\"\n        B[{{API_COMPONENT}}]\n    end\n    \n    subgraph \"{{SERVICE_TITLE}}\"\n        C[{{SERVICE_1}}]\n        D[{{SERVICE_2}}]\n    end\n    \n    subgraph \"{{DATA_TITLE}}\"\n        E[({{DATABASE}})]\n        F[{{CACHE}}]\n    end\n    \n    A --> B\n    B --> C\n    B --> D\n    C --> E\n    D --> E\n    C --> F\n    D --> F\n```\n\n## 集成到OpenClaw工作流\n\n### 作为独立技能使用\n```python\n# 在OpenClaw会话中调用\nexec(\"python /path/to/mermaid-workflow-skill/scripts/create_mermaid.py --type roadmap --output roadmap.mmd\")\n```\n\n### 作为其他技能的组件\n```python\n# 在其他技能中集成Mermaid图表生成\ndef generate_technical_report():\n    # 1. 创建路线图\n    create_mermaid_chart(\"roadmap\", \"项目路线图\")\n    \n    # 2. 转换为图片\n    convert_to_png(\"roadmap.mmd\", \"roadmap.png\")\n    \n    # 3. 插入到报告\n    insert_image_to_md(\"report.md\", \"roadmap.png\", \"## 项目路线图\")\n```\n\n## 故障排除\n\n### 常见问题\n\n#### 1. mmdc命令找不到\n```bash\n# 检查是否安装\nwhich mmdc\n\n# 如果使用npx\nnpx @mermaid-js/mermaid-cli --version\n```\n\n#### 2. 沙箱错误\n```\nError: Failed to launch the browser process! No usable sandbox!\n```\n**解决方案:** 使用Puppeteer配置文件\n```bash\nmmdc -i input.mmd -o output.png -p puppeteer-config.json\n```\n\n#### 3. 中文显示问题\n**解决方案:** 确保系统安装了中文字体\n```bash\n# Ubuntu/Debian\nsudo apt-get install fonts-wqy-zenhei\n\n# 或者在mmdc命令中指定字体\nmmdc -i input.mmd -o output.png --fontFamily \"WenQuanYi Zen Hei\"\n```\n\n#### 4. 图片质量不佳\n**解决方案:** 增加图片尺寸和DPI\n```bash\nmmdc -i input.mmd -o output.png -w 2000 -H 1400 --scale 2\n```\n\n## 最佳实践\n\n### 1. 文件命名规范\n- 使用有意义的文件名: `project_roadmap.mmd`, `system_architecture.png`\n- 包含版本信息: `v1.0_architecture.mmd`\n- 使用日期戳: `20240302_roadmap.mmd`\n\n### 2. 版本控制\n- 将.mmd文件纳入版本控制\n- PNG图片可以忽略（可重新生成）\n- 在README中记录图表生成命令\n\n### 3. 文档化\n- 为每个图表添加注释说明\n- 在Markdown中提供图表说明文字\n- 维护图表变更日志\n\n### 4. 自动化集成\n- 在CI/CD中集成图表生成\n- 使用Makefile或脚本自动化流程\n- 设置图表生成触发器\n\n## 扩展功能\n\n### 批量处理\n```bash\n# 批量转换所有.mmd文件\nfor file in *.mmd; do\n    python scripts/convert_mermaid.py --input \"$file\" --output \"${file%.mmd}.png\"\ndone\n```\n\n### 监控和日志\n```python\n# 添加日志记录\nimport logging\nlogging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')\n```\n\n### 质量检查\n```python\n# 检查图表语法\ndef validate_mermaid_syntax(mmd_content):\n    # 实现语法检查逻辑\n    pass\n```\n\n## 示例项目\n\n### 完整工作流示例\n```bash\n# 创建项目目录\nmkdir -p my_project/charts\ncd my_project\n\n# 1. 创建技术路线图\npython ../mermaid-workflow-skill/scripts/create_mermaid.py \\\n  --type roadmap \\\n  --title \"产品开发路线图\" \\\n  --output charts/product_roadmap.mmd\n\n# 2. 创建系统架构图\npython ../mermaid-workflow-skill/scripts/create_mermaid.py \\\n  --type architecture \\\n  --title \"系统架构\" \\\n  --output charts/system_architecture.mmd\n\n# 3. 转换为PNG\nfor mmd in charts/*.mmd; do\n    python ../mermaid-workflow-skill/scripts/convert_mermaid.py \\\n      --input \"$mmd\" \\\n      --output \"${mmd%.mmd}.png\"\ndone\n\n# 4. 创建Markdown报告\ncat > report.md << EOF\n# 项目报告\n\n## 技术路线图\n![产品开发路线图](charts/product_roadmap.png)\n\n## 系统架构\n![系统架构图](charts/system_architecture.png)\nEOF\n\n# 5. 插入图片（如果需要自动化插入）\npython ../mermaid-workflow-skill/scripts/insert_to_md.py \\\n  --md-file report.md \\\n  --image charts/product_roadmap.png \\\n  --section \"## 技术路线图\"\n```\n\n## 更新日志\n\n### v1.0.0 (2026-03-02)\n- 初始版本发布\n- 支持8种Mermaid图表类型\n- 完整的创建-转换-插入工作流\n- 模板系统和示例\n\n## 贡献指南\n1. Fork项目\n2. 创建功能分支\n3. 提交更改\n4. 创建Pull Request\n\n## 许可证\nMIT License","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":808,"installsAllTime":30,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1772454720287,"updatedAt":1778994528449},"latestVersion":{"version":"1.0.0","createdAt":1772454720287,"changelog":"mermaid-workflow-skill v1.0.0\n\n- 初始版本发布\n- 支持技术路线图、系统架构图、流程图等8类Mermaid图表自动化处理\n- 覆盖Mermaid定义、PNG转换、Markdown插入的完整工作流\n- 包含丰富的模板与示例，方便快速上手\n- 提供脚本化参数控制及故障排查、最佳实践说明","license":null},"metadata":null,"owner":{"handle":"runmanfm-bit","userId":"s1722w1hxtxc0fbs1ex0kete5h83s190","displayName":"runmanfm-bit","image":"https://avatars.githubusercontent.com/u/240475980?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089737076}}