Главная Обзор Помощь
Вход
howard
/
Agent
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: main
Ветки Метки
Agent
/
gateway
/
docs
/
requirements.md

requirements.md 4.7 KB
Постоянная ссылка История Исходник

Gateway 需求规划

更新日期： 2026-03-12

文档维护规范

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

三大核心模块

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 机制（跨设备能力调用）
  • 当前阶段暂不实现
  • 未来如有需求再考虑

相关文档