# Gateway 需求规划

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

## 文档维护规范

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

---

## 核心理解

### Agent 的本质

基于 Agent Core 架构（详见 `../../agent/docs/architecture.md`）：

- **Agent = Trace 数据 + Workspace**
- **无状态执行引擎**：每次调用都是"续跑 trace"
- **动态并发**：
  - 1000 个用户可能有 1000 份 Trace 数据和 Workspace
  - 但运行中的 Agent 实例是动态的，预计 ~10 个并发
- **Workspace 共享**：主 Agent 创建的子 Agent 可以共享同一个 Workspace

### Gateway 的定位

**核心定位：** 使命/职能对话系统

- 用户给 Agent 分配任务
- Agent 汇报工作、述职
- 是"管理-执行"关系

**与 IM 系统的区别：**
- **IM 系统**：LLM 作为主体的平等交流（协作-沟通关系）
  - Agent 之间对等通信
  - 用户和 Agent 平等对话
  - 可以接入飞书、微信等任何渠道
- **Gateway**：用户对 LLM 的使命/职能对话（管理-执行关系）
  - 用户分配任务给 Agent
  - Agent 执行任务并汇报
  - 通过 API 接口调用

---

## 三大核心模块

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

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

**关键点：**
- 只用于个人助理型 Agent 的飞书接入
- 数字员工型 Agent 的飞书接入通过 IM Server
- 使用不同的飞书账号区分两种类型
- 首次对话自动创建 Trace 和 Workspace

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

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

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

**关键点：**
- Trace 元数据由 Agent 框架管理，Gateway 不维护副本
- 多个 Trace 可以共享一个 Workspace（主 Agent + 子 Agent）
- Workspace 需要引用计数机制
- 配置变更时热重载，不影响正在运行的 Trace

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

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

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

**关键点：**
- 支持同步和异步任务执行
- 管理任务队列（个人助理型 Agent）
- 提供任务状态查询接口
- 与 Channels 模块集成，处理来自飞书的任务

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

---

## 两种 Agent 类型

### 类型 1：个人助理型 Agent

**特征：**
- 每个用户有独立的 Trace + Workspace
- 聊天历史隔离
- 可以并发处理多个用户的任务

**使用场景：**
- 个人助理
- 专属客服
- 个性化服务

**飞书接入：**
- 通过 Gateway Channels 模块接入
- 使用个人助理飞书账号
- 飞书用户 ID → Trace ID（一对一映射）
- 首次对话自动创建 Trace

**任务调度：**
- 每个用户的任务独立调度
- 支持并发执行（不同用户的任务）
- 同一用户的任务需要排队

**消息流转：**
```
飞书用户 → Gateway Channels → Executor → Agent 执行 → Executor → Channels → 飞书
```

### 类型 2：数字员工型 Agent

**特征：**
- 所有用户共享一个 Trace
- 每个用户有独立的对话（通过 IM 系统）
- 串行工作（按全局消息顺序处理）

**使用场景：**
- 前台接待
- 客服中心
- 工单处理

**飞书接入：**
- 通过 IM Server 接入（不通过 Gateway）
- 使用数字员工飞书账号
- 所有用户消息 → 同一个 Trace
- 消息队列由 IM Client 管理

**任务调度：**
- 所有任务串行处理
- 任务队列由 IM Client 管理
- Agent 主动查看和处理任务

**消息流转：**
```
飞书用户 → IM Server → IM Client → Agent 主动查看 → Agent 执行 → IM Client → IM Server → 飞书
```

---

## 两种接入方式

### 内部 Agent（同设备，我们的框架）

**特点：**
- 和 Gateway 运行在同一台机器
- 使用我们的 Agent 框架
- 直接调用 Gateway 的内部接口（Python 函数调用）

**不需要：**
- HTTP Client
- Webhook
- 网络通信

**使用方式：**
```python
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（其他设备/其他框架）

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

**需要：**
- HTTP Client SDK
- Webhook 接收消息
- 网络通信

**使用方式：**
```python
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 系统的通信：

### Agent 主动通信

- Agent 执行任务过程中需要协作 → 通过 IM Client 发送消息给其他 Agent
- Agent 需要通知用户 → 通过 IM Client 发送消息给用户（飞书等渠道）

### 消息历史管理

- IM Client 存储在 Workspace 内
- 管理该 Agent 的所有 IM 对话历史
- 联系人列表、消息记录等

### 两种对话模式的协同

**个人助理型 Agent 的典型场景：**

1. **用户通过飞书发送任务**（使命/职能对话）
   - 飞书 → Gateway Channels → Executor → Agent 执行

2. **Agent 执行任务时通过 IM 与其他 Agent 协作**（主体间交流）
   - Agent → IM Client → IM Server → 其他 Agent

3. **Agent 完成任务后通过飞书回复用户**（使命/职能对话）
   - Agent 执行完成 → Executor → Channels → 飞书

**说明：** 同一个 Agent 可以同时参与两种对话模式

---

## 暂不实现的功能

### 能力 Node

**说明：**
- 类似 OpenClaw 的 Node 机制（跨设备能力调用）
- 当前阶段暂不实现
- 未来如有需求再考虑

### 其他外部渠道

**说明：**
- 当前只实现飞书接入（个人助理型）
- 微信、钉钉等其他渠道暂不实现
- 未来可以参考飞书集成方式扩展

---

## 相关文档

- [Agent Core 架构](../../agent/docs/architecture.md)：Agent 框架核心设计
- [Gateway 架构](./architecture.md)：Gateway 架构设计
- [核心模块文档](./core/)：各核心模块详细文档
- [API 文档](./api/)：HTTP API 参考
- [IM Server 架构](../../im-server/docs/architecture.md)：IM 系统架构设计
- [IM Client 文档](../../im-client/docs/)：IM Client 使用指南