Gateway 设计决策

文档说明

本文档记录 Gateway 模块的架构决策、设计权衡和实现选择。

决策记录

1. Gateway 与 Agent Core 并列而非嵌套

日期：2026-03-04

背景：

Gateway 负责 Agent 注册、消息路由、在线状态管理
Agent Core 负责 Agent 执行引擎、工具系统、记忆管理
两者功能独立，可以分别部署

决策：

Gateway 和 Agent Core 作为并列的顶层模块（gateway/ 和 agent/）
单向依赖：Gateway 可以依赖 Agent Core，但 Agent Core 不依赖 Gateway
Agent Core 可以独立运行（本地 Agent），Gateway 可选

理由：

解耦：两个模块职责清晰，可以独立开发和部署
灵活性：支持多种部署模式（单机、分离、分布式）
可维护性：模块边界清晰，便于理解和维护

替代方案：

方案 A：Gateway 作为 agent/gateway/（嵌套）
- 缺点：暗示 Gateway 是 Agent 的子模块，但实际上 Gateway 是独立的服务
方案 B：Gateway 作为 integrations/gateway/
- 缺点：Gateway 不是第三方集成，而是核心基础设施

2. 消息接收采用 Webhook 而非 WebSocket

日期：2026-03-05

背景：

需要将 Gateway 收到的消息推送给目标 Agent
PC 端 Agent 通常没有公网 IP，需要反向连接机制
场景是任务协作，而非实时聊天

决策：

采用 Webhook 推送（而非 WebSocket 长连接）
Agent 注册时提供 webhook_url
Gateway 收到消息后，HTTP POST 到 webhook_url
Agent 发送心跳维持在线状态（HTTP POST，30s 间隔）

理由：

维护成本低：无需管理长连接、断线重连
场景匹配：任务导向协作不需要毫秒级实时性
调试简单：标准 HTTP，易于监控和排查
已有基础：Agent 已运行 FastAPI 服务，添加 webhook 端点极简单

被放弃的方案：

WebSocket 长连接：实时性好，但维护成本高（需处理重连、心跳保活、连接池），对我们的场景是过度设计
HTTP 轮询：无需长连接，但浪费资源，延迟不可控

影响：

gateway/core/client.py（旧 WebSocket 客户端）待清理
gateway/core/router.py WebSocket 端点可移除
Registry 简化为只存储 webhook_url，不存储连接对象

4. Enterprise 作为 Gateway 扩展层

日期：2026-03-04

背景：

Enterprise 层提供认证、审计、多租户等功能
个人部署不需要 Enterprise 功能

决策：

Enterprise 作为 Gateway 的可选扩展层
通过中间件模式集成（auth.py, audit.py, rate_limit.py）
文档放在 gateway/docs/enterprise/

理由：

可选部署：个人用户可以只部署 Gateway，不部署 Enterprise
清晰分层：Enterprise 扩展 Gateway 功能，关系明确
易于扩展：中间件模式便于添加新功能

替代方案：

方案 A：Enterprise 作为独立顶层模块
- 缺点：增加部署复杂度，Enterprise 主要扩展 Gateway
方案 B：Enterprise 功能内置到 Gateway
- 缺点：个人用户也要承担 Enterprise 的复杂度

5. 消息格式采用 MAMP 协议

日期：2026-03-04

背景：

需要与外部 Agent 系统通信
需要支持多模态内容

决策：

采用 MAMP（Minimal Agent Message Protocol）
消息格式参考 Anthropic SDK
支持 conversation_id 管理对话

理由：

简洁：最小化协议，易于实现
兼容：与 Anthropic SDK 格式对齐
扩展性：支持多模态和元数据

详细设计：见 MAMP 协议

相关文档