feishu-send-file

核心用法

feishu-send-file 是飞书生态中专门处理普通文件传输的补足型技能。飞书 API 对文件类型有严格区分：图片、视频可直接通过 message 工具的 media 参数发送，但 HTML、PDF、ZIP、代码文件等普通附件必须走「上传-获取 file_key-发消息」的两步流程。本技能封装了这一繁琐过程，提供脚本化一键方案与手动 REST API 两种模式。

显著优点

• 流程封装：将租户令牌获取、文件上传、消息发送三个 API 调用收敛为单条命令，降低 70% 以上的集成代码量
• 配置透明：明确标注从 openclaw.json 读取 appId/appSecret，从 chat_id 提取 open_id，解决飞书 ID 体系混乱的常见问题
• 类型兼容：file_type=stream 通吃所有普通文件，无需按后缀名区分 MIME 类型
• AI 友好：提供可直接嵌入 agent 执行的 Python exec 模板，适合自动化场景

潜在缺点与局限性

• 非原生集成：依赖外部 Python 脚本与 curl，非飞书官方 SDK 调用，稳定性受网络与本地环境制约
• 令牌管理粗糙：每次调用均重新获取 tenant_access_token，未做缓存复用，高频场景可能触发频率限制
• 错误处理缺失：脚本与 curl 示例均未展示失败重试、token 过期刷新、文件大小校验等生产级逻辑
• 群聊支持未验证：文档注明群聊需切换 receive_id_type 为 chat_id，但未提供完整示例

适合人群

• 需要向飞书用户推送报告、日志、备份文件的运维/数据工程师
• 构建飞书客服、审批通知等自动化工作流的低代码开发者
• 已将 OpenClaw 作为 agent 运行时、需扩展文件输出能力的 AI 应用开发者

常规风险

• 密钥泄露：脚本参数与 grep 命令均要求直接接触 appSecret，历史命令残留或日志记录可能导致凭证外泄
• 路径遍历：file_path 参数若未校验，可能被恶意构造为 ../../../etc/passwd 等敏感路径
• 频率限制：飞书开放平台的 tenant_access_token 与文件上传接口均有 QPS 限制，批量推送需自行限流
• 文件持久性：飞书文件存储有有效期（通常 30 天），长期归档需用户及时下载

核心用法

feishu-send-file 是专为飞书机器人设计的文件发送技能，解决飞书API对普通文件（HTML/PDF/ZIP/代码等）与媒体文件（图片/视频）的不同处理逻辑。核心流程为两步：先上传获取file_key，再发送消息。

推荐方式：使用封装脚本 scripts/send_file.py，一行命令完成双步操作，需传入文件路径、接收者open_id、应用凭证（app_id/app_secret）及可选自定义文件名。脚本自动处理Token获取、文件上传、消息发送全流程。

手动方式：分别调用飞书tenant_access_token/internal获取Token、im/v1/files上传文件获取file_key、im/v1/messages发送文件消息。适用于需要深度定制或调试的场景。

显著优点

• 流程清晰：明确区分媒体文件（直接用message tool）与普通文件（必须用本技能），避免常见误用
• 开箱即用：提供完整Python脚本，无需理解飞书API细节即可快速集成
• 官方接口：仅对接飞书开放平台的官方可信API（TLS 1.2+加密），无第三方中间服务
• 灵活配置：支持自定义文件名，兼容个人消息（open_id）与群聊（chat_id）场景
• 文档详尽：包含参数说明、配置获取命令、AI助手调用示例，降低使用门槛

潜在局限

• 来源可信度一般：维护者为个人开发者（dadaniya99），无企业背书，需人工审查脚本内容
• 无内置输入验证：文档未强调file_path路径遍历防护、open_id格式校验，依赖使用者自行处理
• 错误处理缺失：示例代码未展示Token失效、上传失败、网络异常等边界情况的处理
• 依赖外部凭证：必须配置有效的飞书应用凭证，新手可能因权限配置不当导致调用失败
• T-MD纯文档类型：无可执行代码文件，实际功能依赖用户主动执行脚本或命令

适合人群

• 已部署飞书机器人、需要向用户发送报告/代码/文档等非媒体文件的开发者
• 熟悉命令行操作、具备基础飞书开放平台配置经验的技术人员
• 希望快速集成文件发送能力、不愿深入研究飞书API细节的效率型用户

常规风险

• 凭证泄露风险：app_secret在命令行或脚本中明文传递时可能被历史记录、进程列表捕获
• 路径遍历风险：若file_path未经验证直接传入，可能导致敏感文件被意外读取上传
• API限流风险：高频调用可能触发飞书平台速率限制，影响服务稳定性
• Token过期风险：tenant_access_token有效期较短，长任务场景需考虑刷新机制
• 误操作风险：群聊场景下若未正确切换receive_id_type，可能导致消息发送错误对象