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

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

一、什么时候用这个技能

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

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

二、核心能力

三、技术方案

渲染流程

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

HTML 模板

  
  
  


  
    %% Mermaid 代码在这里
    flowchart LR
    A --> B
  
  

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

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

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

六、使用示例

示例 1：流程图

用户请求：

画一个用户登录的流程图

生成的 Mermaid 代码：

渲染结果：PNG 图片

示例 2：时序图

用户请求：

生成一个API调用的时序图

生成的 Mermaid 代码：

示例 3：甘特图

用户请求：

画一个项目甘特图

生成的 Mermaid 代码：

七、安全语法规范

7.1 节点 ID 安全规则

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

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

正确做法：

%% 错误 ❌
flowchart
    end --> start
%% 正确 ✅
flowchart
    EndState --> StartState

7.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:
        渲染后的图片路径
    """
    pass

8.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               # 安全语法规范

十一、参考文件

十二、相关链接

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