feishu-rich-card

Original source / Raw SKILL.md

---
name: feishu-rich-card
description: >
  Send rich interactive cards with embedded images in Feishu group chats.
  Use when reporting progress, sharing analysis results, or presenting any content
  that benefits from mixed text+image layout in Feishu.
  Combines SVG UI templates (or matplotlib/PIL charts) with Feishu Card Kit API.
---

# Feishu Rich Card — 飞书图文混排卡片

在飞书群聊中发送**图文并茂**的交互式卡片，用于汇报进展、展示分析结果、项目状态等。

## When to Use

- 汇报任务进展、项目状态
- 展示数据分析结果（图表 + 解读）
- 发送研究简报、阶段性成果
- 任何需要图文混排的飞书消息

## Architecture

```
生成图片(SVG→PNG / matplotlib / PIL)
        ↓
上传图片到飞书 → 获取 image_key
        ↓
构造 Card JSON (schema 2.0) → 嵌入 img 元素 + markdown 元素
        ↓
调用飞书 API 发送 interactive 消息
```

## Workflow

### Step 1: Prepare Images

图片来源可以是：
- **SVG UI 模板** → 用 `svg-ui-templates` skill 生成 SVG → cairosvg 转 PNG
- **matplotlib/seaborn** → 直接 savefig 为 PNG
- **PIL/Pillow** → 程序化生成图片
- **已有文件** → 直接使用本地 PNG/JPG

### Step 2: Upload & Send

使用 `references/send_card.py` 中的辅助函数：

```python
# 完整用法参见 references/send_card.py
from send_card import FeishuCardSender

sender = FeishuCardSender()  # 自动读取 openclaw.json 凭证

# 发送图文卡片
sender.send_rich_card(
    chat_id="oc_xxx",
    title="📊 分析报告",
    elements=[
        {"type": "markdown", "content": "## 结果摘要\n\n发现 **3 个**显著差异基因"},
        {"type": "image", "path": "/tmp/volcano_plot.png", "alt": "火山图"},
        {"type": "markdown", "content": "> Gene X: FC=2.5, p<0.001"},
        {"type": "hr"},
        {"type": "image", "path": "/tmp/heatmap.png", "alt": "热图"},
        {"type": "markdown", "content": "**结论：** 样本间差异显著，建议进一步验证。"},
    ],
    header_template="blue"  # blue/indigo/green/red/purple/violet/wathet/turquoise/yellow/grey
)
```

### Step 3: Quick One-liner (for simple cases)

```python
sender.send_image_report(
    chat_id="oc_xxx",
    title="🧬 单细胞分析完成",
    intro="UMAP 降维完成，共识别 12 个细胞群：",
    image_path="/tmp/umap.png",
    conclusion="Cluster 5 为目标细胞群，marker: CD8A, GZMB, PRF1",
    header_template="indigo"
)
```

## Card Elements Reference

| Element | Tag | 说明 |
|---------|-----|------|
| **Markdown** | `markdown` | 支持加粗、斜体、链接、列表、引用块、代码块 |
| **Image** | `img` | 需要 `image_key`（上传后获取） |
| **Divider** | `hr` | 水平分割线 |
| **Column Set** | `column_set` | 多列并排布局 |
| **Note** | `note` | 底部灰色备注 |

## Header Templates (颜色)

`blue` `wathet` `turquoise` `green` `yellow` `orange` `red` `carmine` `violet` `purple` `indigo` `grey`

## Key Rules

1. **图片必须先上传**到飞书获取 `image_key`，不能用 URL
2. **Card schema 必须是 `"2.0"`**
3. **每张卡片最多 50 个元素**
4. 图片建议宽度 600-1200px，飞书会自动缩放
5. markdown 中**不能嵌入图片**，图片必须是独立的 `img` 元素
6. 发送后 OpenClaw 的正常回复会重复，用 `NO_REPLY` 避免

## Integration with SVG UI Templates

当需要专业级可视化时，结合 `svg-ui-templates` skill：

```bash
# 1. 生成 SVG（用模板或自定义）
# 2. 转 PNG
python3 -c "import cairosvg; cairosvg.svg2png(url='report.svg', write_to='report.png', output_width=2400)"
# 3. 用本 skill 上传并发送卡片
```

## Default Chat ID

通过环境变量配置：`FEISHU_DEFAULT_CHAT_ID`（在 `.env` 中设置）


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/send_card.py

