# 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 可选

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

**替代方案**：
- 方案 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 间隔）

**理由**：
1. **维护成本低**：无需管理长连接、断线重连
2. **场景匹配**：任务导向协作不需要毫秒级实时性
3. **调试简单**：标准 HTTP，易于监控和排查
4. **已有基础**：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/

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

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

---

### 5. 消息格式采用 MAMP 协议

**日期**：2026-03-04

**背景**：
- 需要与外部 Agent 系统通信
- 需要支持多模态内容

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

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

**详细设计**：见 [MAMP 协议](../../../docs/research/a2a-mamp-protocol.md)

---

## 相关文档

- [Agent Core 设计决策](../../agent/docs/decisions.md)
- [架构设计](./architecture.md)
- [A2A IM 系统](../../../docs/a2a-im.md)