AI 智能体消息通道分层设计笔记
核心分三层:消息接入、会话队列并发、消息接出,外加 AI 时代开发思路建议。
消息通道架构图
一、消息接入层
1.1 核心职责
各平台(飞书、钉钉、企业微信)通过 Webhook 向你的服务推送消息事件,接入层的任务是把这些格式各异的事件统一成系统内部可以处理的标准格式。
1.2 消息抽象层(重点)
不同平台的消息结构差异巨大——飞书有自己的 event_type,钉钉有自己的 msgtype,企业微信又一套。如果直接把原始格式往下传,业务逻辑层就要写很多 if platform == 'feishu' 之类的判断,维护噩梦。
解决思路是定义一个统一消息结构,例如:
{
"platform": "feishu",
"session_id": "u_xxx",
"user_id": "u_abc",
"msg_type": "text | image | file",
"content": "...",
"attachments": [{ "file_id": "...", "file_type": "pdf" }],
"timestamp": 1700000000
}所有平台的原始事件都由各自的适配器转换成这个结构,下游 AI 处理逻辑只看这个统一结构。
1.3 文件下载处理(重点)
这是最容易踩坑的地方。平台上的文件(图片、附录、语音)不能直接用 URL 访问,必须用平台分配的 Token 鉴权后下载,否则会返回 403。
正确流程:
- 从事件中取出
file_id - 调用平台的文件下载 API(携带 access_token)
- 下载到本地或云存储,得到真实路径
- 把本地路径写入统一消息结构,再向下传递
二、会话队列并发层
2.1 核心设计原则
| 场景 | 策略 |
|---|---|
| 同一会话的多条消息 | 串行排队处理 |
| 不同会话之间 | 隔离并发处理 |
| 整体调用量 | 限流保护 |
2.2 同一会话串行排队
用户在一个对话里连发多条消息(“帮我分析一下” → “再细化一下” → “改个格式”),如果并发处理,AI 会乱序响应,上下文也会混乱。
实现方式:以 session_id(或用户 ID)为 Key,每个 Key 对应一个独立队列,队列内部严格 FIFO 串行消费。
2.3 不同会话隔离并发
A 用户的请求在处理,不应该阻塞 B 用户。各 session 队列之间相互独立、平行消费,这样系统整体吞吐量才能随用户数线性扩展。
2.4 限流保护
AI 服务(无论是自部署还是第三方 API)都有并发限制,超载会报错或影响质量。限流策略通常在两层设置:
- 队列入口:同时在处理的 session 数量上限
- AI 调用:每秒/每分钟调用次数上限,超出则排队等待或返回友好提示
三、消息接出层
3.1 文本消息
最简单,直接调用平台的发送消息 API,传入 session_id 和文本内容即可。需要注意各平台 Markdown/富文本语法不同,同样的格式在飞书和企业微信可能渲染效果不一样,需要做格式适配。
3.2 文件消息(重点)
AI 生成的文件(数据报告、图表、Excel)不能直接作为附件发送,必须先走一遍上传流程:
- AI 生成文件,保存到临时路径
- 调用平台的文件上传 API,上传文件
- 获得平台返回的
file_key/media_id - 用这个 key 构造”文件消息”发送给用户
这个流程和接入层的文件下载是对称的——下载要鉴权,上传要先拿 key,都是平台对文件的管控机制。
四、AI 时代的开发思路建议
不必对每个平台的 API 细节死记硬背,关键是理解三个核心原理,然后借助 AI 工具快速落地:
| 核心原理 | 一句话总结 |
|---|---|
| 消息抽象 | 用统一结构屏蔽平台差异,下游逻辑只看抽象层 |
| 会话队列 | 同会话串行保上下文,跨会话并发保吞吐 |
| 文件特殊处理 | 收文件要鉴权下载,发文件要先上传拿 key |
开发节奏建议:说清需求 → 快速出初版 → 跑通主流程 → 边测边调细节。平台 API 的签名方式、字段命名这些细节,遇到了查文档或问 AI,不需要提前全部记住。