07-实战 · 飞书卡片组件速查表

目标：做 OpenClaw 飞书卡片时，快速判断该用什么组件。这里按实战用途整理，不替代飞书官方文档。

组件选择原则

先确定卡片任务：

任务	推荐组件
发通知	`markdown` + 简单 header
展示统计	`column_set` / 多段 markdown
展示大量明细	`collapsible_panel`
让用户选择	`button` / `select` / `form`
危险操作确认	二级确认卡片或 confirm 流程
展示完成状态	更新原卡片 header + footer

卡片不是网页，别把所有东西都塞进去。复杂交互应该拆成多张卡。

用途：告诉用户这张卡是什么状态。

建议颜色：

状态	template
信息	`blue`
成功	`green`
警告	`orange`
失败	`red`
已取消 / 过期	`grey`

示例：

{
  "header": {
    "title": { "tag": "plain_text", "content": "OpenClaw 周审完成" },
    "template": "green"
  }
}

Markdown

最常用，适合摘要、说明、列表。

适合：

任务摘要
错误解释
操作说明
少量列表

不适合：

复杂表格
过长日志
需要用户输入的内容

建议把日志压缩成“错误类型 + 下一步命令”，不要直接贴几百行。

Column Set

适合展示并列统计，例如周审卡片里的三层记忆：

高价值：8
待审阅：3
低价值：12

用法建议：

每列只放短文本
不要超过 3 列
移动端优先考虑可读性
数字和状态比长句更适合列布局

Collapsible Panel

适合“默认折叠，用户想看再展开”的内容：

记忆候选明细
错误详情
dry-run 预览
变更列表

设计建议：

折叠标题写清数量
展开内容只放前 N 条
超长明细放链接或提示用户看日志
卡片接近大小限制时优先折叠明细

Button

OpenClaw 卡片最关键的组件。

按钮设计建议：

按钮类型	用法
primary	推荐动作，例如“合并高价值”
default	普通动作，例如“查看详情”
danger	危险动作，例如“确认回滚”

按钮 value 必须结构化：

{
  "action": "memory-merge-high",
  "task_id": "weekly-2026-04-24",
  "tier": "high",
  "card_meta": {
    "issued_at": 1777046400,
    "expires_in_sec": 604800
  }
}

不要只传 "ok"。

Form / Select

适合让用户从少量选项里选择：

选择合并层级
选择 Git 平台
选择告警级别
选择派给哪个 agent

注意：表单会让 handler 复杂度上升。第一版系统建议先用按钮，跑顺后再加表单。

Footer 适合放排障信息：

task_id
生成时间
模型名
cache / context 简要指标
过期时间

不要把敏感字段放 footer，例如完整 open_id、token、内部路径。

卡片大小控制

经验策略：

核心摘要永远保留
明细默认折叠
只展示前 5-10 条
超限时自动删除低价值明细
发送失败时降级成文本摘要或兜底卡

上线前跑：

python3 your-card-script.py --dry-run > /tmp/card.json
wc -c /tmp/card.json
python3 -m json.tool /tmp/card.json >/dev/null

组件搭配模板

通知卡

Header + Markdown + Footer

审批卡

Header + Summary + Collapsible Details + Buttons + Footer

运维告警卡

Header(red/orange) + Impact + Next Commands + Buttons + Footer

周审卡

Header + 三列统计 + 热门主题 + 分层折叠明细 + 合并/回滚按钮 + Footer

让 AI 生成组件草稿

帮我设计一张飞书 CardKit 2.0 卡片，用于 OpenClaw【填写场景】。
请先说明你选择了哪些组件以及原因，再输出 JSON。
限制：
1. 不超过 25KB。
2. 明细必须折叠。
3. 按钮 value 必须包含 action、task_id、issued_at。
4. 危险按钮必须用 danger 风格，并要求二次确认。