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 节禁区）
5. 落盘：Write 到 /tmp/<name>-card.json（复用已有路径避免污染）
6. 发送：

   feishu-cli msg send \
     --receive-id-type email \
     --receive-id [email protected] \
     --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"
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. 完整范例（可直接复制）

{
  "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 或 [email protected]）
feishu-cli msg send \
  --receive-id-type email \
  --receive-id [email protected] \
  --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 发送。两者解耦，不要混在一起写。