# Gateway 需求规划

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

## 文档维护规范

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 个并发

---

## 三大核心模块

### 1. Agent 生命周期管理（Lifecycle）

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

**关键点：**
- Trace 数据结构由 Agent Core 定义
- Gateway 负责管理 Trace 的元数据和 Workspace 路径
- 配置变更时热重载，不影响正在运行的 Trace

### 2. 对话管理（Conversations）

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

**关键概念：**
- **对话（Conversation）** = 一个用户和一个 Agent 的永久对话
- 每个对话有独立的消息历史

### 3. 消息路由（Routing）

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

**路由规则：**
- 根据配置将飞书消息路由到对应的 Trace
- 支持两种 Agent 类型的路由（见下文）

---

## 两种 Agent 类型

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

**特征：**
- 1 个飞书账号（助理） ← 多个用户
- 每个用户有独立的 Trace + Workspace
- 聊天历史隔离

**路由规则：**
```
飞书用户 ID → Agent Trace ID

示例：
- 用户 Alice 发消息给助理账号 → 路由到 trace-alice-001
- 用户 Bob 发消息给助理账号 → 路由到 trace-bob-001
```

**实现方式：**
- IM Server 根据配置维护 `飞书用户 ID → Trace ID` 的映射
- 消息到达时查找对应的 Trace 并执行

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

**特征：**
- 1 个飞书账号（数字员工） ← 所有用户
- 1 个 Agent Trace，但有多个对话（每个用户一个）
- Agent 可以查看所有对话的消息历史
- 串行工作（按全局消息顺序处理，或定时检查）

**工作模式：**
- Agent 通过工具主动查看消息
- Agent 通过工具主动回复消息
- 类似人类的工作方式

**示例工作流程：**
```
1. Agent 定时检查（如每 5 分钟）或收到新消息通知
2. 调用工具查看所有对话
3. 调用工具查看具体消息
4. 调用工具回复消息
5. 串行处理下一个对话
```

**路由规则：**
```
所有发给数字员工账号的消息 → 同一个 Trace

示例：
- 用户 Alice 发消息 → trace-receptionist
- 用户 Bob 发消息 → trace-receptionist（同一个）
```

---

## 两种 Agent 接入方式

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

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

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

### 外部 Agent（其他设备/其他框架）

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

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

---

## 联系人管理

**职责：**
- 维护每个注册 Agent 的可见联系人列表
- 联系人包括：Agent ID、介绍、运行设备信息
- 支持 Agent 之间发送消息

**说明：**
- Agent 介绍中可能体现其运行在不同设备
- 具体实现细节待后续设计

---

## 企业功能（可选）

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

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

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

**说明：**
- 这些功能可能需要，但具体实现方式待确认
- 作为可选模块，不影响核心功能

---

## 暂不实现的功能

### 能力 Node

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

---

## 相关文档

- [Agent Core 架构](../../agent/docs/architecture.md)：Agent 框架核心设计
- [Gateway 架构](./architecture.md)：Gateway 架构设计
- [核心模块文档](./core/)：各核心模块详细文档
- [API 文档](./api/)：HTTP API 参考
- [设计决策](./decisions.md)：架构决策记录