feishu-card

# 飞书卡片构建助手

## 概述

这个 skill 帮助你根据需求正确构造飞书卡片（消息卡片）的 JSON 结构。**默认使用卡片 JSON 2.0 版本**，支持各种卡片组件、布局和交互功能。

## 使用场景

- 需要创建飞书机器人发送的消息卡片
- 需要构建包含按钮、表单等交互元素的卡片
- 需要设计复杂布局的飞书通知卡片
- 需要生成符合飞书规范的卡片 JSON schema

## 工作流程

### 1. 确认需求

首先询问用户以下信息：
- 卡片的用途是什么？（通知、审批、表单、数据展示等）
- 需要哪些内容元素？（标题、文本、图片、按钮、表格等）
- 是否需要交互功能？（按钮点击、表单输入、选择器等）
- 卡片的目标平台？（飞书/Lark）

### 2. 选择组件

根据需求选择合适的组件，参考 `references/components.md`：

**容器组件**：用于布局
- `column_set` - 多列布局
- `form` - 表单容器
- `interactive` - 交互容器
- `collapsible_panel` - 折叠面板

**内容组件**：用于展示
- `div` / `markdown` - 文本内容
- `img` / `multi_image_layout` - 图片展示
- `table` - 表格数据
- `chart` - 图表可视化
- `person` / `person_list` - 人员展示

**交互组件**：用于用户操作
- `button` - 按钮
- `input` - 输入框
- `select_static` / `multi_select_static` - 下拉选择
- `date_picker` / `picker_time` / `picker_datetime` - 日期时间选择
- `select_person` / `multi_select_person` - 人员选择
- `checker` - 勾选器
- `image_picker` - 图片上传

### 3. 构建卡片结构

使用卡片 JSON 2.0 结构（带 `"schema": "2.0"`），参考 `references/card-structure.md`。

### 4. 生成 JSON

根据用户需求生成完整的 JSON 文件，确保：
- 符合飞书卡片 schema 规范
- 包含所有必要字段
- JSON 格式正确可用

## 卡片 JSON 2.0 基础结构

```json
{
  "schema": "2.0",
  "config": {
    "wide_screen_mode": true,
    "enable_forward": true
  },
  "header": {
    "title": {
      "tag": "plain_text",
      "content": "卡片标题"
    },
    "subtitle": {
      "tag": "plain_text",
      "content": "副标题"
    },
    "template": "blue"
  },
  "body": {
    "elements": [
      // 内容组件
    ]
  }
}
```

## Schema 2.0 常见坑点

> **重要**：以下是通过 API 发送卡片时的实测结果，搭建工具预览可能不会报错，但 API 会拒绝。

### 0. 交互容器 tag 值（极易出错！）

> **血泪教训**：交互容器的 tag 是 `interactive_container`，**不是** `interactive`！

| 写法 | 结果 |
|------|------|
| `"tag": "interactive"` | **API 报错**: `not support tag: interactive` |
| `"tag": "interactive_container"` | 正确 |

**错误示例**：
```json
{
  "tag": "interactive",  // ❌ 错误！会导致 API 拒绝
  "elements": [...]
}
```

**正确示例**：
```json
{
  "tag": "interactive_container",  // ✅ 正确
  "width": "fill",
  "behaviors": [{ "type": "open_url", "default_url": "https://