Feishu Card Design 飞书卡片消息设计规范

飞书卡片消息设计规范技能——一套适用于所有 Agent 平台（TRAE 定时任务、Coze、Dify、自建 Agent）的飞书 IM 卡片消息渲染规范。基于 Card 2.0 Schema，定义邻近色环配色规则、标题命名规则、布局模式、客户端兼容性、可访问性。本技能是纯规范 Skill，不直接发送飞书消息。Do NOT use for 飞书云文档编辑/多维表格操作/IM 群管理/只发文本消息。

版本 1.0.4 | Card 2.0 Schema | 让任何 Agent 平台生成的飞书卡片消息都视觉一致、信息密度合理、行动闭环完整。

何时使用

触发场景（任一即触发）：

• Agent 需要发送飞书 IM 卡片消息（cron 定时任务、监控告警、报告推送、状态更新）
• 用户说"飞书卡片"、"飞书卡片消息"、"Card 2.0"、"飞书卡片设计/配色/模板"、"IM 提醒样式"、"推送飞书卡片"
• 已有卡片渲染不理想（Markdown 不渲染、配色混乱、标题无区分度、客户端兼容差）

Do NOT use for：

• 只发文本消息（不需要卡片）
• 飞书云文档编辑（用 lark-doc skill）
• 飞书多维表格操作（用 lark-base skill）
• 飞书 IM 群管理（用 lark-im skill，本 skill 只管卡片样式）

5 大铁律

铁律 1：Card 2.0 Schema

json

{
  "schema": "2.0",
  "config": {"wide_screen_mode": true, "update_multi": true},
  "header": {
    "title": {"tag": "plain_text", "content": "卡片标题"},
    "subtitle": {"tag": "plain_text", "content": "副标题（可选）"},
    "template": "blue"
  },
  "body": {"elements": [...]}
}

关键字段：

• header.title / header.subtitle：必须是 {"tag": "plain_text", "content": "..."} 结构
• header.template：起始色枚举（turquoise/blue/green/indigo/violet/red/yellow/wheat）
• body.elements：直接挂载数组，不要用 action 包装

禁止：旧版 config.wide_screen_mode / 顶层 elements / lark_md 元素（必须用 markdown 元素支持 #/##/>）/ button 用 action 包装（必须用 behaviors）

铁律 2：邻近色环配色（≤3 主色系）

• 由 header.template 决定起始色，整张卡片最多 3 种主色系
• 背景色块用 *-50 系列（light mode）
• yellow-50 / grey-50 是语义中性色，不计入 3 主色系限制

header.template	邻近色环可选背景色
turquoise	turquoise-50 / wathet-50 / blue-50
blue	blue-50 / violet-50 / purple-50
green	green-50 / turquoise-50
indigo	indigo-50 / blue-50 / violet-50
violet	violet-50 / purple-50 / indigo-50
red	red-50（仅告警，不与其他色搭配）
yellow	yellow-50（仅亮点，不作为主色）

铁律 3：5 语义色块

背景色	Hex（light mode）	语义	使用场景
blue-50	#F0F4FF	主推	核心信息、主要内容块
turquoise-50	#E2F8F5	主推	核心信息、主要内容块（turquoise 系）
yellow-50	#FBF4DF	亮点	金句、关键发现、反常识、可复制提示词
grey-50	#f5f6f7	统计	数据统计、表格摘要、耗时、计数
green-50	#E4FAE1	成功	通过的检查、完成的任务、正向行动
red-50	#FEF0F0	告警	失败、Critical 修复、风险警告

色值来源：飞书官方文档 颜色枚举值，light mode 模式取 *-50 系列。

铁律 4：标题命名 YYYYMMDD-类型-关键信息

格式：<8位日期>-<报告类型>-<关键信息1>-<关键信息2>-...

• 报告类型：存量日报 / 增量日报 / 行动清单 / 健康报告 / 周报 / 月报 / 发芽日报 / 综合日报 / 反思报告 / 告警通知 / 成功通知
• 关键信息：AI 从标题和内容提取 2-4 个关键词，用 - 分隔
• ✅ 20260719-存量日报-归档30篇-Atoms18条-主种1个
• ❌ 20260719-报告-report_id（无关键信息）

铁律 5：column + column_set 双重保险

兼容性问题：column.background_style V7.4+ 支持，column_set.background_style V7.9+ 才支持。同时设置两者双重保险。default 是「无背景色」，不触发双重保险。

11 种报告类型 × 配色映射

