围绕飞书自建应用与DeepSeek API的完整接入路径，拆解凭证配置、消息路由、联调部署与教学场景治理，给出可复用的实操要点。
把DeepSeek接入飞书，本质是把飞书里的消息事件转成模型请求，再把模型回复送回会话。对AI指导老师而言，这条链路决定了课程答疑、作业反馈和教研协作能否稳定运行。下面按实际落地顺序拆开讲，重点放在凭证、权限、路由和教学场景治理上。
1. 接入前的应用边界与权限设计
先明确机器人只在哪些群、哪些课程使用，处理文本还是文件，是否允许私聊。AI指导老师不是通用聊天工具，回答范围要限定在课程大纲、教学资料和作业规范之内。企业自建应用比商店应用更适合这类内部场景，因为可用范围、权限申请和数据留存都更可控。管理员需要在飞书开放平台创建企业自建应用，开启机器人能力，把应用可用范围设置到教研组或试点课程群，避免一开始就全公司可见。
权限要按最小化原则申请，至少需要接收用户发给机器人的消息事件，以及以机器人身份发送单聊和群组消息。事件订阅选择im.message.receive_v1，群聊中还要判断消息是否@机器人。后续如果要读取群历史或云文档，再单独申请对应权限，不要一次性开大权限。权限变更后必须发布应用版本并由管理员审核，很多联调失败不是代码问题，而是版本没发布或可用范围没覆盖测试账号。
app_secret和DeepSeek API Key只能放服务端环境变量，不能写进飞书机器人卡片或前端代码。提前准备系统提示词和拒答策略，比如遇到课程外问题引导回课程群或教师。某教研团队先在高职数学课程群试点，只开放作业规范查询和知识点解释两类意图，误答明显减少。把边界设计清楚再写代码，联调范围会小很多。
2. 凭证获取与API调用链路搭建
在DeepSeek开放平台创建API Key，确认base_url为，常规聊天模型用deepseek-chat，复杂推理场景再评估deepseek-reasoner。请求走OpenAI兼容的chat/completions，消息数组包含system和user。先用Postman或curl验证，确认返回结构和错误码。API Key按开发和生产环境区分，设置额度告警，绝不能在飞书前端暴露。
飞书侧拿到app_id和app_secret后，调用tenant_access_token/internal获取tenant_access_token，并缓存到过期前，不要每条消息都重新换取。发送消息调用im/v1/messages，receive_id_type可选open_id或chat_id，消息体msg_type用text或interactive。先做非流式回复，降低联调复杂度；流式输出再考虑消息更新。群聊回复要引用原消息或@提问者，避免刷屏。
把链路串起来就是Webhook收到消息、解析text、取open_id或chat_id、拼系统提示词和用户问题、调用DeepSeek、截断到飞书消息长度限制、再发回。参数上temperature设低一些保证教学回答稳定，max_tokens按场景控制。日志记录message_id、chat_id、耗时和token用量，但不要记录完整敏感内容。测试时先用固定问题验证端到端，再放开真实群。
3. 消息路由服务与联调排错
部署公网HTTPS服务，配置飞书事件订阅请求地址。首次验证会发challenge，服务端原样返回；若开启加密，要用Encrypt Key解密并校验签名。事件体里取event.message.message_id、chat_id和content。飞书回调通常要求快速响应，模型调用可能超时，所以先返回200，再把任务放入队列异步处理。用message_id做幂等，避免飞书重试导致重复回复。
消息路由要处理三类分支：单聊直接处理，群聊只有@机器人才处理，非文本消息先提示暂不支持或转人工。调用DeepSeek后按飞书消息格式组装回复，超长内容分段发送。错误处理要区分鉴权失败、权限不足、模型超时和频率限制。常见联调问题是回调地址不可达、tenant_access_token过期、应用版本未发布、事件未订阅、机器人未被拉进群。日志里带trace_id，方便对照飞书开放平台事件日志。
群内@机器人没反应时，先看事件订阅是否勾选im.message.receive_v1，再看应用版本是否发布到测试企业，最后看机器人是否在群里且有发消息权限。另一个常见问题是模型回复超过飞书文本长度，直接发送失败，需要在服务端做分段。联调阶段按日志逐项定位，不要盲目改代码，把回调验证、鉴权、事件解析和消息发送四个环节分开排查，效率会高很多。
4. 教学场景落地与稳定性治理
教学场景要把提示词做成模板：角色设定为AI指导老师，限定课程范围，要求先判断问题类型，再给解释、示例和下一步练习；遇到作业代写、考试答案等请求要拒答并引导。知识库可用课程大纲、讲义、常见问题做检索增强，先检索再拼入prompt，减少编造。作业点评用rubric结构化输出，教师复核后再发。课程群答疑可把高频问题沉淀成FAQ，模型命中后直接回复，未命中再走生成。
稳定性治理包括超时重试、熔断和人工兜底。DeepSeek调用设置合理超时，失败时返回已转人工而不是空白。按课程群设置日调用限额和单用户频率限制，记录token用量，定期清理过长上下文。敏感信息要脱敏，不把学生隐私写进日志。模型输出要做长度截断和敏感词检查，重要通知不让模型自动发。
运营迭代靠badcase复盘。每周抽取低评分对话，区分是知识库缺失、提示词不清还是权限配置问题，更新模板和FAQ。教师端保留开关，可一键停用机器人。接入不是一次上线就结束，而是把飞书群、DeepSeek调用和教研内容维护成可持续的日常流程。这样AI指导老师才能稳定服务教学。