```python
#!/usr/bin/env python3
"""
Feishu Rich Card Sender — 飞书图文混排卡片发送工具

Usage:
    from send_card import FeishuCardSender
    sender = FeishuCardSender()
    sender.send_rich_card(chat_id, title, elements)

Or standalone:
    python3 send_card.py --chat oc_xxx --title "Report" --image /tmp/plot.png --text "Done!"
"""

import json
import os
import sys
import requests
from pathlib import Path
from typing import Optional

# ─── Config ──────────────────────────────────────────────────────────────

OPENCLAW_CONFIG = Path.home() / ".openclaw" / "openclaw.json"
DEFAULT_CHAT_ID = os.environ.get("FEISHU_DEFAULT_CHAT_ID", "")

# ─── Token Cache ─────────────────────────────────────────────────────────

_token_cache: dict = {}


def _get_credentials() -> dict:
    """Read Feishu appId/appSecret from openclaw.json."""
    with open(OPENCLAW_CONFIG) as f:
        cfg = json.load(f)
    feishu = cfg.get("channels", {}).get("feishu", {})
    # Check accounts first, then top-level
    accounts = feishu.get("accounts", {})
    if accounts:
        first = next(iter(accounts.values()))
        return {
            "app_id": first.get("appId", feishu.get("appId")),
            "app_secret": first.get("appSecret", feishu.get("appSecret")),
            "domain": first.get("domain", feishu.get("domain", "feishu")),
        }
    return {
        "app_id": feishu.get("appId"),
        "app_secret": feishu.get("appSecret"),
        "domain": feishu.get("domain", "feishu"),
    }


def _api_base(domain: str = "feishu") -> str:
    if domain == "lark":
        return "https://open.larksuite.com/open-apis"
    return "https://open.feishu.cn/open-apis"


def _get_token(creds: dict) -> str:
    """Get or refresh tenant access token."""
    import time

    cache_key = creds["app_id"]
    cached = _token_cache.get(cache_key)
    if cached and cached["expires_at"] > time.time() + 60:
        return cached["token"]

    base = _api_base(creds.get("domain", "feishu"))
    resp = requests.post(
        f"{base}/auth/v3/tenant_access_token/internal",
        json={"app_id": creds["app_id"], "app_secret": creds["app_secret"]},
    )
    data = resp.json()
    if data.get("code") != 0:
        raise RuntimeError(f"Token error: {data.get('msg')}")

    token = data["tenant_access_token"]
    _token_cache[cache_key] = {
        "token": token,
        "expires_at": time.time() + data.get("expire", 7200),
    }
    return token


# ─── Core Functions ──────────────────────────────────────────────────────


class FeishuCardSender:
    def __init__(self, creds: Optional[dict] = None):
        self.creds = creds or _get_credentials()
        self.base = _api_base(self.creds.get("domain", "feishu"))

    @property
    def token(self) -> str:
        return _get_token(self.creds)

    def upload_image(self, image_path: str) -> str:
        """Upload a local image file and return image_key."""
        with open(image_path, "rb") as f:
            resp = requests.post(
                f"{self.base}/im/v1/images",
                headers={"Authorization": f"Bearer {self.token}"},
                data={"image_type": "message"},
                files={"image": (Path(image_path).name, f, "image/png")},
            )
        data = resp.json()
        if data.get("code") != 0:
            raise RuntimeError(f"Image upload failed: {data.get('msg')}")
        return data["data"]["image_key"]

    def send_rich_card(
        self,
        chat_id: str,
        title: str,
        elements: list[dict],
        header_template: str = "blue",
        reply_to: Optional[str] = None,
    ) -> dict:
        """
        Send a rich card with mixed text and images.

        elements: list of dicts, each with:
          - {"type": "markdown", "content": "**bold** text"}
          - {"type": "image", "path": "/tmp/img.png", "alt": "description"}
          - {"type": "image_key", "key": "img_v3_xxx", "alt": "description"}
          - {"type": "hr"}
          - {"type": "note", "content": "footer text"}
          - {"type": "column_set", "columns": [...]}  # advanced
        """
        card_elements = []
        for elem in elements:
            t = elem.get("type", "")
            if t == "markdown":
                card_elements.append({"tag": "markdown", "content": elem["content"]})
            elif t == "image":
                image_key = self.upload_image(elem["path"])
                card_elements.append(
                    {
                        "tag": "img",
                        "img_key": image_key,
                        "alt": {"tag": "plain_text", "content": elem.get("alt", "")},
                    }
                )
            elif t == "image_key":
                card_elements.append(
                    {
                        "tag": "img",
                        "img_key": elem["key"],
                        "alt": {"tag": "plain_text", "content": elem.get("alt", "")},
                    }
                )
            elif t == "hr":
                card_elements.append({"tag": "hr"})
            elif t == "note":
                card_elements.append(
                    {
                        "tag": "note",
                        "elements": [
                            {"tag": "plain_text", "content": elem["content"]}
                        ],
                    }
                )
            else:
                print(f"Warning: unknown element type '{t}', skipping", file=sys.stderr)

        card = {
            "schema": "2.0",
            "config": {"wide_screen_mode": True},
            "header": {
                "title": {"tag": "plain_text", "content": title},
                "template": header_template,
            },
            "body": {"elements": card_elements},
        }

        payload = {
            "receive_id": chat_id,
            "msg_type": "interactive",
            "content": json.dumps(card, ensure_ascii=False),
        }

        if reply_to:
            resp = requests.post(
                f"{self.base}/im/v1/messages/{reply_to}/reply",
                headers={
                    "Authorization": f"Bearer {self.token}",
                    "Content-Type": "application/json",
                },
                json={"msg_type": "interactive", "content": json.dumps(card, ensure_ascii=False)},
            )
        else:
            resp = requests.post(
                f"{self.base}/im/v1/messages",
                headers={
                    "Authorization": f"Bearer {self.token}",
                    "Content-Type": "application/json",
                },
                params={"receive_id_type": "chat_id"},
                json=payload,
            )

        data = resp.json()
        if data.get("code") != 0:
            raise RuntimeError(f"Send card failed: {data.get('msg')}")
        return data

    def send_image_report(
        self,
        chat_id: str,
        title: str,
        image_path: str,
        intro: str = "",
        conclusion: str = "",
        header_template: str = "blue",
    ) -> dict:
        """Quick helper: send a single-image report card."""
        elements = []
        if intro:
            elements.append({"type": "markdown", "content": intro})
        elements.append({"type": "image", "path": image_path, "alt": title})
        if conclusion:
            elements.append({"type": "markdown", "content": conclusion})
        return self.send_rich_card(chat_id, title, elements, header_template)

    def send_progress_report(
        self,
        chat_id: str,
        title: str,
        sections: list[dict],
        header_template: str = "indigo",
    ) -> dict:
        """
        Send a structured progress report.

        sections: list of dicts:
          - {"heading": "...", "body": "...", "image": "/path/to/img.png" (optional)}
        """
        elements = []
        for i, sec in enumerate(sections):
            if i > 0:
                elements.append({"type": "hr"})
            heading = sec.get("heading", "")
            body = sec.get("body", "")
            md = ""
            if heading:
                md += f"## {heading}\n\n"
            if body:
                md += body
            if md:
                elements.append({"type": "markdown", "content": md})
            if sec.get("image"):
                elements.append(
                    {"type": "image", "path": sec["image"], "alt": heading or "image"}
                )
        return self.send_rich_card(chat_id, title, elements, header_template)


# ─── CLI ─────────────────────────────────────────────────────────────────

if __name__ == "__main__":
    import argparse

    parser = argparse.ArgumentParser(description="Send Feishu rich card")
    parser.add_argument("--chat", default=DEFAULT_CHAT_ID, help="Chat ID")
    parser.add_argument("--title", required=True, help="Card title")
    parser.add_argument("--image", action="append", help="Image path(s)")
    parser.add_argument("--text", action="append", help="Text section(s)")
    parser.add_argument("--template", default="blue", help="Header color template")
    args = parser.parse_args()

    sender = FeishuCardSender()
    elements = []
    texts = args.text or []
    images = args.image or []

    # Interleave text and images
    max_len = max(len(texts), len(images))
    for i in range(max_len):
        if i < len(texts):
            elements.append({"type": "markdown", "content": texts[i]})
        if i < len(images):
            elements.append({"type": "image", "path": images[i], "alt": f"Image {i+1}"})

    result = sender.send_rich_card(args.chat, args.title, elements, args.template)
    print(f"✅ Sent! message_id={result['data']['message_id']}")

```