# Gateway 文档索引

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

## 文档维护规范

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

---

## 核心文档

### [需求规划](./requirements.md)
**状态：** ✅ 已更新（2026-03-14）

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

### [架构设计](./architecture.md)
**状态：** ✅ 已更新（2026-03-14）

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

---

## 模块文档

### 核心模块（Core）

**状态：** ✅ 已完成

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

### API 文档

**状态：** 📋 待更新

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

### 客户端文档

**状态：** 📋 待更新

- [python.md](./client/python.md) - Python SDK 使用指南（需要根据新架构更新）

---

## 使用指南

**状态：** 📋 待更新

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

---

## 其他文档

### [设计决策](./decisions.md)
**状态：** 📋 待更新

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

### [部署指南](./deployment.md)
**状态：** 📋 待更新

部署方式和配置说明。

### 企业功能文档

**状态：** 📋 保留（可选）

- [enterprise/overview.md](./enterprise/overview.md) - 企业功能概览
- [enterprise/implementation.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** - 任务执行调度模块（详细设计完成）

### 待更新 📋

6. **api/** - API 文档（需要根据新架构更新）
7. **client/** - 客户端文档（需要根据新架构更新）
8. **guides/** - 使用指南（需要根据新架构更新）
9. **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/docs/architecture.md)：Agent 框架核心设计
- [Gateway README](../README.md)：项目概览
- [IM Server 架构](../../im-server/docs/architecture.md)：IM 系统架构设计
- [IM Client 文档](../../im-client/docs/)：IM Client 使用指南
