# Gateway 架构设计

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

## 文档维护规范

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

---

## 整体架构

Gateway 是自研 Agent 框架的管理系统，负责 Agent 的生命周期管理和任务执行调度。

**核心定位：** 使命/职能对话系统
- 用户给 Agent 分配任务
- Agent 汇报工作、述职
- 是"管理-执行"关系

**与 IM 系统的区别：**
- IM 系统：LLM 作为主体的平等交流（协作-沟通关系）
- Gateway：用户对 LLM 的使命/职能对话（管理-执行关系）

```
                    ┌──────────────────────┐
                    │   飞书（个人助理）    │
                    │  使命/职能对话        │
                    └──────────┬───────────┘
                               │
                               │ Webhook
                               │
   ┌───────────────────────────▼───────────────────────────┐
   │              Gateway（Agent 管理系统）                 │
   │                                                        │
   │  ┌──────────────────────────────────────────────────┐ │
   │  │ Channels（外部渠道接入）                          │ │
   │  │ - 飞书集成（个人助理型）                          │ │
   │  │ - 消息路由                                        │ │
   │  └──────────────────────────────────────────────────┘ │
   │                                                        │
   │  ┌──────────────────────────────────────────────────┐ │
   │  │ Lifecycle（生命周期管理）                         │ │
   │  │ - Trace 注册和查询                               │ │
   │  │ - Workspace 管理                                 │ │
   │  │ - 配置热重载                                      │ │
   │  └──────────────────────────────────────────────────┘ │
   │                                                        │
   │  ┌──────────────────────────────────────────────────┐ │
   │  │ Executor（任务执行调度）                          │ │
   │  │ - 接收用户任务                                    │ │
   │  │ - 调度 Agent 执行                                │ │
   │  │ - 管理执行状态                                    │ │
   │  └──────────────────────────────────────────────────┘ │
   │                                                        │
   │  ┌──────────────────────────────────────────────────┐ │
   │  │ IM Client（可选）                                 │ │
   │  │ - Agent 主动通信                                  │ │
   │  └──────────────────────────────────────────────────┘ │
   └────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    IM Server                             │
│  - 所有主体（Agent、用户）的平等通信系统                    │
│  - 接入飞书（数字员工型）、微信等渠道                       │
│  - LLM 作为主体参与对话                                    │
└─────────────────────────────────────────────────────────┘
                         ↑
                         │ IM Protocol
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼────┐      ┌───▼────┐      ┌───▼────┐
   │IM Client│      │IM Client│     │IM Client│
   │(自研)   │      │(Claude  │     │(飞书数字 │
   │         │      │ Code)   │     │ 员工)   │
   └─────────┘      └─────────┘     └─────────┘
```

---

## 模块结构

```
gateway/
├── core/                          # 核心服务层（内部接口）
│   ├── channels/                  # 外部渠道接入
│   │   ├── feishu/                # 飞书集成
│   │   │   ├── connector.py       # 飞书连接器
│   │   │   ├── webhook.py         # Webhook 处理
│   │   │   └── api.py             # 飞书 API 调用
│   │   ├── router.py              # 消息路由
│   │   └── channel_manager.py     # 渠道管理
│   │
│   ├── lifecycle/                 # Agent 生命周期管理
│   │   ├── trace_manager.py      # Trace 注册和查询
│   │   ├── workspace_manager.py  # Workspace 管理
│   │   └── config_watcher.py     # 配置热重载
│   │
│   └── executor/                  # 任务执行调度
│       ├── task_manager.py        # 任务管理
│       ├── scheduler.py           # 调度器
│       └── execution_context.py   # 执行上下文
│
├── api/                           # HTTP API 层（外部接口）
│   ├── lifecycle_api.py           # 生命周期管理 API
│   ├── executor_api.py            # 任务执行 API
│   └── webhook_api.py             # Webhook API（飞书等）
│
└── client/                        # 客户端 SDK
    └── python/                    # Python SDK
        ├── client.py              # GatewayClient
        └── cli.py                 # CLI 工具
```

---

## 核心模块

### Channels（外部渠道接入）

**职责：**
- 接入飞书等外部渠道（个人助理型 Agent）
- 消息路由（飞书用户 ID → Trace ID）
- 自动创建 Trace（首次对话）

**实现位置：**
- `gateway/core/channels/feishu/connector.py`
- `gateway/core/channels/router.py`
- `gateway/core/channels/channel_manager.py`

**详细文档：** [channels.md](./core/channels.md)

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

**职责：**
- 调用 Agent 框架创建/查询 Trace
- 管理 Workspace（创建、引用计数、清理）
- 监听配置变化并热重载

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

**详细文档：** [lifecycle.md](./core/lifecycle.md)

### Executor（任务执行调度）

**职责：**
- 接收用户分配的任务
- 调度 Agent 框架执行任务
- 管理任务执行状态和结果

**实现位置：**
- `gateway/core/executor/task_manager.py`
- `gateway/core/executor/scheduler.py`
- `gateway/core/executor/execution_context.py`

**详细文档：** [executor.md](./core/executor.md)

---

## 两种对话模式

### 使命/职能对话（通过 Gateway）

**场景：**
- 用户通过管理界面给 Agent 分配任务
- Agent 定期向用户汇报工作进度
- 用户查询 Agent 的执行状态

**消息流转：**
```
用户 → Gateway API → Executor → Agent 框架执行 → Executor → Gateway API → 用户
```

**特点：**
- 用户是管理者，Agent 是执行者
- 任务导向，有明确的目标和结果
- 通过 Gateway 的 API 接口

### 主体间交流（通过 IM 系统）

**场景：**
- 用户在飞书上和 Agent 聊天（平等对话）
- Agent A 请求 Agent B 协助完成任务
- Agent 主动向用户发送通知

**消息流转：**
```
用户/Agent A → IM Client → IM Server → IM Client → Agent B
```

**特点：**
- 所有参与者都是平等主体
- 协作导向，强调沟通和交流
- 通过 IM Server 的消息系统

---

## 接入方式

### 内部 Agent 接入

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

**使用方式：**
```python
# 直接导入 Core 层模块
from gateway.core.lifecycle import TraceManager
from gateway.core.executor import TaskManager

trace_mgr = TraceManager()
task_mgr = TaskManager()

# 创建 Trace
trace_id = trace_mgr.create_trace(workspace_id="user_001", agent_type="personal_assistant")

# 提交任务
task_id = task_mgr.submit_task(trace_id, task_description="分析销售数据")
```

### 外部 Agent 接入

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

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

client = GatewayClient("http://gateway-host:8000")

# 创建 Trace
trace_id = client.create_trace(workspace_id="user_001", agent_type="personal_assistant")

# 提交任务
task_id = client.submit_task(trace_id, task_description="分析销售数据")
```

---

## 与 IM 系统的集成

Gateway 管理的 Agent 可以通过 IM Client 参与 IM 系统的通信：

1. **Agent 执行过程中需要协作**：
   - Agent 通过 IM Client 发送消息给其他 Agent
   - 其他 Agent 通过 IM 回复

2. **Agent 主动通知用户**：
   - Agent 通过 IM Client 发送消息给用户
   - 用户在飞书等渠道收到消息

3. **消息历史管理**：
   - IM Client 存储在 Workspace 内
   - 管理该 Agent 的所有 IM 对话历史

---

## 相关文档

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