飞书消息发送与互动技能

通过 feishu-cli 发送飞书消息、回复、转发、Reaction、Pin 等互动操作。

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

查看聊天记录？ 请使用 feishu-cli-chat 技能（msg history/list/get/search-chats/群管理）。本技能专注于消息的发送与互动操作。

核心概念

消息架构

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

互斥：以上 5 种输入方式只能指定一个，同时指定会报错。

接收者类型

消息类型选择

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

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

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

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

消息类型一览

身份说明

本技能所有命令使用 App Token（Bot 身份），无需登录。

Reaction/Pin/删除/获取消息/搜索群聊？ 这些操作需要 User Token，已移至 feishu-cli-chat 技能（需先 auth login）。

发送命令

基础格式

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

file 类型（直发文件）

# 直接发送本地文件（自动上传，限 30MB）
feishu-cli msg send \
  --receive-id-type email \
  --receive-id user@example.com \
  --file /path/to/report.pdf

自动推断文件 MIME 类型（opus/mp4/pdf/doc/xls/ppt），未知类型使用 stream。超过 30MB 的文件请先用 file upload 上传到云空间，再用 --msg-type file --content '{"file_key":"..."}' 发送。

image 类型（直发图片）

# 直接发送本地图片（自动上传，限 10MB）
feishu-cli msg send \
  --receive-id-type chat_id \
  --receive-id oc_xxx \
  --image /path/to/screenshot.png

支持 JPEG、PNG、BMP、GIF、TIFF、WebP 格式。

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"}
      ]
    }
  ]
}

自动上传本地图片（推荐）

发送 post 或 interactive 卡片消息时，推荐使用 --upload-images flag 自动解析并上传内容中的本地图片，无需手动预上传：

# 卡片消息中嵌入本地图片（自动上传）
cat > /tmp/card.json << 'EOF'
{
  "header": {
    "template": "blue",
    "title": {"tag": "plain_text", "content": "项目报告"}
  },
  "elements": [
    {"tag": "markdown", "content": "截图：\n![截图](./screenshot.png)"},
    {"tag": "note", "elements": [{"tag": "plain_text", "content": "自动上传本地图片"}]}
  ]
}
EOF

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

最佳实践：

• 相对路径基于 --content-file 所在目录解析（与 doc import 保持一致）
• 支持 Markdown 语法：![alt](local/path.png)
• 支持 img 标签：{"tag":"img","image_key":"local/path.png","width":100,"height":100}
• 自动识别 img_ 开头的远程图片和已上传图片，跳过上传

限制：

• 仅对 post 和 interactive 消息类型有效
• 图片大小限制 10MB

回复消息

回复指定消息，支持与 msg send 相同的消息类型和输入方式。

# 文本回复
feishu-cli msg reply <message_id> --text "收到，我来处理"

# 卡片回复
feishu-cli msg reply <message_id> --msg-type interactive --content-file /tmp/card.json

# 富文本回复
feishu-cli msg reply <message_id> --msg-type post --content-file /tmp/post.json

消息加急

对指定用户发送消息加急通知，支持应用内加急、电话加急和短信加急三种方式。

# 应用内加急（默认）
feishu-cli msg urgent <message_id> \
  --user-ids ou_xxx,ou_yyy \
  --user-id-type open_id

# 电话加急
feishu-cli msg urgent <message_id> \
  --urgent-type phone \
  --user-ids u_xxx,u_yyy \
  --user-id-type user_id

# 短信加急
feishu-cli msg urgent <message_id> \
  --urgent-type sms \
  --user-ids on_xxx,on_yyy \
  --user-id-type union_id

加急类型说明

注意：

• 电话和短信加急需要单独申请权限并通过审批
• 加急通知会向指定用户发送强提醒
• 建议仅在紧急情况下使用

合并转发

将多条消息合并转发给指定接收者。

feishu-cli msg merge-forward \
  --receive-id user@example.com \
  --receive-id-type email \
  --message-ids om_xxx,om_yyy,om_zzz

Reaction / Pin / 删除消息

这些命令需要 User Token，已移至 feishu-cli-chat 技能。包括：

• msg reaction add/remove/list — 表情回应
• msg pin/unpin — 置顶/取消置顶
• msg pins — 查看群内置顶消息
• msg delete — 删除消息（仅 Bot 自己发的）
• msg get — 获取消息详情

请使用 feishu-cli-chat 技能操作以上功能。

其他消息命令

转发消息

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

执行流程

发送消息流程

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

权限要求

注意事项

错误处理

批量获取消息

一次获取多条消息的详细信息。

feishu-cli msg mget --message-ids om_xxx,om_yyy,om_zzz

下载消息资源

下载消息中的图片或文件附件。

# 下载消息中的图片
feishu-cli msg resource-download <message_id> <file_key> --type image -o /tmp/photo.png

# 下载消息中的文件
feishu-cli msg resource-download <message_id> <file_key> --type file -o /tmp/attachment.pdf

# 下载大文件时指定超时时间
feishu-cli msg resource-download <message_id> <file_key> --type image -o /tmp/photo.png --timeout 10m

file_key 来源：通过 msg get <message_id> 获取消息详情，从 content 中提取 image_key 或 file_key。

话题（Thread）消息

发送到已有话题

msg send 支持 --thread-id（等价于 --receive-id-type thread_id --receive-id <thread_id>）：

# 在已有话题内追加一条消息
feishu-cli msg send --thread-id omt_xxx --text "话题内继续聊"

# 卡片消息也支持
feishu-cli msg send --thread-id omt_xxx \
  --msg-type interactive \
  --content "$(cat card.json)"

--thread-id 与 --receive-id-type/--receive-id 互斥，只能指定一组。

回复时开启话题

msg reply 支持 --reply-in-thread（reply_in_thread=true）：

# 在非话题群聊中，以话题形式回复某条消息（会开启一个新话题）
feishu-cli msg reply om_xxx --text "这里开个话题" --reply-in-thread

# 若群聊已是话题模式，--reply-in-thread 会自动回复到消息所在话题

话题回复列表

获取话题中的所有回复消息：

# 获取话题回复
feishu-cli msg thread-messages <thread_id>

# 指定排序和分页
feishu-cli msg thread-messages <thread_id> \
  --sort ByCreateTimeAsc \
  --page-size 20

# 指定时间范围
feishu-cli msg thread-messages <thread_id> \
  --start-time 1704067200000 \
  --end-time 1704153600000

参考文档

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