功能说明: 本技能涵盖 自动化配置和灵活的参数设置、化配置和灵活的参数设置 等核心能力。

feishu-send-file

飞书机器人发送文件附件需要区分两条链路:普通文件走 im/v1/files 拿 file_key 后发 msg_type=file;图片走 im/v1/images 拿 image_key 后发 msg_type=image。混用会导致用户在飞书里看到路径文本而不是文件本体. 本技能封装两条链路的稳定调用方式,并提供针对"本地图片路径被发成路径文本"故障的可靠补救脚本.

输入定义

专业版增值服务

环境要求

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

快速熟悉

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

调用方式

方式一:脚本化调用(推荐)

python3 （请参考skill目录中的脚本文件） <file_path> <open_id> <app_id> <app_secret> [file_name]

参数说明:

• file_path:要发送的文件本地路径(HTML/PDF/ZIP/代码文件等)
• open_id:接收者 open_id,从 inbound_meta 的 chat_id 字段获取,格式 user:ou_未指定,取 ou_未指定 部分
• app_id:飞书应用 ID,从 skill-platform.json 的 channels.feishu.appId 读取
• app_secret:飞书应用密钥,从 skill-platform.json 的 channels.feishu.appSecret 读取
• file_name:可选,自定义文件名,不填则用原文件名

快速读取应用配置:

grep -A 2 '"feishu"' /root/.skill-platform/skill-platform.json | grep -E '(appId|appSecret)'

完整示例:

python3 /root/.skill-platform/workspace/skills/feishu-send-file/（请参考skill目录中的脚本文件） \
  /root/myfiles/report.html \
  ou_abc123def456 \
  cli_a1b2c3d4e5f6g7h8 \
  secretAbCdEfGhIjKlMnOp \
  weekly-report.html

方式二:手动两步

Step 1 - 获取 app_access_token 并上传文件:

TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['app_access_token'])")
# ...
FILE_KEY=$(curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_type=stream" \
  -F "file_name=<文件名>" \
  -F "file=@<文件路径>" \
load(sys.stdin)['data']['file_key'])")

Step 2 - 发送文件消息:

curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"receive_id\":\"<OPEN_ID>\",\"msg_type\":\"file\",\"content\":\"{\\\"file_key\\\":\\\"$FILE_KEY\\\"}\"}"

图片稳定发送

何时切换到图片链路

当本地图片路径(尤其是 /root/myfiles/...)通过 message 工具 media 参数发送后,用户在飞书里看到的是 📎 /root/myfiles/未指定.png 路径文本而不是图片本体,说明本地媒体上传链路已降级为路径回显。此时不要重试同一参数组合,直接改走本技能的稳定图片上传脚本. 关键判断:messageId 返回成功不等于用户真的看到图片。唯一成功标准是用户在飞书里实际看到图片本体.

推荐脚本

python3 （请参考skill目录中的脚本文件） <image_path> <open_id> <app_id> <app_secret> [domain]

中国版飞书示例:

python3 /root/.skill-platform/workspace/skills/feishu-send-file/（请参考skill目录中的脚本文件） \
  /root/myfiles/generated-images/demo.png \
  ou_abc123def456 \
  cli_a1b2c3d4e5f6g7h8 \
  secretAbCdEfGhIjKlMnOp

国际版 Lark 加第四个参数 lark:

python3 （请参考skill目录中的脚本文件） /root/myfiles/demo.png ou_未指定 cli_未指定 secret_未指定 lark

普通文件与图片的区别

• 普通文件:im/v1/files 获取 file_key,msg_type=file
• 图片:im/v1/images 获取 image_key,msg_type=image

两条链路不可混用。把本地路径直接塞给 msg_type=file 的 content 字段只会回显路径文本.

应用场景

场景一:自动化工作流分发产物

输入:CI 流水线生成的 HTML 测试报告路径 /root/myfiles/coverage.html、接收者 ou_未指定、飞书应用凭证 输出:用户在飞书会话中收到 coverage.html 文件附件,可点击预览或下载

