feishu-cli-card（feishu CLI card 命令行）

飞书 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 最小可运行骨架

{
  "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 节禁区）

1. 落盘：Write 到 /tmp/<name>-card.json（复用已有路径避免污染）
2. 发送： 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. 组件速查矩阵

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

容器类（装其他组件）：

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

完整字段、嵌套规则、坑点 → 读 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 严格校验，未知属性会报错！）

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

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

{
  "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. 发送衔接

# 方式 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：

和 feishu-cli-msg 的边界

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

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