核心导读与中文摘要
从 Webhook 验签、3 秒超时异步回执、流式消息更新到群聊 @ 唤醒与会话记忆隔离,手把手写出稳定不超时的生产级 AI Bot。
开发生产级 AI Bot 最大的 4 个坑
大多数人写 Demo Bot 时直接把大模型 API 同步塞进 Webhook 请求处理器里,一上线就遇到 平台 3 秒超时重试轰炸、一条问题被回复 3 遍、群聊上下文串线 等故障。
生产级 Bot 通用架构
text
[IM 平台 Webhook (飞书 / Telegram / Discord / Slack)]
│ 1. 校验签名 / Token + event_id 幂等去重
│ 2. 立即返回 HTTP 200 OK(耗时 < 100ms,防平台重试!)
▼
[异步任务队列 / 后台 Worker]
│ 3. 发送占位消息「思考中...」拿到 message_id
│ 4. 流式请求 LLM(每 600ms 节流 editMessage 更新同一条消息)
│ 5. 调用工具 / 查询知识库(带超时与异常兜底提示)
▼
[按 (platform, chat_id, thread_id) 隔离保存会话历史]
Node.js / TypeScript 核心防重与流式节流示例
typescript
const processedEvents = new Set<string>();
export async function handleWebhook(req: Request) {
const payload = await req.json();
const eventId = payload.header?.event_id ?? String(payload.update_id);
// 1. 幂等去重:防止平台超时重发导致 AI 重复回复
if (processedEvents.has(eventId)) {
return Response.json({ ok: true, deduplicated: true });
}
processedEvents.add(eventId);
// 2. 立即 ack,异步执行耗时的模型推理
void processBotReplyAsync(payload).catch((err) => {
console.error('Bot async worker error:', err);
});
return Response.json({ ok: true });
}
各平台差异与必调参数
| 平台 | 接收方式推荐 | 流式体验优化方案 | 群聊防刷屏要点 |
|---|---|---|---|
| 飞书 (Feishu/Lark) | 长连接 WebSocket(免公网 IP)或 Webhook | 发送卡片后调用 PATCH /im/v1/messages/:id 刷新卡片内容 | 仅响应 mentions 含机器人的 im.message.receive_v1 事件 |
| Telegram | Webhook + secret_token 校验 | sendMessageDraft / 节流调用 editMessageText | 群组开启 Privacy Mode 或仅拦截 @bot_name / / 指令 |
| Discord | Gateway Bot 或 Interactions HTTP | 先 deferReply()(获得 15 分钟窗口),再 editReply() | 优先用 Slash Command /ask + Thread 隔离长对话 |
| 企业微信 | 回调 URL AES 加解密 | 被动回复先回空串,异步走应用消息主动推送 API | 注意 MsgId 去重窗口与 Markdown 子集兼容限制 |