场景二:企业团队批量通知附件

输入:周报 PDF /root/reports/weekly.pdf、群聊 chat_id、应用凭证 输出:群聊中收到 PDF 附件消息,所有群成员可见可下载

场景三:开发者本地图片稳定投递

输入:本地生成的图片 /root/myfiles/generated-images/demo.png、接收者 ou_未指定、应用凭证 输出:用户在飞书中看到图片本体,而非 📎 /root/myfiles/...png 路径文本

场景四:跨版本飞书文件投递

输入:同一份报告需同时投递给中国版飞书用户与国际版 Lark 用户 输出:分别调用 send_file.py 与 send_image.py 的 lark 域名参数,两边用户均收到文件本体

案例展示

案例一:HTML 报告投递失败排查

某用户反馈飞书机器人发送的 HTML 报告,接收方只看到 📎 /root/myfiles/report.html 文本,无法点击预览. 排查步骤:

1. 检查发送链路,确认使用的是 message 工具的 filePath 参数直传本地路径
2. 确认这是降级回显,不是真正发送成功
3. 改用脚本化调用:

python3 /root/.skill-platform/workspace/skills/feishu-send-file/（请参考skill目录中的脚本文件） \
  ou_abc123def456 \
  cli_a1b2c3d4e5f6g7h8 \
  secretAbCdEfGhIjKlMnOp \
  report.html

4. 接收方在飞书中收到可预览的 HTML 文件附件,问题解决.

案例二:群聊批量推送 PDF 周报

需要将 /root/reports/2026-W28.pdf 推送到部门群聊 oc_def678ghi901. 操作:

1. 将 receive_id_type 从 open_id 改为 chat_id
2. 调用:

python3 /root/.skill-platform/workspace/skills/feishu-send-file/（请参考skill目录中的脚本文件） \
  /root/reports/2026-W28.pdf \
  oc_def678ghi901 \
  cli_a1b2c3d4e5f6g7h8 \
  secretAbCdEfGhIjKlMnOp \
  2026-W28-周报.pdf

3. 群聊所有成员收到 PDF 附件.

案例三:本地图片路径被发成文本的补救

用户通过 message 工具 media 参数发送 /root/myfiles/generated-images/banner.png,飞书侧显示 📎 /root/myfiles/generated-images/banner.png 路径文本. 补救步骤:

1. 立即停止重试 media 参数
2. 切换到稳定图片脚本:

python3 /root/.skill-platform/workspace/skills/feishu-send-file/（请参考skill目录中的脚本文件） \
  /root/myfiles/generated-images/banner.png \
  ou_abc123def456 \
  cli_a1b2c3d4e5f6g7h8 \
  secretAbCdEfGhIjKlMnOp

3. 接收方在飞书中看到图片本体,问题解决.

异常应对

1. app_access_token 获取失败

现象:curl 返回 app_access_token 为空或 HTTP 401 原因:app_id 或 app_secret 错误、应用已被停用 处理:核对 skill-platform.json 中 channels.feishu.appId 与 appSecret,确认应用在飞书开放平台处于启用状态

2. 文件上传返回 230002

现象:上传到 im/v1/files 返回 code 230002 原因:文件大小超过 30MB 限制,或 file_type 取值非法 处理:确认文件不超过 30MB;普通文件一律用 file_type=stream,不要用 pdf、opus 等枚举值

3. 发送消息返回 230001

现象:调用 im/v1/messages 返回 code 230001 原因:receive_id 格式错误或机器人未与接收者建立会话 处理:open_id 应为 ou_ 开头的纯 ID(不含 user: 前缀);首次发送需接收者先向机器人发过任意消息建立会话

4. 图片路径被回显为文本

