# Gateway 架构设计

**更新日期：** 2026-03-12

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录已确认的架构设计

---

## 架构概述

Gateway 采用分层架构：

```
┌─────────────────────────────────────────────────────────────┐
│ API 层（HTTP 接口）                                          │
│ - 供外部 Agent 调用                                          │
│ - RESTful API                                               │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│ Core 层（核心服务）                                          │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Lifecycle（生命周期管理）                            │  │
│  │ - Trace 注册和元数据管理                             │  │
│  │ - Workspace 管理                                    │  │
│  │ - 配置热重载                                         │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Conversations（对话管理）                            │  │
│  │ - 对话管理                                           │  │
│  │ - 消息历史存储                                       │  │
│  │ - 消息队列和调度                                     │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Routing（消息路由）                                  │  │
│  │ - 飞书消息接收和转发                                 │  │
│  │ - 消息路由规则管理                                   │  │
│  │ - Agent 联系人列表维护                               │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 模块结构

```
gateway/
├── core/                          # 核心服务层（内部接口）
│   ├── lifecycle/                 # Agent 生命周期管理
│   │   ├── trace_manager.py      # Trace 注册和元数据管理
│   │   ├── workspace_manager.py  # Workspace 管理
│   │   └── config_watcher.py     # 配置热重载
│   │
│   ├── conversations/             # 对话管理
│   │   ├── conversation_manager.py  # 对话管理
│   │   ├── message_store.py         # 消息历史存储
│   │   └── message_queue.py         # 消息队列和调度
│   │
│   ├── routing/                   # 消息路由
│   │   ├── router.py              # 消息路由核心
│   │   ├── feishu_connector.py   # 飞书集成
│   │   └── contact_manager.py    # 联系人管理
│   │
│   └── registry.py                # Agent 注册表（保留，兼容旧代码）
│
├── api/                           # HTTP API 层（外部接口）
│   ├── lifecycle_api.py           # 生命周期管理 API
│   ├── conversations_api.py       # 对话管理 API
│   └── routing_api.py             # 消息路由 API
│
├── enterprise/                    # 企业功能（可选）
│   ├── auth/                      # 认证授权
│   ├── audit/                     # 审计日志
│   └── multi_tenant/              # 多租户
│
└── client/                        # 客户端 SDK
    └── python/                    # Python SDK
        ├── client.py              # GatewayClient
        ├── tools.py               # 工具函数
        └── cli.py                 # CLI 工具
```

---

## 核心模块

### Lifecycle（生命周期管理）

**职责：**
- Trace 注册和元数据管理
- Workspace 管理
- 配置热重载

**实现位置：**
- `gateway/core/lifecycle/trace_manager.py`
- `gateway/core/lifecycle/workspace_manager.py`
- `gateway/core/lifecycle/config_watcher.py`

### Conversations（对话管理）

**职责：**
- 对话管理
- 消息历史存储
- 消息队列和调度

**实现位置：**
- `gateway/core/conversations/conversation_manager.py`
- `gateway/core/conversations/message_store.py`
- `gateway/core/conversations/message_queue.py`

### Routing（消息路由）

**职责：**
- 飞书消息接收和转发
- 消息路由规则管理
- Agent 联系人列表维护

**实现位置：**
- `gateway/core/routing/router.py`
- `gateway/core/routing/feishu_connector.py`
- `gateway/core/routing/contact_manager.py`

---

## 两种接入方式

### 内部 Agent 接入

**特点：**
- 和 Gateway 运行在同一台机器
- 使用我们的 Agent 框架
- 直接调用 Core 层的 Python 接口

**使用方式：**
```python
# 直接导入 Core 层模块
from gateway.core.conversations import ConversationManager

manager = ConversationManager()
messages = manager.get_messages(conversation_id)
```

### 外部 Agent 接入

**特点：**
- 运行在不同机器或使用其他框架
- 通过 HTTP API 接入
- 使用 Client SDK 简化调用

**使用方式：**
```python
# 使用 Client SDK
from gateway.client.python import GatewayClient

client = GatewayClient("http://gateway-host:8000")
messages = client.get_messages(conversation_id)
```

---

## 企业功能（可选）

### 认证授权（Auth）
- API Key 认证
- OAuth 集成
- 权限控制
- 单点登录

### 审计日志（Audit）
- 操作日志记录
- 消息审计
- 合规报告

### 多租户（Multi-Tenant）
- 租户隔离
- 资源配额
- 计费管理

**说明：**
- 作为可选模块，独立于核心功能
- 具体实现方式待确认

---

## 相关文档

- [需求规划](./requirements.md)：已确认的需求和功能范围
- [核心模块文档](./core/)：各核心模块详细文档
- [API 文档](./api/)：HTTP API 参考
- [Client SDK 文档](./client/)：客户端 SDK 使用指南
- [设计决策](./decisions.md)：架构决策记录