学习指南 / 第十一章
第十一章

消息网关

🎧 语音播放

理解 Hermes 如何同时服务多个消息平台

🎯 本章目标

  • 理解网关的架构设计
  • 掌握平台适配器模式
  • 理解消息路由机制

📚 前置知识

  • 第五章的 Agent 循环

💡 学完收获

  • 能够接入新消息平台
  • 理解统一消息处理的好处

11.1 为什么需要网关？

CLI 模式只能本地使用。网关让 Hermes 可以远程服务：

📱 Telegram
随时随地对话
💬 Discord
团队协作
📮 Slack
企业集成

11.2 架构概览

网关采用适配器模式，每平台一个适配器：

网关架构 Gateway Architecture

flowchart TD subgraph Platforms["📱 消息平台"] T["Telegram"] D["Discord"] S["Slack"] W["WhatsApp"] end Platforms --> A["🎛️ Gateway"] A --> B["📝 统一格式"] B --> C["🧠 AIAgent"] C --> D2["📤 响应"] D2 --> A A --> Platforms style A fill:#dbeafe,stroke:#2563eb style C fill:#d1fae5,stroke:#059669

11.3 平台适配器

每个平台有一个适配器：

📱 telegram.py
消息格式转换
💬 discord.py
消息格式转换
📮 slack.py
消息格式转换
📤 base.py
基类定义

11.4 统一消息格式

不同平台的消息格式不同，网关统一转换：

📋 GatewayMessage
class GatewayMessage:
    text: str        # 消息文本
    sender_id: str    # 发送者 ID
    platform: str     # 来源平台
    session_id: str   # 会话 ID
    metadata: dict   # 平台特定数据

11.5 会话管理

网关通过 session_id 区分不同对话：

📱 Telegram
session_id = f"telegram:{user_id}"
💬 Discord
session_id = f"discord:{server_id}:{user_id}"
💡 为什么 session_id 要包含平台？

同一个 user_id 可能在不同平台都和 Hermes 对话。用 platform:user_id 可以确保不同平台的会话是独立的。

11.6 启动网关

Terminal
# 启动 Telegram Bot
hermes gateway telegram --api-key $TELEGRAM_BOT_TOKEN

# 启动 Discord Bot  
hermes gateway discord --token $DISCORD_BOT_TOKEN

# 同时运行多个平台
hermes gateway telegram --api-key $TOKEN &
hermes gateway discord --token $TOKEN &

📚 本章总结

本章重点：

  • 网关是统一的消息入口
  • 平台适配器处理差异化
  • session_id 实现多用户多会话
  • 适配器模式便于扩展新平台

一句话记忆点： 网关 = 消息的"中央车站"——所有平台的消息都在这里汇合

延伸思考

  1. 如果 Telegram 消息格式变了，会影响 Gateway 核心代码吗？
  2. 如何保证消息顺序？
  3. 如果某个平台 API 下線了，如何快速切换？