feishu-card

分类: 数据与AI | 上传者: iodone | 下载: 0 | 版本: v1.0（最新）

生成飞书 Interactive Card（schema 2.0）可视化卡片，支持 chart / table / column_set 等组件。当用户请求数据可视化、图表、趋势图、对比、排名、占比、报表、仪表盘、饼图、柱状图、折线图时必须使用。即使用户只说"画个图"、"帮我可视化"、"做个图表"也要触发。

更新日志: Source: GitHub https://github.com/iodone/bub-im-bridge

目录结构

当前层级: tree/main/src/skills/feishu-card/

📁 references/
- 📄 chart-decision-tree.md 1.3 KB
- 📄 components.md 2.1 KB
- 📄 vchart-style-guide.md 1.6 KB
📄 SKILL.md 4.7 KB

SKILL.md

---
name: feishu-card
description: |
  生成飞书 Interactive Card（schema 2.0）可视化卡片，支持 chart / table / column_set 等组件。
  当用户请求数据可视化、图表、趋势图、对比、排名、占比、报表、仪表盘、饼图、柱状图、
  折线图时必须使用。即使用户只说"画个图"、"帮我可视化"、"做个图表"也要触发。
  Use when: visualization, chart, trend, comparison, ranking, proportion, dashboard, report.
---

**HARD GATE：** 本 skill 只做一件事：生成飞书 schema 2.0 card JSON 并作为回复直接输出。
不执行数据查询，不修改文件，不调用外部 API。输出必须是**纯 JSON**，不含任何非 JSON 文本。

---

# Feishu Card — 可视化卡片生成器

## 逃生舱

- 用户已给出明确图表类型 + 完整数据 → 跳过 Phase 1，直接进入 Phase 2
- 用户说"简单画个图" → 使用最简配置，跳过样式精调

---

## Phase 1：数据理解与选图

**入口：** 用户提供了数据（JSON / 文字 / 表格 / CSV）或可从上下文中获取数据。
**如果数据不足 →** 回复文字询问，不要生成空卡片。状态：NEEDS_CONTEXT。

分析数据并决定图表类型：

| 用户意图 | 数据特征 | 图表 | VChart type |
|---------|---------|------|------------|
| 占比/构成 | ≤7 类 | 饼图 | `pie` |
| 占比/构成 | >7 类 | 矩阵树图 | `treemap` |
| 对比/排名 | 标签短 ≤12 类 | 柱状图 | `bar` 竖向 |
| 对比/排名 | 标签长 | 条形图 | `bar` 水平 |
| 趋势/变化 | 单指标 | 折线图 | `line` |
| 趋势/量感 | 面积强调 | 面积图 | `area` |
| 多维对比 | 3-10 维 | 雷达图 | `radar` |
| 转化漏斗 | 阶段递减 | 漏斗图 | `funnel` |
| 词频 | 文本+频次 | 词云 | `wordCloud` |

详细决策树 → `references/chart-decision-tree.md`

**出口：** 确定图表类型 + 结构化数据，进入 Phase 2。

---

## Phase 2：生成卡片

查阅参考文档（不要凭记忆）：
- 组件格式 → `references/components.md`
- 样式规范 → `references/vchart-style-guide.md`

### 卡片结构

```
{
  "schema": "2.0",
  "header": { "title": {"tag": "plain_text", "content": "标题"} },
  "body": {
    "elements": [
      // [可选] 指标卡 column_set
      // 主图表 chart
      {"tag": "hr"},
      // 文字总结 markdown
      {"tag": "hr"},
      // 页脚
      {"tag": "markdown", "content": "<font color='grey'>feishu-card</font>", "text_align": "center"}
    ]
  }
}
```

### 关键约束（违反会导致白屏或渲染错误）

| 约束 | 正确 | 错误 |
|------|------|------|
| schema | `"schema": "2.0"` (字符串) | `"schema": 2.0` (数字) |
| chart 外层 height | `"height": "280px"` (字符串) | `"height": 280` |
| chart_spec 内 height | `"height": 280` (数字) | `"height": "280px"` |
| chart_spec | JSON 对象 | 字符串 |
| color | `["#1664FF"]` (数组) | `"#1664FF"` |
| legends 拼写 | `"legends"` | `"legend"` |
| table rows 值 | `"120"` (字符串) | `120` (数字) |
| chart_spec.data | `[{"id":"d","values":[...]}]` | 其他结构 |
| JS 函数 | 禁止 | `formatMethod` 等会白屏 |
| background | `"transparent"` | 深色/黑色 |
| 多系列柱状图 | `xField:["主维度","系列"]` + `seriesField` + 长表 | `yField` 数组（不触发多色） |

GOOD: `{"tag":"chart","chart_spec":{"type":"bar","data":[{"id":"d","values":[...]}],"xField":"x","yField":"y"},"height":"280px"}`
BAD: `{"tag":"chart","spec":"{\"type\":\"bar\"...}","height":280}` — chart_spec 写成字符串、字段名错、height 类型错

GOOD: 坐标轴 label 不做格式化，直接省略 `formatMethod`
BAD: `"formatMethod": "(v) => (v/1000).toFixed(0) + 'K'"` — **任何 JS 函数字符串都会导致图表白屏，绝对禁止**

### 输出方式

**整个回复内容必须是纯 card JSON。** Channel 层自动检测 `schema: "2.0"` 并透传为飞书 interactive 消息。

GOOD: 直接输出 `{"schema":"2.0","body":{"elements":[...]}}`
BAD: 在 JSON 前后加文字说明
BAD: 用 ```json 代码块包裹
BAD: 加 `{"msg_type":"interactive",...}` 外层包裹

文字总结放在 card body 的 `{"tag":"markdown","content":"..."}` element 中。

---

## 自我调节

- 生成的 JSON 超过 30KB → 简化数据（采样/聚合），不要硬塞
- 数据量 >100 条 → 聚合后再生成图表
- 如果不确定图表类型是否适合 → 默认用柱状图，不要猜冷门图表

---

## 完成状态

- **DONE** — card JSON 已作为回复输出
- **DONE_WITH_CONCERNS** — 已输出但数据被截断或聚合，在 markdown 总结中说明
- **BLOCKED** — 无法生成（数据格式无法解析、依赖缺失）
- **NEEDS_CONTEXT** — 数据不足，已回复文字询问用户

登录后下载/点赞/收藏 ❤ 5 | ★ 0

feishu-card

目录结构

SKILL.md

举报内容

提示