feishu-cli-card

---
name: feishu-cli-card
description: >-
license: MIT
---

# 飞书 V2 卡片构造技能

> **职责**：把用户的意图 → 构造出视觉丰富的 **v2** 卡片 JSON，写入 `/tmp/<name>-card.json`，
> 再交给 `feishu-cli msg send --msg-type interactive --content-file` 发送。
>
> **只做 v2**：所有输出必须以 `"schema": "2.0"` 开头，用 `body` 包裹 elements。
> v1 相关迁移见 `references/v2-vs-v1.md`。

## 1. 决策树（30 秒选模板）

```
用户意图 → 推荐模板 → header.template
├─ 通知 / 公告 / 信息同步      → notification.json      → blue
├─ 操作完成 / 构建成功 / 交付   → success-report.json    → green
├─ 告警 / 故障 / 错误           → alert.json             → red / carmine
├─ 审批请求 / 待办 / 确认       → approval.json          → orange
├─ 数据展示 / 报表 / 指标       → data-dashboard.json    → purple / indigo
├─ 长文摘要 / 文章总结 / 多章节 → article-summary.json   → blue / wathet
└─ AI 流式输出 / 生成中         → llm-streaming.json     → blue + streaming_mode
```

**不确定时用 `notification.json` 兜底**（蓝色、结构通用、覆盖度最广）。

用户没说具体是什么场景但内容有结构（多字段/多链接/图表/状态指标）——也优先选卡片而不是纯文本。

## 2. v2 最小可运行骨架

```json
{
  "schema": "2.0",
  "config": {
    "update_multi": true,
    "enable_forward": true,
    "width_mode": "fill"
  },
  "header": {
    "template": "blue",
    "title": { "tag": "plain_text", "content": "标题" },
    "subtitle": { "tag": "plain_text", "content": "可选副标题" }
  },
  "body": {
    "direction": "vertical",
    "vertical_spacing": "medium",
    "elements": [
      { "tag": "markdown", "content": "**正文**\n\n支持完整 CommonMark + `<font>`/`<at>`/`<link>` 等 HTML 标签" }
    ]
  }
}
```

**四大必备块**：
1. `schema: "2.0"` — 顶层声明，v2 必须
2. `config` — 全局行为：`update_multi` v2 只支持 `true`；`width_mode` 用 `fill`/`compact`/省略（默认 600px）
3. `header` — 标题区：`template` 定主题色，`title` 必填，`subtitle` 可选
4. `body.elements` — 组件数组，按顺序从上到下渲染

## 3. 工作流（6 步）

1. **选模板**：按决策树确定 `templates/<name>.json`，Read 进来作为起点
2. **填内容**：替换所有 `__PLACEHOLDER__` 标记位（标题、字段值、URL、数据、人员 ID）
3. **选配色**：`header.template` 按场景挑（参见 `references/design.md` 配色矩阵），markdown 内 `<font>` 强调色不超过 3 种
4. **校验**：
   - `python -m json.tool /tmp/xxx-card.json` 过 JSON 解析
   - 检查无 v2 禁用字段（见第 6 节禁区）
5. **落盘**：Write 到 `/tmp/<name>-card.json`（复用已有路径避免污染）
6. **发送**：
   ```bash
   feishu-cli msg send \
     --receive-id-type email \
     --receive-id user@example.com \
     --msg-type interactive \
     --content-file /tmp/<name>-card.json
   ```
   成功返回 `message_id: om_xxx`。

## 4. 组件速查矩阵

**展示类**（只看、不交互）：

| tag | 用途 | 典型属性 |
|-----|------|---------|
| `markdown` | 富文本正文 | `content` + `text_size` + `text_align` + `icon` |
| `div` | 带 fields 的多列键值 | `fields: [{is_short, text}]` |
| `hr` | 分割线 | 无其它属性 |
| `img` | 单图 | `img_key` + `alt` |
| `img_combination` | 多图混排（双/三/四/六/九图） | `combination_mode` + `img_list` |
| `chart` | VChart 图表 | `chart_spec` + `aspect_ratio` + `color_theme` |
| `person` | 单人员 | `user_id` + `show_name` + `show_avatar` |
| `person_list` | 人员列表 | `persons: [{user_id}]` |
| `table` | 表格 | `rows` + `columns` + `row_height` |

**容器类**（装其他组件）：

