跳到主要内容

网关内部

消息网关是连接 Hermes 到 14+ 个外部消息平台的长期运行进程，通过统一架构。

关键文件​

文件用途
gateway/run.pyGatewayRunner — 主循环、斜杠命令、消息分发（约 9,000 行）
gateway/session.pySessionStore — 对话持久化和会话密钥构造
gateway/delivery.py到目标平台/频道的出站消息传递
gateway/pairing.py用于用户授权的 DM 配对流程
gateway/channel_directory.py将聊天 ID 映射到人类可读名称用于 cron 传递
gateway/hooks.py钩子发现、加载和生命周期事件分发
gateway/mirror.py用于 send_message 的跨会话消息镜像
gateway/status.py用于 profile-scoped 网关实例的令牌锁管理
gateway/builtin_hooks/始终注册的钩子（例如 BOOT.md 系统提示钩子）
gateway/platforms/平台适配器（每个消息平台一个）

架构概述​

┌─────────────────────────────────────────────────┐
│                 GatewayRunner                     │
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Telegram  │  │ Discord  │  │  Slack   │  ...  │
│  │ Adapter   │  │ Adapter  │  │ Adapter  │       │
│  └─────┬─────┘  └─────┬────┘  └────┬────┘       │
│        │              │              │             │
│        └──────────────┼──────────────┘             │
│                       ▼                            │
│              _handle_message()                     │
│                       │                            │
│          ┌────────────┼────────────┐               │
│          ▼            ▼            ▼               │
│   Slash command   AIAgent      Queue/BG            │
│    dispatch       creation     sessions            │
│                       │                            │
│                       ▼                            │
│              SessionStore                          │
│           (SQLite persistence)                      │
└─────────────────────────────────────────────────┘

消息流​

当消息从任何平台到达时：

  1. 平台适配器 接收原始事件，将其规范化为 MessageEvent
  2. 基础适配器 检查活跃会话守卫
  3. GatewayRunner._handle_message() 接收事件
  4. 响应 通过平台适配器发送回去

会话密钥格式​

会话密钥编码完整路由上下文：

agent:main:{platform}:{chat_type}:{chat_id}

例如：agent:main:telegram:private:123456789

两级消息守卫​

当 Agent 正在运行时，传入消息通过两个顺序守卫：

  1. 第一级 — 基础适配器：gateway/platforms/base.py：检查 _active_sessions。如果会话活跃，队列消息并设置中断事件。
  2. 第二级 — 网关运行器：gateway/run.py：检查 _running_agents。拦截特定命令（/stop、/new、/queue、/status、/approve、/deny）。

授权​

网关使用多层授权检查，按顺序评估：

  1. 每个平台的全部允许标志 — 如果设置，该平台所有用户都被授权
  2. 平台允许列表 — 逗号分隔的用户 ID
  3. DM 配对 — 经认证的用户可以通过配对码配对新用户
  4. 全局全部允许 — 如果设置，所有平台所有用户都被授权
  5. 默认：拒绝 — 未授权用户被拒绝

DM 配对流程​

Admin: /pair
Gateway: "Pairing code: ABC123. Share with the user."
New user: ABC123
Gateway: "Paired! You're now authorized."

斜杠命令分发​

所有斜杠命令通过相同的解析管道：

  1. resolve_command() 映射输入到规范名称（处理别名、前缀匹配）
  2. 检查规范名称是否在 GATEWAY_KNOWN_COMMANDS 中
  3. 处理程序分发

平台适配器​

每个消息平台在 gateway/platforms/ 中有适配器：

gateway/platforms/
├── base.py              # BaseAdapter — 所有平台共享逻辑
├── telegram.py          # Telegram Bot API
├── discord.py           # Discord bot via discord.py
├── slack.py             # Slack Socket Mode
├── whatsapp.py          # WhatsApp Business Cloud API
├── signal.py            # Signal via signal-cli REST API
├── matrix.py            # Matrix via mautrix
├── mattermost.py        # Mattermost WebSocket API
├── email.py             # Email via IMAP/SMTP
├── sms.py               # SMS via Twilio
├── dingtalk.py          # DingTalk WebSocket
├── feishu.py            # Feishu/Lark WebSocket or webhook
├── wecom.py             # WeCom (WeChat Work) callback
├── weixin.py            # Weixin (personal WeChat) via iLink Bot API
├── bluebubbles.py       # Apple iMessage via BlueBubbles macOS server
├── qqbot.py             # QQ Bot (Tencent QQ) via Official API v2
├── webhook.py           # Inbound/outbound webhook adapter
├── api_server.py        # REST API server adapter
└── homeassistant.py     # Home Assistant conversation integration

钩子​

网关钩子是响应生命周期事件的 Python 模块：

事件触发时机
gateway:startup网关进程启动
session:start新对话会话开始
session:end会话完成或超时
session:reset用户用 /new 重置会话
agent:startAgent 开始处理消息
agent:stepAgent 完成一次工具调用迭代
agent:endAgent 完成并返回响应
command:*任何斜杠命令被执行

相关文档​