报告类型	header.template	主推块	亮点块	统计块	告警块（条件触发）
存量日报	turquoise	turquoise-50	yellow-50	grey-50	red-50（健康度章节有 ⚠️ 时）
增量日报	blue	blue-50	yellow-50	grey-50	—
行动清单	green	green-50	yellow-50	grey-50	—
健康报告	red	red-50	yellow-50	grey-50	red-50（评分<60 或有 Critical）
周报	indigo	blue-50	yellow-50	grey-50	—
月报	violet	blue-50	yellow-50	grey-50	—
发芽日报	turquoise	turquoise-50	yellow-50	grey-50	—
综合日报	blue	blue-50	yellow-50	grey-50	—
反思报告	indigo	blue-50	yellow-50	grey-50	—
告警通知	red	red-50	yellow-50	grey-50	red-50（强制）
成功通知	green	green-50	yellow-50	grey-50	—

告警块条件触发规则：

• 扫描章节内容是否含告警关键词：⚠️ / 异常 / 待补 / Critical / 失败 / 风险
• 含告警关键词 → 该章节背景色块切换为 red-50
• 不含告警关键词 → 用默认色（主推块或 green-50 表示通过）
• 告警通知类型强制全部告警块用 red-50

4 段式标准结构

text

Header（title + subtitle + 色）→ 主推块（blue-50/turquoise-50）
→ 亮点块（yellow-50）→ 统计块（grey-50）→ 行动按钮 + Footer note

永远不要省略：Header + 主推块 + Footer note。简单通知可省略亮点/统计块。

3 种使用方式

方式 1：Agent 读 SKILL.md + templates/ Agent 收到"发飞书卡片"指令时，Read SKILL.md → 从 templates/ 复制模板 → 替换内容 → 用 scripts/card_validator.py 验证 → 调用飞书 OpenAPI POST /im/v1/messages?receive_id_type=open_id 发送。

方式 2：Python 构建器（推荐 Python Agent）

python

from scripts.card_builder import stock_card, flow_card, action_card, health_card, weekly_card
card = flow_card(title="20260719-增量日报-...", subtitle="...", doc_url="https://...",
                 main_content="...", highlight="...", stats="...")

方式 3：Markdown → Card 转换器

bash

python scripts/markdown_to_card.py --input report.md --type flow-report \
  --title "20260719-增量日报-..." --output card.json

验证 11 项铁律

bash

python scripts/card_validator.py --input card.json

检查：schema=2.0 / header.template 合法色 / *-50 背景 / ≤3 主色系 / 邻近色环 / column+column_set 双重保险 / button.behaviors / 禁 lark_md / 禁 action 包装 / 标题格式 / 主推块+note footer

权限声明

能力类别	是否使用	说明
网络访问	❌	本 Skill 是纯规范，不直接发请求；示例代码 send_feishu_card() 演示如何调用飞书 OpenAPI，由调用方负责
文件读写	✅	scripts/card_validator.py 读卡片 JSON 文件；markdown_to_card.py 读 MD 写 JSON
环境变量	❌	不读取任何环境变量（飞书 OpenAPI 凭证由调用方管理）
subprocess	❌	不调用任何外部命令
外部 API	❌	不调用任何外部 API（飞书 OpenAPI 由调用方集成）

用户警告

⚠️ 本 Skill 是纯规范 Skill，不直接发送飞书消息。所有网络请求由调用方代码（示例中的 send_feishu_card() 函数）发起，调用方需自行管理飞书 App 凭证（app_id / app_secret）和用户授权。本 Skill 不存储、不传输任何凭证。

调用方发送卡片消息时需注意：

• 推荐用 open_id 直接推送给用户本人，不要用 chat_id 推送到 AIbot 自聊会话（用户可能看不到）
• 飞书 App 需开通 im:message:send_as_bot 权限

文件结构

路径	内容
SKILL.md	本文件，主入口
README.md / README.en.md	21 章产品页（中英双语）
references/	6 份规范文档：card-2.0-schema / color-system / title-naming / layout-patterns / compatibility / accessibility
templates/	5 份 JSON 模板：report / stat / action / alert / success
examples/	5 份真实样例：stock / flow / action / health / weekly（全部通过 11 项铁律验证）
scripts/	3 份工具：card_validator.py / card_builder.py / markdown_to_card.py

详细规范

• Card 2.0 Schema 完整字段：references/card-2.0-schema.md
• 邻近色环配色规则详解：references/color-system.md
• 标题命名规则 + 关键信息提取：references/title-naming.md
• 4 段式布局 + 多列布局：references/layout-patterns.md
• 客户端版本兼容性：references/compatibility.md
• 可访问性 + 国际化：references/accessibility.md
• 21 章产品页：README.md / README.en.md

License

MIT License — 详见 LICENSE