前置条件
- 1已安装飞书客户端（7.28 及以上）并拥有企业/团队账号
- 2是目标飞书群的群管理员（自定义机器人只有群管理员能添加）
- 3已注册 Moonshot AI 开放平台账号并创建 API Key
- 4有一台能出网的机器跑中转脚本，Python 3.10+ 或 Node.js 18+
即时通信 IM + AI
高效构建智能聊天能力
常见问题
Q群里发一份 80 页的 PDF，Kimi 能直接读完回答吗？
能，但要走文件上传而不是把正文塞进 messages。做法是先用 /v1/files 上传文件拿到 file_id，再在 messages 里放一个 role 为 system、content 类型为 file 的消息引用它，K3 会在服务端完成解析。群里常见的做法是：用户把文件发给机器人 → 你的服务用 im:resource 权限下载 → 转发到 /v1/files → 拿到 file_id 后再提问。同一个 file_id 可以反复提问，不用重复上传，这是省钱的关键。
Q加签一直返回 19021 sign match fail 怎么办？
三个高频原因：timestamp 用了毫秒（13 位）必须改成秒级（10 位）；待签名串必须是 timestamp 加换行符加 secret，顺序不能反；加密结果要取 HMAC-SHA256 的十六进制小写字符串，而钉钉要的是 base64。另外服务器时间与飞书相差超过 1 小时也会被拒。
Q回复很慢，群里的人等得不耐烦怎么办？
长文问答本身要 3-8 秒，光靠提速没用。正确的做法是先发一张灰色「处理中」的占位卡片，拿到 message_id 后用 PATCH 把答案覆盖上去，用户感知延迟能从 4 秒降到 0.3 秒。再进一步可以开流式：Kimi 支持 stream=True，配合卡片流式更新让答案一个字一个字长出来。
Qtenant_access_token 多久过期？能不能每次发消息都重新获取？
有效期 2 小时，不要每次都重新获取。飞书对鉴权接口有独立限流，实测高频换取会在几十秒内被打回限流错误，导致全部发消息请求失败。正确做法是进程内缓存，在剩余有效期小于 300 秒时刷新；多实例部署放 Redis 并加分布式锁。
Q卡片消息返回 230002 怎么排查？
230002 是消息体校验失败。按顺序查：header.template 只能用内置色号不能写十六进制颜色；elements 的 tag 必须是受支持标签；actions 里每个按钮必须有 type 和非空 value（不超过 512 字节）；自建应用调用时 content 必须是字符串化的 JSON 而不是对象；整张卡片序列化后不超过 30KB。