飞书互动卡片渲染引擎

定位

模板引擎，不是规则手册。 拿到数据 → 选模板 → 填内容 → 推送。用户管内容和意图，技能管展示好看。

技能结构

feishu-card-renderer/
├── SKILL.md                  ← 本文档
├── scripts/
│   ├── build_card.py         ← 核心：模板 + 数据 → 卡片 JSON
│   ├── validate_card.py      ← 校验：卡片 JSON 合法性检查
│   └── push_card.py          ← 封装：输出 message 工具调用参数
└── templates/
    ├── __init__.py
    ├── dashboard.py          ← 模板 A：数据看板
    ├── comparison.py         ← 模板 B：对比分析
    ├── text_analysis.py      ← 模板 C：文本分析
    └── notice.py             ← 模板 D：简讯通知

可执行脚本（推荐优先使用）

build_card.py — 卡片构建

# 从 JSON 文件读取数据（推荐，避免 shell 转义问题）
python scripts/build_card.py --template dashboard --data-file ./data.json

# 直接传 JSON 字符串（简单场景）
python scripts/build_card.py --template notice --data '{"title":"通知","body":"内容"}'

# 从 stdin 读取
echo '{"title":"...","rows":[...]}' | python scripts/build_card.py --template dashboard

# 格式化输出
python scripts/build_card.py --template dashboard --data-file ./data.json --pretty

模板名：dashboard | comparison | text_analysis | notice

数据格式见各模板 Python 文件中的 docstring。

validate_card.py — 卡片校验

python scripts/validate_card.py --card-file ./card.json
python scripts/validate_card.py --card '{"schema":"2.0",...}'
cat card.json | python scripts/validate_card.py

校验通过 → {"valid": true, "errors": [], "warnings": []}（exit 0） 校验失败 → {"valid": false, "errors": [...], "warnings": [...]}（exit 1）

校验规则覆盖所有「关键约束」节的踩坑经验，包括：

• note 标签兼容性、date data_type 禁用手法、page_size 范围、options 列格式、markdown heading 禁用等。

push_card.py — 推送封装

python scripts/push_card.py --chat-id oc_xxx --card-file ./card.json

输出标准 message 工具调用 JSON，AI 直接传参即可，无需手动拼 target/channel/card 字段。

推荐工作流

读取数据源 → 结构化数据 → build_card.py → validate_card.py → push_card.py → message 工具

标准调用格式

1. 读取飞书数据源（url: {链接}）。
2. {展示意图，描述需求}。
3. 调用 feishu-card-renderer 渲染并推送卡片到群 chat:{chat_id}。
4. 发完卡片后回复 NO_REPLY，不要输出任何其他文字。

缺参数就问，不猜。

执行流程

确认参数 → 识别来源 → 读取数据 → 选模板 → 构建卡片 → 校验 → 推送 → NO_REPLY
                                              ↑                        ↑
                                    build_card.py              push_card.py
                                              ↓
                                    validate_card.py

数据源识别

按 URL 特征自动路由：

多维表字段自适应（不硬编码列名）：按「名称/负责人/状态/分类/优先级/日期/描述」语义匹配。

展示模板

模板 A：数据看板（结构化行数据）

适用：多维表、任务表、统计表等有明确行列的数据

骨架：

header(title)
→ column_set（概览指标：总数、完成率、待办数等）
→ hr
→ table（明细数据）
→ hr
→ markdown（一句话结论）

概览指标用 column_set 双栏 / 三栏，纯 markdown 文字，不带复杂格式。 明细用 table 组件，状态列用 options 类型带颜色标签。

模板 B：对比分析

适用：两组或多组数据对比、前后变化、差异分析

骨架：

header(title)
→ markdown（背景一句话）
→ hr
→ table（对比明细：列=对比维度）
→ hr
→ markdown（结论）

模板 C：文本分析（非结构化文档）

适用：散文、报告、议论文等无表格的长文

骨架：

header(title)
→ markdown（核心提炼 2-3 句）
→ hr
→ 中间区：有对比用 table，无可提炼为 markdown 块
→ hr
→ markdown（关键引用/佐证）
→ hr
→ markdown（作者意图一句话）

模板 D：简讯 / 通知

适用：纯文字消息、公告、提醒

骨架：

header(title)
→ markdown（正文）
→ markdown（补充/行动指引）

模板选型原则

空白数据 → 卡片只放「📊 暂无数据」→ NO_REPLY。

Table 组件格式

{
  "schema": "2.0",
  "config": { "wide_screen_mode": true },
  "header": {
    "title": { "tag": "plain_text", "content": "表格标题" }
  },
  "body": {
    "elements": [
      {
        "tag": "table",
        "page_size": 10,
        "columns": [
          { "data_type": "text",    "display_name": "列名", "name": "col" },
          { "data_type": "options", "display_name": "状态", "name": "status" }
        ],
        "rows": [
          { "col": "值", "status": [{ "color": "green", "text": "已完成" }] }
        ]
      }
    ]
  }
}

要点：

• 必须包含顶层 "schema": "2.0"，表格组件放在 body.elements中
• page_size有效范围为 1 ~ 10（原 1.0 中可设 15 但超出限制会被截断）
• header_style在 2.0 中不再单独存在，可通过 header.title自定义样式

颜色语义：

关键约束（来自实测踩坑）

推送

message 工具：
  action:  send
  channel: feishu
  target:  chat:{chat_id}
  card:    {完整卡片 JSON（2.0 格式）}

推送成功 → NO_REPLY。不要输出任何其他文字。