飞书消息发送技能

通过 feishu-cli 发送飞书消息，支持多种消息类型和丰富的消息管理操作。

核心概念

消息架构

飞书消息 API 的 content 字段是一个 JSON 字符串（不是 JSON 对象）。CLI 提供三种输入方式：

优先级：--text > --content > --content-file（同时指定时前者优先）

接收者类型

消息类型选择

决策树（Claude 未指定类型时自动选择）

默认优先使用 interactive（卡片消息），样式美观、内容丰富、支持颜色/多列/按钮等。

用户需求
├─ 【默认】通知/报告/告警/任何有信息量的消息 → interactive（卡片）
├─ 发送已上传的图片/文件/音视频 → image/file/audio/media
├─ 分享群聊或用户名片 → share_chat/share_user
├─ 会话分割线（仅 p2p） → system
└─ 仅以下场景才用 text/post：
   ├─ 用户明确要求发纯文本 → text
   └─ 用户明确要求发富文本 → post

为什么优先卡片：text 不支持任何格式渲染，post 样式有限，卡片支持彩色 header、多列 fields、按钮、分割线、备注等，视觉效果远优于其他类型。

消息类型一览

发送命令

基础格式

feishu-cli msg send \
  --receive-id-type <type> \
  --receive-id <id> \
  [--msg-type <msg_type>] \
  [--text "<text>" | --content '<json>' | --content-file <file.json>]

text 类型

# 最简形式（默认 msg-type 为 text）
feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --text "你好，这是一条测试消息"

text 类型支持的内联语法：

• @ 用户：<at user_id="ou_xxx">Tom</at>
• @ 所有人：<at user_id="all"></at>

注意：text 类型不支持富文本样式（加粗、斜体、下划线、删除线、超链接等均不会渲染）。如需格式排版，请使用 post 类型。

post 类型（富文本）

推荐使用 md 标签承载 Markdown，一个 md 标签独占一个段落：

cat > /tmp/msg.json << 'EOF'
{
  "zh_cn": {
    "title": "项目进展通知",
    "content": [
      [{"tag": "md", "text": "**本周进展**\n- 完成功能 A 开发\n- 修复 3 个 Bug\n- [查看详情](https://example.com)"}],
      [{"tag": "md", "text": "**下周计划**\n1. 功能 B 开发\n2. 性能优化"}]
    ]
  }
}
EOF

feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --msg-type post \
  --content-file /tmp/msg.json

post 支持的 tag 类型：

interactive 类型（卡片消息）

卡片消息有三种发送方式：

方式一：完整 Card JSON（推荐，最灵活）

cat > /tmp/card.json << 'EOF'
{
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "任务完成通知"}
  },
  "elements": [
    {"tag": "markdown", "content": "**项目**: feishu-cli\n**状态**: 已完成\n**负责人**: <at id=all></at>"},
    {"tag": "hr"},
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "由 CI/CD 自动发送"}]}
  ]
}
EOF

feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --msg-type interactive \
  --content-file /tmp/card.json

方式二：template_id

cat > /tmp/card.json << 'EOF'
{
  "type": "template",
  "data": {
    "template_id": "AAqk1xxxxxx",
    "template_variable": {"name": "张三", "status": "已完成"}
  }
}
EOF

feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --msg-type interactive \
  --content-file /tmp/card.json

方式三：card_id

feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --msg-type interactive \
  --content '{"type":"card","data":{"card_id":"7371713483664506900"}}'

Card JSON 结构（v1 vs v2）

v1 格式（推荐，兼容性好）：

{
  "header": {"template": "blue", "title": {"tag": "plain_text", "content": "标题"}},
  "elements": [...]
}

v2 格式（更多组件）：

{
  "schema": "2.0",
  "header": {"template": "blue", "title": {"tag": "plain_text", "content": "标题"}},
  "body": {"direction": "vertical", "elements": [...]}
}

v2 额外支持：table（表格）、chart（图表）、form_container（表单）、column_set（多列布局）等高级组件。对于简单通知，v1 足够；需要复杂布局时用 v2。

header 颜色模板

语义化推荐：绿=成功 / 蓝=通知 / 橙=警告 / 红=错误 / 灰=已处理

常用组件速查

内容组件：

布局组件：

交互组件：

卡片 Markdown 语法（lark_md）

卡片内 markdown 组件使用 lark_md 语法，与标准 Markdown 有差异：

# 支持的语法
**加粗** *斜体* ~~删除线~~ [链接](url) `行内代码`
![图片](img_v2_xxx)

# 特有语法
<font color='green'>绿色文字</font>
<font color='red'>红色文字</font>
<font color='grey'>灰色文字</font>
<at id=ou_xxx></at>
<at id=all></at>

注意：lark_md 的 <font color> 仅支持 green/red/grey 三种颜色。

常用卡片模板

模板 1：简单通知卡片

{
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "通知标题"}
  },
  "elements": [
    {"tag": "markdown", "content": "通知内容，支持 **加粗** 和 [链接](https://example.com)"},
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "来自自动化工具"}]}
  ]
}

模板 2：告警卡片（多列 + 按钮）