| tag | 用途 | 关键属性 |
|-----|------|---------|
| `column_set` | 横向分栏 | `flex_mode` + `horizontal_spacing` + `columns` |
| `collapsible_panel` | 折叠面板 | `expanded` + `header.{title,icon,background_color}` + `elements` |
| `form` | 表单容器 | `name` + `elements`（收集一批 input 后一次提交） |
| `interactive_container` | 交互容器 | 统一样式和点击交互，包多个组件 |

**交互类**（可点/可输入）：

| tag | 用途 | 关键属性 |
|-----|------|---------|
| `button` | 按钮 | `type` + `text` + `behaviors: [{type: "open_url"|"callback"}]` |
| `input` | 单行输入 | `name` + `placeholder` + `default_value` |
| `textarea` | 多行输入 | 同 input，多 `rows` |
| `select_static` | 下拉单选 | `options: [{text, value}]` |
| `multi_select_static` | 下拉多选 | 同上，`selected_values` 数组 |
| `date_picker` | 日期 | `initial_date` + `placeholder` |
| `picker_time` | 时间 | 同上 |
| `picker_datetime` | 日期时间 | 同上 |
| `overflow` | 折叠菜单（⋯按钮）| `options: [{text, value, url}]` |

**完整字段、嵌套规则、坑点** → 读 `references/components.md`。

## 5. 美观三板斧（总纲）

### 5.1 配色

- `header.template` 从 13 种里选一种定主色（见 `design.md` 颜色矩阵）：
  - blue = 通知 / 信息 | green = 成功 | orange = 警告 | red = 错误 | grey = 归档 | purple = 品牌/数据
- markdown 内嵌色只用 `<font color='...'>` 点关键数字，**一张卡片主色不超过 3 种**
- 用 `grey` 压副文本视觉权重

### 5.2 布局节奏

- `body.vertical_spacing` 设 `medium`（8px）作默认节奏
- 重要信息 → `large` (12px) 拉大
- 紧凑行（如状态胶囊）→ `small` (4px)
- 场景切换 → 插 `hr` 做硬分割

### 5.3 元素密度（Z 字视线）

```
顶部  │ header（标题 + 副标题 + 最多 3 个 text_tag）
中上  │ markdown 摘要（核心结论，带 1-2 处 <font> 强调）
中部  │ div.fields（2×2 关键指标） 或 column_set（左图右文）
中下  │ chart / table（数据可视化）
底部  │ collapsible_panel（折叠次要信息）
操作区│ column_set 里放 2-3 个 button（primary 放中间）
```

细节展开见 `references/design.md`。

## 6. 禁区（v2 严格校验，未知属性会报错！）

| ❌ 禁止 | ✅ 替代 | 原因 |
|--------|--------|------|
| 顶层 `elements` 直接放 | 放进 `body.elements` | v2 必须 body 包裹 |
| `"tag": "action"` 交互模块 | 按钮直接放 `body.elements`，间距用 spacing | v2 废弃 action 模块 |
| `"tag": "note"` 备注组件 | `markdown` + `<font color='grey'>` + `text_size: "notation"` | v2 废弃 note |
| `config.wide_screen_mode` | `config.width_mode: "fill"` | v1 旧属性 |
| `config.update_multi: false` | `update_multi: true`（或不写） | v2 只支持 true |
| `i18n_elements` | `i18n_content`（局部多语言） | v2 不支持全局多语言 |
| hex 颜色 `#FF0000` | 颜色枚举 `red` 或 `rgba(255,0,0,1)` | v2 不认 hex |
| `[text]($urlVal)` 差异化跳转 | `<link icon='' url='' pc_url='' ...>` 标签 | v2 已删 |
| `stretch_without_padding` 图片通栏 | `margin: "0 -12px"` 负边距 | v2 已删 |
| `flex_mode: "fixed"` | `flex_mode: "none"` 或 `"bisect"/"trisect"` | 枚举不包含 fixed |
| `column.width: 1/2/3` 数字 | `width: "weighted"` + `weight: 1~5` | 列宽语法变了 |
| `collapsible_panel.header.padding: "4px 8px"` 两值 | 写成 `"4px 8px 4px 8px"` 四值 | 服务端对 header padding 严格校验，只接受单值或四值 |

**兜底检查**：写完 JSON 后搜一下 `note|action|wide_screen_mode`，有任何一个都改掉。

## 7. 完整范例（可直接复制）

