Agent/gateway/docs/requirements.md

Gateway 需求规划

更新日期： 2026-03-14

文档维护规范

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

---

核心理解

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

2. 生命周期管理（Lifecycle）

职责：

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

关键点：

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

详细文档： lifecycle.md

3. 任务执行调度（Executor）

职责：

• 接收用户分配的任务
• 调度 Agent 框架执行任务
• 管理任务执行状态和结果

关键点：

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

详细文档： 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
• 网络通信

使用方式：

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 接收消息
• 网络通信

使用方式：

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 框架核心设计
• Gateway 架构：Gateway 架构设计
• 核心模块文档：各核心模块详细文档
• API 文档：HTTP API 参考
• IM Server 架构：IM 系统架构设计
• IM Client 文档：IM Client 使用指南