{
  "header": {
    "template": "red",
    "title": {"tag": "plain_text", "content": "告警通知"}
  },
  "elements": [
    {
      "tag": "div",
      "fields": [
        {"is_short": true, "text": {"tag": "lark_md", "content": "**服务**\napi-gateway"}},
        {"is_short": true, "text": {"tag": "lark_md", "content": "**级别**\n<font color='red'>P0</font>"}},
        {"is_short": true, "text": {"tag": "lark_md", "content": "**时间**\n2024-01-01 10:00"}},
        {"is_short": true, "text": {"tag": "lark_md", "content": "**影响**\n<font color='red'>用户无法登录</font>"}}
      ]
    },
    {"tag": "hr"},
    {
      "tag": "action",
      "actions": [
        {"tag": "button", "text": {"tag": "plain_text", "content": "查看详情"}, "type": "primary", "url": "https://example.com/alert/123"},
        {"tag": "button", "text": {"tag": "plain_text", "content": "忽略"}, "type": "default"}
      ]
    }
  ]
}

模板 3：进度报告卡片

{
  "header": {
    "template": "green",
    "title": {"tag": "plain_text", "content": "构建报告"}
  },
  "elements": [
    {"tag": "markdown", "content": "**项目**: feishu-cli\n**分支**: main\n**提交**: abc1234"},
    {"tag": "hr"},
    {"tag": "markdown", "content": "<font color='green'>Tests: 42/42 passed</font>\n<font color='green'>Build: Success</font>\n<font color='grey'>Duration: 3m 25s</font>"},
    {"tag": "hr"},
    {
      "tag": "action",
      "actions": [
        {"tag": "button", "text": {"tag": "plain_text", "content": "查看日志"}, "type": "default", "url": "https://ci.example.com/build/123"}
      ]
    },
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "CI/CD Pipeline #123"}]}
  ]
}

模板 4：文档操作通知

{
  "header": {
    "template": "turquoise",
    "title": {"tag": "plain_text", "content": "文档操作通知"}
  },
  "elements": [
    {
      "tag": "div",
      "fields": [
        {"is_short": true, "text": {"tag": "lark_md", "content": "**操作类型**\n创建文档"}},
        {"is_short": true, "text": {"tag": "lark_md", "content": "**状态**\n<font color='green'>成功</font>"}}
      ]
    },
    {"tag": "markdown", "content": "**文档标题**: 周报 2024-W01\n**文档链接**: [点击查看](https://xxx.feishu.cn/docx/abc123)"},
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "由 feishu-cli 自动创建"}]}
  ]
}

模板 5：审批确认卡片（多按钮）

{
  "header": {
    "template": "orange",
    "title": {"tag": "plain_text", "content": "审批请求"}
  },
  "elements": [
    {"tag": "markdown", "content": "**申请人**: 张三\n**申请类型**: 服务器扩容\n**说明**: 线上流量增长，需要增加 2 台服务器"},
    {"tag": "hr"},
    {
      "tag": "action",
      "actions": [
        {"tag": "button", "text": {"tag": "plain_text", "content": "批准"}, "type": "primary"},
        {"tag": "button", "text": {"tag": "plain_text", "content": "拒绝"}, "type": "danger"},
        {"tag": "button", "text": {"tag": "plain_text", "content": "查看详情"}, "type": "default", "url": "https://example.com/approval/456"}
      ]
    }
  ]
}

其他消息命令

获取消息详情

feishu-cli msg get <message_id>
feishu-cli msg get om_xxx --output json

转发消息

feishu-cli msg forward <message_id> \
  --receive-id user@example.com \
  --receive-id-type email

删除消息

仅能删除机器人自己发送的消息，不可恢复。

feishu-cli msg delete <message_id>

获取消息列表

feishu-cli msg list \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 20 \
  --sort-type ByCreateTimeDesc

支持参数：--start-time、--end-time（秒级时间戳）、--page-token。

获取会话历史

feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --sort-type ByCreateTimeAsc \
  --page-size 50

查询消息已读用户

feishu-cli msg read-users <message_id>
feishu-cli msg read-users om_xxx --user-id-type user_id --page-size 50

搜索群聊

feishu-cli msg search-chats --query "项目群"
feishu-cli msg search-chats --page-size 20

搜索消息（需 User Access Token）

feishu-cli search messages "关键词" \
  --user-access-token u-xxx \
  --chat-ids oc_xxx \
  --message-type file \
  --start-time 1704067200

执行流程

Claude 发送消息时按以下流程操作：

1. 确定接收者：默认 user@example.com（email），或从上下文获取
2. 选择消息类型：
   • 用户明确指定类型 → 使用指定类型
   • 默认使用 interactive（卡片消息） → 根据内容语义选择 header 颜色和合适的组件布局
   • 仅在用户明确要求纯文本/富文本时 → 使用 text / post
3. 构造卡片内容：
   • 根据消息语义选择 header 颜色（绿=成功、红=错误、橙=警告、蓝=通知、灰=归档）
   • 使用 markdown 组件承载主要内容
   • 有多个键值对时使用 div + fields 多列布局
   • 需要操作链接时添加 action + button
   • 底部添加 note 备注来源
   • 将 JSON 写入临时文件后用 --content-file 发送
4. 发送并检查结果：执行命令，确认返回 message_id

权限要求

注意事项

错误处理

参考文档

• references/message_content.md：各消息类型的 content JSON 结构详解
• references/card_schema.md：卡片消息完整构造指南（组件、布局、模板）