📖 技能介紹

# mermaid-to-feishu - Mermaid 圖表轉圖片傳送技能（Canvas 渲染版）

📋 技能描述

功能： 自動將 Mermaid 程式碼通過 Canvas/Browser 渲染為 PNG 圖片併發送到飛書對話

用途： - 當回答中包含 Mermaid 圖表時，自動渲染為圖片 - 使用 Browser/Canvas 渲染 + 截圖方案（飛書不支援直接渲染 Mermaid） - 使用飛書 API 上傳圖片併發送 - 替代純文本 Mermaid 程式碼，提供更直觀的視覺體驗

⚠️ 重要： 飛書不支援直接渲染 Mermaid 程式碼塊，必須轉換為圖片！

🎯 觸發條件

自動觸發： - 回答中包含 Mermaid 程式碼塊（```mermaid） - 使用者明確要求"畫圖"、"生成圖表"、"UML 圖" - 解釋複雜流程/架構/關係時

手動觸發： - 使用者說"用圖片展示"、"轉成圖片" - 使用者說"傳送到飛書"

🔧 配置要求

環境變數或配置檔案

方式 1：環境變數（推薦）

export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="your_app_secret_here"
export FEISHU_RECEIVE_ID="ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

方式 2：配置檔案 建立 ~/.agents/skills/mermaid-to-feishu/config.json：

{
  "app_id": "cli_xxxxxxxxxxxxxxxx",
  "app_secret": "your_app_secret_here",
  "receive_id": "ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

依賴工具

方案 A：Browser/Canvas 渲染（推薦）⭐ - ✅ OpenClaw browser 工具 - 渲染 HTML + 截圖 - ✅ Mermaid CDN - 瀏覽器端渲染 - ✅ 無需本地安裝 mermaid-cli

方案 B：mermaid-cli 渲染（傳統方案） - ✅ mmdc (mermaid-cli) - 用於渲染 Mermaid 圖表 - ✅ Python 3.x - 指令碼執行環境 - ✅ requests 庫 - HTTP 請求

安裝 mermaid-cli（可選）：

npm install -g @mermaid-js/mermaid-cli

📄 核心檔案

主指令碼：`send-mermaid.py`

位置： ~/.agents/skills/mermaid-to-feishu/scripts/send-mermaid.py

功能： 1. 接收 Mermaid 程式碼 2. 建立臨時 Markdown 檔案 3. 呼叫 mmdc 渲染為 PNG 4. 上傳到飛書獲取 image_key 5. 傳送圖片訊息到飛書

用法：

python send-mermaid.py "graph LR\n    A --> B"

SKILL.md

位置： ~/.agents/skills/mermaid-to-feishu/SKILL.md

內容： 本檔案，定義技能行為和使用方式

🚀 工作流程

方案 A：Browser/Canvas 渲染（推薦）⭐

flowchart TB
    A[檢測到 Mermaid 程式碼] --> B[建立 HTML 檔案]
    B --> C[Browser navigate 開啟]
    C --> D[Browser snapshot 截圖]
    D --> E[上傳到飛書]
    E --> F[獲取 image_key]
    F --> G[傳送圖片訊息]

    style A fill:#e1f5ff
    style C fill:#ffe1e1
    style G fill:#e1ffe1

核心步驟： 1. 建立 HTML 檔案（含 Mermaid CDN） 2. 使用 browser 工具 navigate 開啟 HTML 3. 使用 browser 工具 snapshot 截圖（JPG/PNG） 4. 使用 feishu-send-file 傳送圖片

方案 B：mermaid-cli 渲染（傳統方案）

flowchart TB
    A[檢測到 Mermaid 程式碼] --> B[提取程式碼]
    B --> C[建立臨時檔案]
    C --> D[mmdc 渲染 PNG]
    D --> E[上傳到飛書]
    E --> F[獲取 image_key]
    F --> G[傳送圖片訊息]
    G --> H[清理臨時檔案]

    style A fill:#e1f5ff
    style D fill:#ffe1e1
    style G fill:#e1ffe1

💡 使用示例

示例 1：自動觸發（Browser 渲染）

使用者問： "解釋一下向量搜尋的工作流程"

阿香回答： 1. 生成 Mermaid 程式碼 2. 建立 HTML 檔案（含 Mermaid CDN） 3. Browser navigate 開啟 + snapshot 截圖 4. 使用 feishu-send-file 傳送圖片到飛書

示例 2：手動觸發

使用者說： "把剛才的流程圖轉成圖片發給我"

小蔥技能站7w4.net發現了升級外掛。

阿香： 1. 提取之前的 Mermaid 程式碼 2. 建立 HTML 並渲染截圖 3. 傳送圖片到飛書

示例 3：Thomas 驗收流程

流程：

阿美驗收 Mermaid 程式碼 → 阿香 Browser 渲染 → 截圖 → 傳送飛書

觸發條件： 當回答中包含 Mermaid 程式碼時

🔍 程式碼示例

Browser 渲染方案（推薦）⭐

HTML 模板：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
  <style>
    body { 
      margin: 0; 
      padding: 40px; 
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      font-family: Arial, sans-serif;
    }
    .container {
      background: white;
      border-radius: 20px;
      padding: 40px;
      box-shadow: 0 20px 60px rgba(0,0,0,0.1);
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="mermaid">
graph TB
    A[開始] --> B[結束]
    </div>
  </div>
  <script>
    mermaid.initialize({ startOnLoad: true });
  </script>
</body>
</html>

OpenClaw 工具呼叫：

// 1. Navigate 開啟 HTML
browser(action="navigate", url="file:///path/to/mermaid.html")

// 2. Snapshot 截圖
browser(action="snapshot", type="png", fullPage=true)

// 3. 傳送飛書
feishu-send-file(filePath="screenshot.png")

Python 指令碼核心邏輯（傳統方案）

import requests
import json
import tempfile
import subprocess

# 配置
APP_ID = "cli_xxx"
APP_SECRET = "xxx"
RECEIVE_ID = "ou_xxx"

def get_token():
    r = requests.post(
        "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
        json={"app_id": APP_ID, "app_secret": APP_SECRET}
    )
    return r.json().get("tenant_access_token")

def mermaid_to_png(mermaid_code):
    # 建立臨時檔案
    with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
        f.write(f"```mermaid\n{mermaid_code}\n```")
        md_file = f.name

    png_file = md_file.replace('.md', '.png')

    # 呼叫 mmdc 渲染
    subprocess.run(['mmdc', '-i', md_file, '-o', png_file, '-b', 'transparent'])

    return png_file

def upload_image(token, image_path):
    with open(image_path, 'rb') as f:
        files = {
            'image': (os.path.basename(image_path), f, 'image/png'),
            'image_type': (None, 'message')
        }
        r = requests.post(
            "https://open.feishu.cn/open-apis/im/v1/images",
            headers={'Authorization': f'Bearer {token}'},
            files=files
        )
        return r.json()['data']['image_key']

def send_image(token, image_key):
    data = {
        'receive_id': RECEIVE_ID,
        'msg_type': 'image',
        'content': json.dumps({'image_key': image_key})
    }
    r = requests.post(
        "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
        headers={'Authorization': f'Bearer {token}'},
        json=data
    )
    return r.json()

📊 Mermaid 圖表型別支援

型別	說明	示例
流程圖	flowchart	工作流程、決策樹
序列圖	sequenceDiagram	互動流程、API 呼叫
類圖	classDiagram	類關係、繼承結構
狀態圖	stateDiagram	狀態轉換、生命週期
實體關係圖	erDiagram	資料模型、資料庫設計
使用者旅程圖	journey	使用者體驗流程
甘特圖	gantt	專案計劃、時間線
餅圖	pie	資料分佈、佔比
思維導圖	mindmap	知識梳理、腦圖
象限圖	quadrantChart	優先順序矩陣、對比分析
時序圖	timeline	時間序列、歷史事件

⚠️ 注意事項

1. 飛書不支援直接渲染 Mermaid ❌

重要： 飛書文件的 Code block 不會自動渲染 Mermaid！

解決方案： - ✅ 使用 Browser/Canvas 渲染成圖片 - ✅ 使用 feishu-send-file 傳送圖片 - ❌ 不要直接插入 Mermaid 程式碼塊

2. Browser 渲染優勢（推薦）⭐

對比 mermaid-cli：

方案	優點	缺點
Browser 渲染	無需安裝、支援 CDN、樣式靈活	需要 Browser 工具
mermaid-cli	本地渲染、離線可用	需要 npm 安裝、字型問題

推薦場景： - ✅ 有 OpenClaw Browser 工具 → 用 Browser 渲染 - ✅ 純本地環境 → 用 mermaid-cli

3. 臨時檔案清理

指令碼會自動清理臨時檔案，但如果中斷可能殘留：

# 手動清理
rm /tmp/tmp*.md /tmp/tmp*.png

2. mmdc 渲染失敗

可能原因： - Mermaid 語法錯誤 - mmdc 未安裝或路徑不對 - 中文字型問題

解決方案：

# 檢查 mmdc
mmdc --version

# 測試渲染
echo '```mermaid\ngraph LR\n    A --> B\n```' > test.md
mmdc -i test.md -o test.png

3. 飛書 API 限制

圖片大小：最大 20MB
格式：PNG/JPG/GIF
頻率：避免短時間大量上傳

🔧 故障排查

問題 1：mmdc 找不到

錯誤： Error rendering mermaid: mmdc not found

解決：

# 檢查安裝
npm list -g @mermaid-js/mermaid-cli

# 重新安裝
npm install -g @mermaid-js/mermaid-cli

# 檢查路徑
which mmdc  # Linux/Mac
where mmdc  # Windows

問題 2：飛書憑證無效

錯誤： Invalid tenant_access_token

解決： 1. 檢查 app_id 和 app_secret 是否正確 2. 確認飛書應用許可權已配置 3. 重新獲取 token

問題 3：receive_id 無效

錯誤： The request you send is not a valid {open_id}

解決： 1. 確認 receive_id 是正確的 open_id 格式 2. open_id 格式：ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（32 位） 3. 從飛書對話 metadata 獲取正確的 open_id

📝 配置檢查清單

使用前確認：

[ ] 已安裝 mermaid-cli (npm install -g @mermaid-js/mermaid-cli)
[ ] 已配置飛書憑證 (app_id, app_secret, receive_id)
[ ] 已測試 mmdc 渲染 (mmdc --version)
[ ] 已測試飛書 API (傳送文本訊息)
[ ] 已測試完整流程 (Mermaid → PNG → 飛書)

🎯 最佳實踐

1. 自動觸發策略

觸發關鍵詞： - "畫個圖"、"生成圖表"、"UML" - "流程圖"、"架構圖"、"時序圖" - "用圖片展示"、"轉成圖片"

不觸發的場景： - 簡單的 Mermaid 示例程式碼 - 使用者明確要求"只要程式碼" - 圖表過於複雜（渲染時間長）

2. 圖片質量最佳化

推薦配置：

mmdc -i input.md -o output.png \
  -b transparent \  # 透明背景
  -w 2000 \         # 寬度 2000px
  -H 2000           # 高度 2000px

3. 錯誤處理

優雅降級： - 如果渲染失敗，返回 Mermaid 程式碼 - 如果上傳失敗，儲存為本地檔案 - 如果傳送失敗，記錄日誌

📞 支援

問題反饋： OpenClaw 社群
文件： ~/.agents/skills/mermaid-to-feishu/README.md

核心檔案： - scripts/send-mermaid.py - 主指令碼 - SKILL.md - 技能定義 - config.json - 配置檔案

阿香 🦞 維護的 Mermaid 轉圖片技能

哼～蝦蝦的圖表渲染可是很厲害的！別小看我！✨

🤖 AI 評測

這個 Skill 的文件寫得比較詳細，配置說明和故障排查都很全面，但質量上有個大遺憾：壓縮包裡缺少最重要的指令碼檔案，只有使用說明沒有實際可用的程式碼，導致功能無法真正使用。文件本身適合作為參考學習材料，但作為可執行 Skill 還需完善。

📊 多維度評分

適應性4.5

規範性4.4

有效性3.9

可靠性3.8

可信度4.7

📁 包含檔案 (3 個)

📄 SKILL.md 10.8 KB

📄 _meta.json 136 B

📄 skill.json 411 B

Mermaid 轉飛書圖片 Canvas 渲染版