mermaid-canvas

Render Mermaid code into PNG images supporting all 27 Mermaid 11 chart types, with optional upload to Feishu docs, requiring no API keys.

xx235300@xx235300

Install

openclaw skills install @xx235300/mermaid-canvas

SKILL.md — mermaid-canvas

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

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

一、什么时候用这个技能

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

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

二、核心能力

能力	说明
图表渲染	将 Mermaid 代码渲染为 PNG 图片
飞书集成	直接上传图片到飞书文档
零依赖	不需要任何 API Key
27 种图表	支持 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、状态机
实体关系图	`erDiagram`	ER图、erDiagram、实体关系
甘特图	`gantt`	甘特图、gantt、项目进度
饼图	`pie`	饼图、pie、比例
思维导图	`mindmap`	思维导图、mindmap、脑图
时间线	`timeline`	时间线、timeline
用户旅程	`journey`	用户旅程、journey
架构图	`architecture`	架构图、architecture、系统架构
Git 图	`gitGraph`	gitGraph、Git图
象限图	`quadrantChart`	象限图、quadrantChart
XY 图表	`xyChart`	xyChart、XY图
需求图	`requirementDiagram`	需求图、requirementDiagram
C4 图	`c4Diagram`	C4图、C4Diagram
雷达图	`radar`	雷达图、radar
桑基图	`sankey`	桑基图、sankey、流量图
块图	`block`	块图、block
石川图	`ishikawa`	石川图、鱼骨图
维恩图	`venn`	维恩图、venn
树状图	`treemap`	树状图、treemap
Wardley 图	`wardley`	wardley图、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: 图表不渲染怎么办？

可能原因：

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

解决方案：

在 https://mermaid.live 验证代码语法
检查 OpenClaw browser 状态
等待更长时间让 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-canvas

Install

SKILL.md — mermaid-canvas

一、什么时候用这个技能

二、核心能力

三、技术方案

渲染流程

HTML 模板

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

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

六、使用示例

示例 1：流程图

示例 2：时序图

示例 3：甘特图

七、安全语法规范

7.1 节点 ID 安全规则

7.2 标签引号规则

八、执行脚本

8.1 渲染函数

8.2 渲染+飞书上传

九、常见问题

Q1: 图表不渲染怎么办？

Q2: 中文显示乱码？

Q3: 图片显示不完整？

Q4: 支持哪些 Mermaid 版本？

十、文件结构

十一、参考文件

十二、相关链接

Related skills