02 - 多平台消息网关架构

学习目标

本章聚焦 Hermes Agent 的多平台消息网关架构。你将了解：

• 单一网关进程如何管理 19 个平台适配器
• 会话生命周期管理与 DM 配对安全
• 跨平台消息投递与语音备忘录转录
• 平台注册与发现机制

前置知识

本章涉及多 Agent 路由的通用原理，建议先阅读：

• 多 Agent 路由与隔离

下文直接聚焦 Hermes 的网关具体实现。

---

项目实践

单一网关进程 + 多适配器

gateway/run.py（~18556 行）是消息网关的核心，采用单进程多适配器架构：

支持的平台：Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant、Matrix、Mattermost、Email、SMS、DingTalk（钉钉）、WeCom（企业微信）、Weixin（微信）、Feishu（飞书）、QQBot、Yuanbao（元宝）、Webhook、API Server、BlueBubbles。

会话生命周期管理

gateway/session.py 负责会话生命周期：

• 每个平台消息到达时，通过 session key 路由到对应会话
• 会话持久化到 SQLite（hermes_state.py）
• 支持跨平台会话连续性（同一用户从不同平台发消息可进入同一会话）

DM 配对安全

gateway/pairing.py 实现 DM 配对安全机制：

• 直接消息（DM）默认共享 main session key
• 可通过配置隔离为 per-peer 或 per-channel-peer
• 配对流程确保只有授权用户能与 Agent 对话

跨平台消息投递

gateway/delivery.py 负责跨平台消息投递：

• 将 Agent 回复格式化为目标平台的消息格式
• 支持语音备忘录转录（平台发送的语音消息自动转为文本）
• 多平台广播（同一消息投递到多个平台）

平台注册与发现

gateway/platform_registry.py 实现平台注册与发现：

• 每个平台适配器在 import 时自动注册
• 通过配置文件启用/禁用特定平台
• 平台适配器按需加载依赖，避免启动时加载所有平台库

---

问题与规避

平台依赖膨胀

问题：19 个平台适配器的依赖库各不相同，全部安装会导致依赖膨胀。

对策：平台适配器按需加载依赖。未启用的平台不 import 其依赖库。

跨平台会话连续性

问题：同一用户从 Telegram 和微信发消息，如何进入同一会话？

对策：通过 identity links 关联同一人的多渠道身份。用户可配置是否将多渠道消息合并到同一会话。

---

设计取舍

单一网关 vs 多微服务

方案	优势	代价
单一网关（Hermes）	部署简单、会话状态统一管理、跨平台功能自然	单进程资源消耗大、故障影响所有平台
多微服务	每个平台独立部署、故障隔离	跨平台会话连续性需要额外协调

Hermes 选择单一网关进程，因为其目标场景是个人/小团队部署，运维复杂度比水平扩展更重要。

---

参考来源

• 源码验证：gateway/run.py、gateway/session.py、gateway/delivery.py、gateway/pairing.py、gateway/platform_registry.py