Feishu Cli Msg

# 卡片消息发送与历史排障

飞书卡片消息（interactive）是最灵活的消息类型，支持丰富的布局和交互组件。本文档只维护 `msg send` 侧的发送格式、`template_id` / `card_id` 用法和历史排障。新增卡片 JSON 的设计与模板请使用 `../feishu-cli-card/SKILL.md`。

## 三种发送方式

| 方式 | 适用场景 | 灵活性 |
|------|---------|--------|
| 完整 Card JSON | 代码动态生成卡片 | 最高 |
| template_id | 使用飞书卡片搭建工具创建的模板 | 中等（模板变量） |
| card_id | 引用已保存的卡片实例 | 最低（固定内容） |

**推荐**：Agent 发送现成卡片时使用完整 Card JSON，最灵活且无需预先创建模板。卡片 JSON 本身由 `feishu-cli-card` 生成。

---

## Card JSON 结构

### v1 格式（历史兼容，新增卡片不要使用）

```json
{
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "卡片标题"}
  },
  "elements": [
    {"tag": "markdown", "content": "内容"},
    {"tag": "hr"},
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "备注"}]}
  ]
}
```

### v2 格式（支持高级组件）

```json
{
  "schema": "2.0",
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "卡片标题"}
  },
  "body": {
    "direction": "vertical",
    "elements": [
      {"tag": "markdown", "content": "内容"}
    ]
  }
}
```

**v1 vs v2 区别**：

| 特性 | v1 | v2 |
|------|----|----|
| 顶层容器 | `elements` 数组 | `body.elements` |
| 表格组件 | 不支持 | `table` |
| 图表组件 | 不支持 | `chart` |
| 表单容器 | 不支持 | `form_container` |
| 多列布局 | `column_set`（有限） | `column_set`（完整） |

**选择建议**：新增卡片默认使用 v2（`schema: "2.0"`）。v1 只用于历史卡片排障或迁移说明，不再作为新卡片模板。

---

## header 配置

### 颜色模板

| template 值 | 色系 | 推荐场景 |
|-------------|------|---------|
| `blue` | 蓝色 | 通用通知、信息提示 |
| `wathet` | 浅蓝 | 轻量提示、次要通知 |
| `turquoise` | 青色 | 进行中、处理中状态 |
| `green` | 绿色 | 成功、完成、通过 |
| `yellow` | 黄色 | 注意、提醒 |
| `orange` | 橙色 | 警告、需关注 |
| `red` | 红色 | 错误、失败、紧急 |
| `carmine` | 深红 | 严重告警、危险 |
| `violet` | 紫罗兰 | 特殊标记 |
| `purple` | 紫色 | 自定义分类 |
| `indigo` | 靛蓝 | 深色主题 |
| `grey` | 灰色 | 已处理、归档、历史 |

### 语义化颜色速查

```
成功/完成 → green
通用通知 → blue
警告/注意 → orange
错误/紧急 → red
进行中   → turquoise
已处理   → grey
```

### header 完整结构

```json
{
  "header": {
    "template": "blue",
    "title": {
      "tag": "plain_text",
      "content": "卡片标题"
    },
    "subtitle": {
      "tag": "plain_text",
      "content": "副标题（可选）"
    }
  }
}
```

---

## 组件速查

本节是历史排障参考，保留 v1/v2 混合组件用于读懂旧卡片。新增卡片以 `feishu-cli-card/references/components.md` 为准，不要使用 v1 的 `note` / `action`。

### 内容组件

#### markdown（最常用）

```json
{
  "tag": "markdown",
  "content": "**加粗** *斜体* ~~删除线~~ `代码`\n[链接](url)\n<font color='green'>绿色</font>"
}
```

#### hr（分割线）

```json
{"tag": "hr"}
```

#### note（v1 底部备注，新增不要使用）

灰色小字，通常放在卡片底部。v2 新卡片用 `markdown` + `<font color='grey'>...` + `text_size: "notation"` 替代。

```json
{
  "tag": "note",
  "elements": [
    {"tag": "plain_text", "content": "备注内容"}
  ]
}
```

note 的 elements 支持 `plain_text`、`lark_md`、`img` 类型。

#### img（图片）

```json
{
  "tag": "img",
  "img_key": "img_v2_xxx",
  "alt": {"tag": "plain_text", "content": "图片描述"},
  "mode": "fit_horizontal"
}
```

mode 可选值：`crop_center`（居中裁剪）、`fit_horizontal`（适应宽度）、`large`（大图）、`medium`（中图）、`small`（小图）、`tiny`（超小图）。

### 布局组件

#### div（文本块 + fields 多列）

基础文本块：

```json
{
  "tag": "div",
  "text": {"tag": "lark_md", "content": "一段文本"}
}
```

带 fields（多列布局）：

```json
{
  "tag": "div",
  "fields": [
    {"is_short": true, "text": {"tag": "lark_md", "content": "**标签1**\n值1"}},
    {"is_short": true, "text": {"tag": "lark_md", "content": "**标签2**\n值2"}},
    {"is_short": true, "text": {"tag": "lark_md", "content": "**标签3**\n值3"}},
    {"is_short": true, "text": {"tag": "lark_md", "content": "**标签4**\n值4"}}
  ]
}
```

- `is_short: true`：半宽排列（一行放两个）
- `is_short: false`：全宽排列（独占一行）

带 extra（右侧附加元素）：

```json
{
  "tag": "div",
  "text": {"tag": "lark_md", "content": "左侧文本"},
  "extra": {
    "tag": "button",
    "text": {"tag": "plain_text", "content": "操作"},
    "type": "primary",
    "url": "https://example.com"
  }
}
```

#### column_set（多列分栏，v2）

```json
{
  "tag": "column_set",
  "flex_mode": "none",
  "background_style": "default",
  "columns": [
    {
      "tag": "column",
      "width": "weighted",
      "weight": 1,
      "elements": [
        {"tag": "markdown", "content": "**左栏内容**\n详细描述..."}