Gateway 与平台适配器一套循环接入十五个平台导读同一个 agentCLI 里能用Telegram、Discord、企业微信里也能用——核心循环一行没变变的只是消息从哪来、回复往哪送。本文拆解 Hermes 架构的 Gateway 与平台适配器会话隔离、统一消息格式、并发串行化、断线重连一套机制打通 15 平台。从最笨的微信机器人说起假设你写好了自己的 agent它能在终端里和你对话、调用工具、记住上下文。一切都很美好直到你同事说“能不能让它在企业微信里也用上”最简单粗暴的想法是什么连上微信的 WebSocket死循环收消息调一次run_conversation把回复发回去。大概 40 行代码就能跑起来。但这个最笨的实现有三个致命问题。三个致命问题第一没有记忆。每条消息进来都是一次全新的对话agent 不记得你五分钟前说过什么。之前做的持久化全部白费。第二只能接微信。明天你想接 Telegram怎么办改这 40 行代码那后天接 Discord 呢每接一个平台就 fork 一份代码最后维护成本爆炸。第三并发消息。agent 正在思考的时候用户又发了一条消息。是排队处理直接丢弃还是打断当前思考三种选择背后是完全不同的设计。这三个问题就是 s12 要解决的核心。问题一session key 会话隔离先解决记忆问题。思路很简单给每个会话一个唯一标识用这个标识去数据库里拉历史。defbuild_session_key(source:SessionSource,agent_name:strmain)-str:parts[fagent:{agent_name}:{source.platform}:{source.chat_type}:{source.chat_id}]ifsource.chat_typegroup:parts.append(source.user_id)return:.join(parts)私聊的 key 长这样agent:main:wecom:dm:zhangsan群聊的 key 长这样agent:main:wecom:group:grp_001:zhangsan注意群聊的 key 里多了user_id。这意味着张三和李四在同一个群里 agent各自拥有独立的对话历史——互不干扰。这一步解决的是每条消息全新对话的问题。agent 拿到 session key从数据库加载历史继续之前的上下文。问题二MessageEvent 统一格式接下来解决只能接微信的问题。核心思路不管消息来自哪个平台进入核心循环之前先翻译成同一种格式。classMessageType(Enum):TEXTtextPHOTOphotoVOICEvoiceDOCUMENTdocumentdataclassclassSessionSource:platform:str# console, telegram, wecom, ...chat_id:strchat_type:str# dm or groupuser_id:struser_name:strdataclassclassMessageEvent:message_id:strtext:strsource:SessionSource message_type:MessageTypeMessageType.TEXT media_urls:list[str]field(default_factorylist)微信的消息、Telegram 的消息、Discord 的消息翻译完之后都是同一个MessageEvent。下游代码根本不需要知道消息来自哪个平台。这就是适配器的三职责connect连上平台_translate入站翻译平台原始消息 → MessageEventsend出站翻译agent 回复 → 平台格式每个平台适配器只做这两件翻译工作。GatewayRunner启动、路由、管理有了统一格式还需要一个东西来管理所有适配器。这就是GatewayRunner。它的工作有三件启动所有适配器connect 全部跑起来路由消息适配器收到消息 → 调handle_message→ 找到对应 session → 交给 agent管理会话session 的创建、缓存、过期两个关键设计值得注意。第一agent 实例按 session key 缓存复用。不是每条消息都创建一个新的 agent而是同一个 session 复用同一个 agent 实例。否则每条消息都要重新加载全部工具、重新初始化记忆系统。第二history 每次都从数据库重新拉取。不依赖 agent 内部记忆。为什么因为历史可能被/undo、/compress、会话过期修改过。agent 内部记忆是运行时的数据库才是权威。每次从数据库拉保证拿到的是最新状态。问题三并发消息串行化最后一个问题用户连发三条消息agent 正在思考第一条怎么办Hermes 的做法是串行化 优雅中断self._active_sessions:dict[str,asyncio.Event]{}self._pending_messages:dict[str,MessageEvent]{}一个 session 同一时间只有一个 agent 在跑新消息暂存只保留最后一条平台用户连发多条通常是补充同一个意思给正在运行的 agent 发中断信号agent._interrupt_requested True关键在优雅中断不是粗暴地杀掉任务而是停止等待流式输出跳过剩余工具填占位 tool 消息满足 API 配对要求退出循环中断后内容不丢。部分回复、已执行工具、被跳过工具的占位全部存数据库。下一轮从数据库加载完整脉络接着聊。从 Gateway 到适配器共性问题浮出水面到这里Gateway 的架构已经清楚了。但新的问题来了一个适配器容易写第二个、第三个呢接微信的时候发现消息可能被截断成半截接企业微信发现媒体 URL 是临时的过一会儿就失效接 Discord 发现同样的消息可能被重复推送。这些不是某个平台的特殊情况而是所有平台都会遇到的共性问题。s13 把这些共性机制抽出来做成一套基础设施。BasePlatformAdapter抽象基类先看抽象基类这是所有适配器的骨架classBasePlatformAdapter(ABC):def__init__(self,platform_name:str):self.platform_nameplatform_name self._on_message:Callable|NoneNone# injected by GatewayRunnerself._runningFalseabstractmethodasyncdefconnect(self)-bool:...abstractmethodasyncdefdisconnect(self):...abstractmethodasyncdefsend(self,chat_id:str,content:str)-bool:...asyncdefhandle_message(self,event:MessageEvent):ifself._on_message:awaitself._on_message(event)三个必须实现的方法连接、断开、发送。_on_message回调由 GatewayRunner 启动时注入——适配器不需要知道消息怎么处理只需要把翻译好的MessageEvent交出去。三大共性机制TextBatcher消息分片合并。微信个人号有 1500 字符截断企业微信是 4000。agent 回复长文时平台会截断成半截。TextBatcher 的规则长度 ≥ 3900接近企微截断 4000→ 等 2.0 秒大概率被截断等续片长度远小于 → 等 0.6 秒正常人打不出这么快两条独立消息实现是三个字典加任务管理每收到一条消息就重新倒计时倒计时跑完才交出去。MessageDeduplicator消息去重。按message_id去重FIFO 淘汰旧记录max_size上限 1000。防止平台重复推送导致 agent 重复响应。媒体缓存URL 是临时的。入站下载 → 解密 → 本地缓存。因为平台给的 URL 是临时的不立刻下载就过期了。出站加密 → 分块上传 → 发消息。断线重连指数退避平台连接断掉怎么办指数退避重连[2, 5, 10, 30, 60] 秒连上之后重置计数。不慌不忙越等越久避免在平台不稳定时疯狂重连打爆对方服务器。平台差异对照不同平台的差异比想象中大得多维度企业微信微信个人号协议WebSocket / HTTP 回调HTTP 长轮询35 秒超时截断4000 字符1500 字符加密AES-256-CBC 32 字节AES-128-ECB 16 字节分块512KBCDN 直传限速-0.35 秒分块间隔token-context_token 必须回传这些差异全部封装在适配器内部。核心循环看到的只有MessageEvent完全不知道背后的平台是什么。避坑两章 8 错精选两章各列了 4 个初学者常犯的错误合并精选最要命的把平台差异写进核心循环。格式转换是适配器send的事不是核心循环的事每条消息都创建新 agent。必须串行化 复用实例session key 维度不够。群聊不按 user_id 隔离张三李四共享上下文忽略消息去重。平台重复推送会让 agent 重复响应忘了消息合并。半截话直接交给 agent上下文断裂媒体 URL 过期后才下载。平台给的临时链接不立刻存就没了回复不考虑平台差异。微信个人号不支持 Markdown发过去全是乱码微信回复忘 context_token。每用户必须缓存最新 token 并回传小结Gateway 解决的是消息从哪来的问题适配器解决的是怎么接住的问题。两者合在一起让同一个 agent 核心循环接入 15 平台核心循环一行没变。下一篇预告第 10 篇执行环境抽象与定时任务。agent 不能只会被动响应还要能主动做事。你在接多平台的时候踩过最深的坑是什么欢迎在评论区聊聊。参考文献Hermes Agent 教学仓库agents/s12_gateway_architecture.py本文代码素材53287 字节真实可运行Hermes Agent 教学仓库agents/s13_platform_adapters.py本文代码素材63026 字节真实可运行Hermes Agent 教学仓库docs/zh/s12-gateway-architecture.md与docs/zh/s13-platform-adapters.mdGateway 架构、适配器模式详解源码获取如需本系列全部源码请在以下链接克隆https://gitcode.com/ganxin7932508/learn-hermes-agent.git
