| 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 — 数据不足，已回复文字询问用户
