SKILL.md — mermaid-canvas#

Mermaid Canvas：将 Mermaid 代码渲染为图片，用浏览器当画布。

版本：v1.0.0 技能名称：mermaid-canvas 触发词： /mermaid、 mermaid图表、 画图、 生成图表

---

一、什么时候用这个技能#

当用户请求以下内容时，使用此技能：

• "画一个流程图"
• "生成时序图"
• "帮我画个架构图"
• "/mermaid"
• "mermaid图表"
• "用 Mermaid 画"
• 以及任何涉及创建图表（流程图、时序图、甘特图等）的请求

---

二、核心能力#

能力说明图表渲染将 Mermaid 代码渲染为 PNG 图片飞书集成直接上传图片到飞书文档零依赖不需要任何 API Key27 种图表支持 Mermaid 11 全部图表类型

---

三、技术方案#

渲染流程#

text

1. 接收 Mermaid 代码
2. 生成临时 HTML（含 Mermaid CDN）
3. Browser navigate 到本地 HTML
4. 等待 Mermaid 渲染完成
5. snapshot 截图
6. 保存为 PNG
7. 可选：feishu_doc_media 上传到飞书

HTML 模板#

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
  <style>
    body { margin: 20px; background: white; }
    pre.mermaid { display: flex; justify-content: center; align-items: center; min-height: 300px; }
  </style>
</head>
<body>
  <pre class="mermaid">
    %% Mermaid 代码在这里
    flowchart LR
    A --> B
  </pre>
  <script>
    mermaid.initialize({ startOnLoad: true, theme: 'default', securityLevel: 'loose' });
  </script>
</body>
</html>

---

四、支持的图表类型（Mermaid 11 全部 27 种）#

类型关键字触发关键词流程图flowchart流程图、flowchart、流程时序图sequenceDiagram时序图、sequence、API图类图classDiagram类图、classDiagram、类状态图stateDiagram状态图、stateDiagram、状态机实体关系图erDiagramER图、erDiagram、实体关系甘特图gantt甘特图、gantt、项目进度饼图pie饼图、pie、比例思维导图mindmap思维导图、mindmap、脑图时间线timeline时间线、timeline用户旅程journey用户旅程、journey架构图architecture架构图、architecture、系统架构Git 图gitGraphgitGraph、Git图象限图quadrantChart象限图、quadrantChartXY 图表xyChartxyChart、XY图需求图requirementDiagram需求图、requirementDiagramC4 图c4DiagramC4图、C4Diagram雷达图radar雷达图、radar桑基图sankey桑基图、sankey、流量图块图block块图、block石川图ishikawa石川图、鱼骨图维恩图venn维恩图、venn树状图treemap树状图、treemapWardley 图wardleywardley图、Wardley事件建模图eventmodeling事件建模、eventmodeling看板图kanban看板、kanban数据包图packet数据包、packet树视图treeView树视图、treeView

---

五、图表类型自动判断规则#

当用户描述不明确时，按以下规则判断：

用户描述判断类型默认关键字"画个流程"流程图flowchart TD"API调用"时序图sequenceDiagram"项目进度"甘特图gantt"占比分布"饼图pie"思路整理"思维导图mindmap"决策流程"流程图flowchart TD"系统结构"架构图architecture"数据库设计"实体关系图erDiagram

---

六、使用示例#

示例 1：流程图#

用户请求：

text

画一个用户登录的流程图

生成的 Mermaid 代码：

markdown

```mermaid
flowchart TD
    A["用户打开APP"] --> B{是否已登录}
    B -->|是| C[进入主页]
    B -->|否| D[显示登录页]
    D --> E[输入账号密码]
    E --> F{验证成功?}
    F -->|是| C
    F -->|否| G[提示错误]
    G --> D
```

渲染结果：PNG 图片

---

示例 2：时序图#

用户请求：

text

生成一个API调用的时序图

生成的 Mermaid 代码：

markdown

```mermaid
sequenceDiagram
    participant 用户
    participant 前端
    participant 后端
    participant 数据库

    用户->>前端: 点击按钮
    前端->>后端: POST /api/login
    后端->>数据库: 查询用户
    数据库-->>后端: 用户数据
    后端-->>前端: JWT Token
    前端-->>用户: 登录成功
```

---

示例 3：甘特图#

用户请求：

text

画一个项目甘特图

生成的 Mermaid 代码：

markdown

```mermaid
gantt
    title 项目进度
    dateFormat YYYY-MM-DD
    section 设计
    需求分析       :a1, 2024-01-01, 7d
    架构设计       :a2, after a1, 5d
    section 开发
    前端开发       :a3, after a2, 14d
    后端开发       :a4, after a2, 14d
    section 测试
    集成测试       :a5, after a3 a4, 7d
    上线部署       :a6, after a5, 3d
```

---

七、安全语法规范#

7.1 节点 ID 安全规则#

禁用词汇（作为节点 ID）：

• end、 subgraph、 graph、 flowchart
• sequenceDiagram、 classDiagram、 stateDiagram

正确做法：

Rendering diagram...

7.2 标签引号规则#

何时使用引号：

• 含空格的标签
• 含特殊字符： (, ), [, ], {, }, :, ;
• 含中文的标签

语法：

Rendering diagram...

---

八、执行脚本#

8.1 渲染函数#

python

# scripts/mermaid_render.py

def render_mermaid_to_png(
    mermaid_code: str,
    output_path: str = "/tmp/mermaid_output.png",
    theme: str = "default"
) -> str:
    """
    将 Mermaid 代码渲染为 PNG

    Args:
        mermaid_code: Mermaid 图表代码
        output_path: 输出图片路径
        theme: Mermaid 主题 (default/dark/base/wind)

    Returns:
        渲染后的图片路径
    """
    pass

8.2 渲染+飞书上传#

python

def render_and_upload_feishu(
    mermaid_code: str,
    doc_id: str
) -> str:
    """
    渲染 Mermaid 并上传到飞书

    Args:
        mermaid_code: Mermaid 图表代码
        doc_id: 飞书文档 ID

    Returns:
        飞书图片 token
    """
    pass

---

九、常见问题#

Q1: 图表不渲染怎么办？#

可能原因：

1. Mermaid 代码语法错误
2. 浏览器未启动
3. CDN 访问超时

解决方案：

1. 在 https://mermaid.live 验证代码语法
2. 检查 OpenClaw browser 状态
3. 等待更长时间让 Mermaid 渲染完成

Q2: 中文显示乱码？#

原因：HTML 编码问题

解决：确保 HTML 使用 meta charset="utf-8"

Q3: 图片显示不完整？#

原因：图表节点太多太复杂

解决：简化图表，或使用 subgraph 分组

Q4: 支持哪些 Mermaid 版本？#

答案：Mermaid 11（最新稳定版）

---

十、文件结构#

text

mermaid-canvas/
├── SKILL.md                          # 本文件
├── scripts/
│   └── mermaid_render.py              # 核心渲染脚本
└── references/
    ├── diagram-patterns.md            # 常用图表模板
    └── syntax-guide.md               # 安全语法规范

---

十一、参考文件#

文件说明references/diagram-patterns.md常用图表类型的代码模板references/syntax-guide.md安全语法规范和最佳实践

---

十二、相关链接#

• Mermaid 官方文档
• Mermaid Live Editor
• Mermaid CDN