SKILL.md — mermaid-canvas
Mermaid Canvas：将 Mermaid 代码渲染为图片，用浏览器当画布。 版本：v1.0.0 技能名称：mermaid-canvas 触发词：/mermaid、mermaid图表、画图、生成图表
一、什么时候用这个技能
当用户请求以下内容时，使用此技能：
- "画一个流程图"
- "生成时序图"
- "帮我画个架构图"
- "/mermaid"
- "mermaid图表"
- "用 Mermaid 画"
- 以及任何涉及创建图表（流程图、时序图、甘特图等）的请求
二、核心能力
| 能力 | 说明 |
|---|---|
| 图表渲染 | 将 Mermaid 代码渲染为 PNG 图片 |
| 飞书集成 | 直接上传图片到飞书文档 |
| 零依赖 | 不需要任何 API Key |
| 27 种图表 | 支持 Mermaid 11 全部图表类型 |
三、技术方案
渲染流程
1. 接收 Mermaid 代码
2. 生成临时 HTML（含 Mermaid CDN）
3. Browser navigate 到本地 HTML
4. 等待 Mermaid 渲染完成
5. snapshot 截图
6. 保存为 PNG
7. 可选：feishu_doc_media 上传到飞书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：流程图
用户请求：
画一个用户登录的流程图生成的 Mermaid 代码：
flowchart TD A["用户打开APP"] --> B{是否已登录} B -->|是| C[进入主页] B -->|否| D[显示登录页] D --> E[输入账号密码] E --> F{验证成功?} F -->|是| C F -->|否| G[提示错误] G --> D
渲染结果：PNG 图片
示例 2：时序图
用户请求：
生成一个API调用的时序图生成的 Mermaid 代码：
sequenceDiagram participant 用户 participant 前端 participant 后端 participant 数据库
用户->>前端: 点击按钮 前端->>后端: POST /api/login 后端->>数据库: 查询用户 数据库-->>后端: 用户数据 后端-->>前端: JWT Token 前端-->>用户: 登录成功
示例 3：甘特图
用户请求：
画一个项目甘特图生成的 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、flowchartsequenceDiagram、classDiagram、stateDiagram
正确做法：
%% 错误 ❌
flowchart
end --> start
%% 正确 ✅
flowchart
EndState --> StartState7.2 标签引号规则
何时使用引号：
- 含空格的标签
- 含特殊字符：
(,),[,],{,},:,; - 含中文的标签
语法：
flowchart LR
A["带空格的标签"] --> B["带(括号)的标签"]
C["中文标签"] --> D["多字:标签"]八、执行脚本
8.1 渲染函数
# 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:
渲染后的图片路径
"""
pass8.2 渲染+飞书上传
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（最新稳定版）
十、文件结构
mermaid-canvas/
├── SKILL.md # 本文件
├── scripts/
│ └── mermaid_render.py # 核心渲染脚本
└── references/
├── diagram-patterns.md # 常用图表模板
└── syntax-guide.md # 安全语法规范十一、参考文件
| 文件 | 说明 |
|---|---|
references/diagram-patterns.md | 常用图表类型的代码模板 |
references/syntax-guide.md | 安全语法规范和最佳实践 |