```json
{
  "schema": "2.0",
  "config": { "update_multi": true, "enable_forward": true, "width_mode": "fill" },
  "header": {
    "template": "blue",
    "title": { "tag": "plain_text", "content": "🚀 本周迭代完成" },
    "subtitle": { "tag": "plain_text", "content": "2026-04-17 发版报告" }
  },
  "body": {
    "direction": "vertical",
    "vertical_spacing": "medium",
    "elements": [
      { "tag": "markdown", "content": "共交付 **12 个功能** / **修复 8 个 Bug**，<font color='green'>全部测试通过</font>。" },
      { "tag": "hr" },
      {
        "tag": "div",
        "fields": [
          { "is_short": true, "text": { "tag": "lark_md", "content": "**📦 版本**\n`v2.3.0`" } },
          { "is_short": true, "text": { "tag": "lark_md", "content": "**⏱ 耗时**\n5 天" } },
          { "is_short": true, "text": { "tag": "lark_md", "content": "**👥 参与**\n7 人" } },
          { "is_short": true, "text": { "tag": "lark_md", "content": "**✅ 状态**\n<font color='green'>已上线</font>" } }
        ]
      },
      {
        "tag": "collapsible_panel",
        "expanded": false,
        "header": {
          "title": { "tag": "markdown", "content": "**📋 详细变更清单（点击展开）**" },
          "background_color": "grey",
          "padding": "4px 8px 4px 8px",
          "icon": { "tag": "standard_icon", "token": "down-small-ccm_outlined", "size": "16px 16px" },
          "icon_position": "right",
          "icon_expanded_angle": -180
        },
        "elements": [
          { "tag": "markdown", "content": "- 新增卡片 V2 构造能力\n- 支持流式更新\n- 修复图表渲染问题" }
        ]
      },
      {
        "tag": "column_set",
        "flex_mode": "none",
        "horizontal_spacing": "8px",
        "columns": [
          {
            "tag": "column", "width": "weighted", "weight": 1, "vertical_align": "center",
            "elements": [{
              "tag": "button",
              "text": { "tag": "plain_text", "content": "📖 发版文档" },
              "type": "primary", "width": "fill",
              "behaviors": [{ "type": "open_url", "default_url": "https://example.com/release" }]
            }]
          },
          {
            "tag": "column", "width": "weighted", "weight": 1, "vertical_align": "center",
            "elements": [{
              "tag": "button",
              "text": { "tag": "plain_text", "content": "📊 监控大盘" },
              "type": "default", "width": "fill",
              "behaviors": [{ "type": "open_url", "default_url": "https://example.com/monitor" }]
            }]
          }
        ]
      },
      { "tag": "markdown", "content": "<font color='grey'>📡 由 feishu-cli-card 技能生成 · v2 schema 2.0</font>" }
    ]
  }
}
```

## 8. 发送衔接

```bash
# 方式 1：直接发给默认接收人（env FEISHU_OWNER_EMAIL 或 user@example.com）
feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --msg-type interactive \
  --content-file /tmp/my-card.json

# 方式 2：发群
feishu-cli msg send --receive-id-type chat_id --receive-id oc_xxx \
  --msg-type interactive --content-file /tmp/my-card.json

# 方式 3：带本地图片（--upload-images 自动上传 markdown 里的 ./img.png）
feishu-cli msg send --receive-id-type email --receive-id ... \
  --msg-type interactive --content-file /tmp/my-card.json --upload-images
```

**发送成功标志**：返回 `消息 ID: om_xxxxx`。如果报 `content format error` 或 `invalid element`，
回到第 6 节禁区表逐项检查。

---

## 深度资源

按需 Read：

| 文件 | 什么时候读 | 规模 |
|------|----------|------|
| `references/components.md` | 要用某个组件但不记得字段 / 要查嵌套规则 / 要查颜色枚举 | ~400 行，带 TOC |
| `references/design.md` | 要判断配色 / 布局节奏 / 场景 → 模板映射 | ~250 行 |
| `references/v2-vs-v1.md` | 有 v1 历史代码要迁移 / 要解释用户的 v1 示例为什么跑不通 | ~120 行 |
| `references/vchart-quickref.md` | 要画 chart（bar/pie/line/radar/gauge 等） | ~180 行 |
| `templates/<name>.json` | 7 个开箱即用骨架，每次都先选一个而不是从零写 | 各 80-150 行 |

---

## 和 feishu-cli-msg 的边界

- **feishu-cli-card（本技能）**：**构造** v2 卡片 JSON。职责是"写得漂亮"。
- **feishu-cli-msg**：**发送** 消息（各种类型，含 interactive）。职责是"送得出去"。

构造完成 → 调 msg 发送。两者解耦，不要混在一起写。