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. 反向连接模式（Reverse Connection）

日期：2026-03-04

背景：

PC 端 Agent 通常没有公网 IP
需要支持 NAT 穿透

决策：

PC Agent 主动连接到 Gateway（WebSocket）
Gateway 维护连接映射，路由消息到目标 Agent

理由：

无需公网 IP：PC Agent 不需要暴露端口
简单可靠：避免 NAT 穿透的复杂性
实时性：WebSocket 保持长连接，消息实时送达

替代方案：

方案 A：P2P 直连
- 缺点：需要 NAT 穿透，实现复杂
方案 B：轮询模式
- 缺点：延迟高，资源消耗大

3. 心跳机制

日期：2026-03-04

背景：

需要检测 Agent 在线状态
WebSocket 连接可能静默断开

决策：

Agent 每 30 秒发送心跳
Gateway 超过 60 秒未收到心跳则标记为离线
自动清理过期连接

理由：

及时检测：快速发现断线 Agent
资源管理：自动清理无效连接
简单可靠：无需复杂的健康检查

参数选择：

心跳间隔 30s：平衡实时性和网络开销
超时时间 60s：允许一次心跳丢失

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 协议

相关文档