七、消息平台 Gateway

gateway = 多平台 adapter + session 路由 + 命令分发 + Agent 执行桥 + 消息回传

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

工作原理

• 1、消息适配：平台 adapter 将平台（如 WhatsApp）消息适配成 MessageEvent
• 2、Session 定位：平台 + chat + 用户 + thread 定位到session
• 3、命令优先处理：command 优先被 gateway 前置控制层处理
• 4、运行 Agent：构建 context，AIAgent.run_conversation()是同步阻塞，所以需要在gateway中注册管理进度、streaming、interrupt、approval等事件
• 5、回写结果：adapter 对 Agent 返回结果适配，发送回平台

Slash command dispatch：是 gateway 前置控制层，先解析、跑 hook、命中 handler。没有被 gateway 命令系统消费的内容，才会进入 Agent。

Queue/BG sessions：Queue是在同一个 session 中按顺序聊；BG 是另开一个后台 Agent 并发聊。

亮点

• 并发控制

  1、用户消息排队处理：向一个已经在运行 session 发生 user 消息，不会再起一个并发 agent，而是消息进入队列顺序处理
  
  2、command优先处理：`/approve`, `/stop` 等命令绕过消息队列，被gateway 前置控制层优先处理命令。避免死锁 
  

参考

• Gateway Internals
• Messaging Gateway