现象:messageId 返回成功,但用户侧看到 📎 /root/myfiles/未指定.png 原因:本地路径场景下 message 工具 media 链路降级,未真正走 im/v1/images 处理:立即改用 （请参考skill目录中的脚本文件）,走 im/v1/images 获取 image_key 后发 msg_type=image

5. 国际版 Lark 调用 404

现象:国际版用户调用 open.feishu.cn 返回 404 原因:国际版需走 open.larksuite.com 域名 处理:send_image.py 传入第四个参数 lark;手动调用时将所有 URL 的 open.feishu.cn 替换为 open.larksuite.com

6. 群聊发送返回 230002

现象:向 chat_id 发送返回 230002 原因:机器人未被加入该群聊,或 chat_id 格式错误 原因细节:chat_id 应为 oc_ 开头 处理:将机器人拉入目标群聊;确认 receive_id_type=chat_id 与 chat_id 类型匹配

7. 文件名含中文导致上传失败

现象:file_name 含中文或特殊字符时上传返回 400 原因:curl -F 参数编码问题 处理:使用脚本化调用,Python 脚本内部已处理编码;手动调用时确保 file_name 与本地文件名一致且为 UTF-8

8. file_key 过期导致发送失败

现象:Step 1 拿到 file_key 后延迟较久,Step 2 发送返回 file_key 无效 原因:file_key 有效期有限,通常需在获取后立即使用 处理:两步操作应连续执行,不要间隔超过数分钟;脚本化调用已自动连续执行

问答精选

Q1:为什么文件发送返回成功,但用户看不到文件?

messageId 返回成功只代表消息已投递到飞书服务器,不代表用户看到文件本体。如果用户看到的是 📎 /root/... 路径文本,说明本地路径被降级回显,需要改用本技能的两步上传链路或 send_image.py 脚本.

Q2:普通文件和图片为什么必须走不同链路?

飞书 API 设计上,普通文件走 im/v1/files 获取 file_key,图片走 im/v1/images 获取 image_key,两条链路的 msg_type 分别为 file 与 image。混用会导致文件无法正确渲染.

Q3:如何获取接收者的 open_id?

从 inbound_meta 的 chat_id 字段获取,格式为 user:ou_未指定,取 ou_未指定 部分。群聊场景从消息事件的 event.message.chat_id 获取,格式为 oc_未指定.

Q4:国际版 Lark 如何切换域名?

脚本化调用时给 send_image.py 传入第四个参数 lark。手动调用时将所有 URL 的 open.feishu.cn 替换为 open.larksuite.com,token 获取接口同步替换.

Q5:file_type 必须用 stream 吗?

是的。普通文件一律使用 file_type=stream,这是飞书 API 对通用文件的统一类型。pdf、opus、mp4 等枚举值仅用于特定媒体类型,普通文件使用会导致上传失败.

Q6:机器人首次向用户发消息为什么失败?

飞书要求用户先主动向机器人发过任意消息建立会话,机器人才能主动推送消息。首次发送返回 230001 时,需引导用户先向机器人发送一条消息.

功能边界

• 普通文件单文件大小上限 30MB,超过需拆分或使用飞书云文档
• file_key 与 image_key 有有效期,获取后需立即使用,不适合异步流水线长时间间隔
• 机器人主动推送需用户先建立会话,冷启动场景需引导用户触发
• 本技能不处理飞书云文档原生创建与权限管理,仅处理文件附件投递
• 国际版 Lark 与中国版飞书的 OAuth 凭证不互通,需分别申请应用
• 群聊发送需机器人已入群,不支持向未加入的群聊推送

技术创新

效率提升量化分析

差异化对比

核心痛点解决

安全基本准则

1. 确保API Key安全，避免泄露到公共代码库或日志文件中。
2. 对上传的文件进行安全检查，防止恶意文件上传。
3. 定期更新技能，修复已知的安全漏洞。
4. 对发送的文件内容进行加密处理，保护文件内容安全。
5. 限制技能的使用权限，确保只有授权用户可以调用该技能。

安全风险防范