飞书机器人+deepseek官方api可直接对接，关键在于保障消息不丢、上下文不断、结果不乱码；必须使用webhook方式，严格校验签名与时间戳，控制响应在2秒内，用system角色约束输出json格式，结合redis缓存实现多用户上下文管理，并适配飞书三端消息渲染限制。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
直接用飞书机器人 + DeepSeek 官方 API 就能跑通，不需要自建服务或中转网关。关键不是“能不能接”，而是“怎么让消息不丢、上下文不断、结果不乱码”。
飞书机器人 Webhook 是唯一推荐的接入方式
别碰飞书开放平台的「事件订阅」或「自建应用」模式——它们要处理用户身份、OAuth2、消息加密、重试机制，开发成本高且容易卡在审核环节。Webhook 简单粗暴：飞书把用户消息 POST 到你指定的 URL，你调 DeepSeek API，再把结果 POST 回飞书 Webhook 地址。
- Webhook URL 必须是公网可访问的 HTTPS 地址（本地调试可用
ngrok或cloudflared） - 飞书对 Webhook 响应超时设为 3 秒，
DeepSeek API调用必须控制在 2 秒内，否则飞书会重发，导致重复回答 - 务必校验飞书请求头里的
X-Lark-Signature和X-Lark-Timestamp，否则任意 HTTP 请求都能伪造消息
deepseek-chat 接口调用必须带 system 角色和明确格式约束
飞书群消息天然无结构，用户可能发“查下昨天销售额”“@机器人 为啥跌了”“订单号 ABC123”，不加引导会让 DeepSeek 自由发挥，结果不可控。必须用 system 提示词锁定行为边界：
- 强制要求输出 JSON 格式（如
{"answer": "xxx", "confidence": 0.92}），后续解析才稳定 - 禁止生成 Markdown、代码块、换行符——飞书卡片渲染会崩，纯文本最安全
- 加上业务语境，例如：“你是在飞书群中服务电商运营团队的 AI 助手，只回答与订单、库存、促销相关的问题，其他一概回复‘暂不支持该问题’”
示例请求体片段：
{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "你只回答电商后台数据类问题，输出严格为 {\"answer\": \"...\", \"confidence\": 0.x}，不加说明文字"},
{"role": "user", "content": "上月退货率多少？"}
]
}
群聊中多用户并发时，context_id 不等于会话 ID
飞书没提供全局唯一的会话标识，context_id 实际是消息级 ID，每次新消息都变。想维持上下文（比如用户问“上个月呢”，你要知道他指上条问的“销售额”），得自己存：
• 把前一条用户消息 + 模型回答缓存在 Redis，key 用 chat_id + user_id 拼接
• 缓存过期时间设为 5 分钟，避免脏数据堆积
• 飞书不传 user_id 给 Webhook，得先用 /v1/im/v1/messages/{message_id}/members 接口反查，这步必须异步做，不能堵在主链路
- 别依赖飞书的
open_id做长期记忆——用户换设备或重装飞书，open_id可能变 - 群聊里不同人问同类问题（如都问“库存”，但指不同 SKU），仅靠
chat_id无法区分，必须结合消息原文做简单语义哈希
中文乱码、长文本截断、按钮失效是高频翻车点
飞书对卡片消息有硬限制：
• 单条消息最大 10KB，DeepSeek 输出超过 2000 字就大概率被截断
• 卡片中 button 的 value 字段只支持 ASCII，中文会变成 %E4%BD%A0%E5%A5%BD，点击后后端收不到原始值
• msg_type=interactive 卡片在旧版飞书 App 上不渲染，必须 fallback 到 text 类型
- 长回答拆成多条消息发，每条加序号（“①…②…”），别用分页按钮——飞书按钮回调逻辑复杂，易出错
- 所有按钮文案用英文，
value传 base64 编码后的中文字符串，后端再解码 - 首次发送用
text类型保底，3 秒后若需交互再补发interactive卡片
真正难的不是调通 API，而是让 AI 的“自由发挥”和飞书的“强约束消息模型”之间不打架。每次上线前，拿飞书 iOS/Android/PC 三端各测一遍消息渲染和点击反馈，漏掉任一端都可能引发用户投诉。
