Agent/gateway/docs/README.md

Gateway 文档索引

本目录包含 Gateway 的完整文档。

文档维护规范

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

---

核心文档

需求规划

状态： ✅ 已更新（2026-03-14）

已确认的功能需求和范围：

• Gateway 的核心定位：使命/职能对话系统
• 两大核心模块（Lifecycle、Executor）
• 两种 Agent 类型（个人助理、数字员工）
• 两种接入方式（内部、外部）
• 与 IM 系统的区别和集成

架构设计

状态： ✅ 已更新（2026-03-14）

Gateway 的架构设计和核心模块：

• 整体架构（Gateway + IM Server）
• 两大核心模块（Lifecycle、Executor）
• 两种对话模式（使命/职能对话 vs 主体间交流）
• 两种接入方式
• 与 IM 系统的集成

---

模块文档

核心模块（Core）

状态： ✅ 已完成

• channels.md - 外部渠道接入模块 ✅ 详细设计完成
• lifecycle.md - 生命周期管理模块 ✅ 详细设计完成
• executor.md - 任务执行调度模块 ✅ 详细设计完成

API 文档

状态： 📋 待更新

• lifecycle.md - 生命周期管理 API（需要根据新架构更新）
• executor.md - 任务执行 API（需要创建）
• conversations.md - 已删除（由 IM 系统负责）
• routing.md - 已删除（由 IM 系统负责）

客户端文档

状态： 📋 待更新

• python.md - Python SDK 使用指南（需要根据新架构更新）

---

使用指南

状态： 📋 待更新

• quickstart.md - 快速开始（需要根据新架构更新）
• internal-agent.md - 内部 Agent 集成指南（需要更新）
• external-agent.md - 外部 Agent 集成指南（需要更新）
• personal-assistant.md - 已删除（路由由 IM 系统负责）
• digital-employee.md - 已删除（路由由 IM 系统负责）

---

其他文档

设计决策

状态： 📋 待更新

架构决策记录（ADR）。需要记录本次架构调整的决策。

部署指南

状态： 📋 待更新

部署方式和配置说明。

企业功能文档

状态： 📋 保留（可选）

• enterprise/overview.md - 企业功能概览
• enterprise/implementation.md - 企业功能实现

---

文档完成状态

已完成 ✅

1. requirements.md - 需求规划（已更新）
2. architecture.md - 架构设计（已更新）
3. docs/README.md - 文档索引（本文件，已更新）
4. core/channels.md - 外部渠道接入模块（详细设计完成）
5. core/lifecycle.md - 生命周期管理模块（详细设计完成）
6. core/executor.md - 任务执行调度模块（详细设计完成）

待更新 📋

1. api/ - API 文档（需要根据新架构更新）
2. client/ - 客户端文档（需要根据新架构更新）
3. guides/ - 使用指南（需要根据新架构更新）
4. decisions.md - 设计决策（需要记录架构调整）

已删除 ❌

• core/conversations.md - 对话管理（由 IM 系统负责）
• core/routing.md - 消息路由（由 IM 系统负责）
• guides/personal-assistant.md - 个人助理配置（由 IM 系统负责）
• guides/digital-employee.md - 数字员工配置（由 IM 系统负责）

---

架构变更说明

重大变更（2026-03-14）：

1. Gateway 定位调整：

   • 从"Agent 通信和管理平台"调整为"使命/职能对话系统"
   • 专注于用户给 Agent 分配任务和 Agent 汇报工作

2. IM 系统独立：

   • IM Server 和 IM Client 独立为单独的项目
   • 负责所有主体间的平等通信（Agent ↔ Agent、Agent ↔ 用户）
   • 数字员工型 Agent 的飞书接入通过 IM Server

3. 模块调整：

   • 新增 Channels 模块（外部渠道接入，个人助理型）
   • 保留 Lifecycle 模块（生命周期管理）
   • 保留 Executor 模块（任务执行调度）
   • 删除 Conversations 模块（由 IM 系统负责）
   • 删除 Routing 模块（由 Channels 和 IM 系统负责）

4. 两种对话模式：

   • 使命/职能对话：通过 Gateway（个人助理型 Agent）
   • 主体间交流：通过 IM 系统（数字员工型 Agent）

5. 飞书接入方式：

   • 个人助理型：通过 Gateway Channels 模块接入
   • 数字员工型：通过 IM Server 接入
   • 使用不同的飞书账号

---

相关文档

• Agent Core 架构：Agent 框架核心设计
• Gateway README：项目概览
• IM Server 架构：IM 系统架构设计
• IM Client 文档：IM Client 使用指南