doc: gateway & IM

gateway/README.md

@@ -1,66 +1,111 @@
-# Gateway - Agent 消息路由和生命周期管理服务
+# Gateway - Agent 使命/职能对话系统
 
-**框架无关的 Agent 即时通讯网关**，提供 Agent 生命周期管理、消息路由、对话管理。
+**自研 Agent 框架的管理系统**，负责 Agent 的生命周期管理和任务执行调度。
 
 ## 概述
 
-Gateway 是一个 Agent 即时通讯和管理系统，支持任何 Agent 框架使用。核心功能：
+Gateway 是自研 Agent 框架的管理系统，专注于"使命/职能对话"：
 
-- **Agent 生命周期管理**：Trace 注册、Workspace 管理、配置热重载
-- **对话管理**：对话管理、消息历史、消息队列
-- **消息路由**：飞书集成、消息路由、联系人管理
+- **使命/职能对话**：用户给 Agent 分配任务，Agent 汇报工作
+- **管理-执行关系**：用户是管理者，Agent 是执行者
+- **任务导向**：有明确的目标和预期结果
 
-**独立性**：Gateway 与 Agent Core 并列，可以独立部署。
+**与 IM 系统的区别：**
+- **IM 系统**：LLM 作为主体的平等交流（协作-沟通关系）
+- **Gateway**：用户对 LLM 的使命/职能对话（管理-执行关系）
+
+## 核心功能
+
+- **外部渠道接入（Channels）**：飞书集成（个人助理型）、消息路由、自动创建 Trace
+- **生命周期管理（Lifecycle）**：Trace 注册/查询、Workspace 管理、配置热重载
+- **任务执行调度（Executor）**：接收任务、调度执行、状态管理
 
 ## 设计原则
 
-1. **框架无关**：Gateway 核心不依赖任何特定的 Agent 框架
+1. **职责清晰**：专注于使命/职能对话，不处理平等交流
 2. **分层架构**：Core 层（内部接口）+ API 层（外部接口）
 3. **易于集成**：内部 Agent 直接调用，外部 Agent 使用 SDK
-4. **可扩展**：支持企业功能扩展（认证、审计、多租户）
+4. **与 IM 协同**：Agent 可以通过 IM Client 参与平等交流
 
 ## 架构
 
+```
+                    ┌──────────────────────┐
+                    │   飞书（个人助理）    │
+                    │  使命/职能对话        │
+                    └──────────┬───────────┘
+                               │
+                               │ Webhook
+                               │
+   ┌───────────────────────────▼───────────────────────────┐
+   │              Gateway（Agent 管理系统）                 │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Channels（外部渠道接入）                          │ │
+   │  │ - 飞书集成（个人助理型）                          │ │
+   │  │ - 消息路由                                        │ │
+   │  └──────────────────────────────────────────────────┘ │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Lifecycle（生命周期管理）                         │ │
+   │  │ - Trace 注册和查询                               │ │
+   │  │ - Workspace 管理                                 │ │
+   │  └──────────────────────────────────────────────────┘ │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Executor（任务执行调度）                          │ │
+   │  │ - 接收用户任务                                    │ │
+   │  │ - 调度 Agent 执行                                │ │
+   │  └──────────────────────────────────────────────────┘ │
+   └────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│                    IM Server                             │
+│  - 接入飞书（数字员工型）、微信等渠道                       │
+│  - LLM 作为主体参与对话                                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 目录结构
+
 ```
 gateway/
 ├── core/                          # 核心服务层（内部接口）
+│   ├── channels/                  # 外部渠道接入
+│   │   ├── feishu/                # 飞书集成
+│   │   │   ├── connector.py       # 飞书连接器
+│   │   │   ├── webhook.py         # Webhook 处理
+│   │   │   └── api.py             # 飞书 API 调用
+│   │   ├── router.py              # 消息路由
+│   │   └── channel_manager.py     # 渠道管理
+│   │
 │   ├── lifecycle/                 # Agent 生命周期管理
-│   │   ├── trace_manager.py      # Trace 注册和元数据管理
+│   │   ├── trace_manager.py      # Trace 注册和查询
 │   │   ├── workspace_manager.py  # Workspace 管理
 │   │   └── config_watcher.py     # 配置热重载
 │   │
-│   ├── conversations/             # 对话管理
-│   │   ├── conversation_manager.py  # 对话管理
-│   │   ├── message_store.py      # 消息历史存储
-│   │   └── message_queue.py      # 消息队列和调度
-│   │
-│   ├── routing/                   # 消息路由
-│   │   ├── router.py              # 消息路由核心
-│   │   ├── feishu_connector.py   # 飞书集成
-│   │   └── contact_manager.py    # 联系人管理
-│   │
-│   └── registry.py                # Agent 注册表（保留，兼容旧代码）
+│   └── executor/                  # 任务执行调度
+│       ├── task_manager.py        # 任务管理
+│       ├── scheduler.py           # 调度器
+│       └── execution_context.py   # 执行上下文
 │
 ├── api/                           # HTTP API 层（外部接口）
 │   ├── lifecycle_api.py           # 生命周期管理 API
-│   ├── conversations_api.py       # 对话管理 API
-│   └── routing_api.py             # 消息路由 API
-│
-├── enterprise/                    # 企业功能（可选）
-│   ├── auth/                      # 认证授权
-│   ├── audit/                     # 审计日志
-│   └── multi_tenant/              # 多租户
+│   ├── executor_api.py            # 任务执行 API
+│   └── webhook_api.py             # Webhook API（飞书等）
 │
 ├── client/                        # 客户端 SDK
 │   └── python/                    # Python SDK
 │       ├── client.py              # GatewayClient
-│       ├── tools.py               # 工具函数
 │       └── cli.py                 # CLI 工具
 │
 └── docs/                          # 文档
     ├── requirements.md            # 需求规划
     ├── architecture.md            # 架构设计
     ├── core/                      # 核心模块文档
+    │   ├── channels.md            # 外部渠道接入
+    │   ├── lifecycle.md           # 生命周期管理
+    │   └── executor.md            # 任务执行调度
     ├── api/                       # API 文档
     ├── client/                    # 客户端文档
     ├── guides/                    # 使用指南
@@ -73,10 +118,27 @@ gateway/
 
 ```python
 # 直接导入 Core 层模块
-from gateway.core.conversations import ConversationManager
-
-manager = ConversationManager()
-messages = manager.get_messages(conversation_id)
+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=trace_id,
+    task_description="分析销售数据"
+)
+
+# 查询任务状态
+task = task_mgr.get_task(task_id)
+print(task["status"])  # pending/running/completed/failed
 ```
 
 ### 外部 Agent（其他设备/其他框架）
@@ -86,7 +148,22 @@ messages = manager.get_messages(conversation_id)
 from gateway.client.python import GatewayClient
 
 client = GatewayClient("http://gateway-host:8000")
-messages = client.get_messages(conversation_id)
+
+# 创建 Trace
+trace_id = client.create_trace(
+    workspace_id="user_001",
+    agent_type="personal_assistant"
+)
+
+# 提交任务
+task_id = client.submit_task(
+    trace_id=trace_id,
+    task_description="分析销售数据"
+)
+
+# 查询任务状态
+task = client.get_task(task_id)
+print(task["status"])
 ```
 
 ## 文档
@@ -97,18 +174,22 @@ messages = client.get_messages(conversation_id)
 - [架构设计](./docs/architecture.md)：Gateway 架构和核心模块
 - [文档索引](./docs/README.md)：完整文档导航
 
-### 模块文档（待创建）
+### 模块文档
 
-- 核心模块文档：`docs/core/`
-- API 文档：`docs/api/`
-- 客户端文档：`docs/client/`
-- 使用指南：`docs/guides/`
+- [Channels 模块](./docs/core/channels.md)：外部渠道接入详细设计
+- [Lifecycle 模块](./docs/core/lifecycle.md)：生命周期管理详细设计
+- [Executor 模块](./docs/core/executor.md)：任务执行调度详细设计
+
+### 使用指南（待更新）
+
+- 快速开始：`docs/guides/quickstart.md`
+- 内部 Agent 集成：`docs/guides/internal-agent.md`
+- 外部 Agent 集成：`docs/guides/external-agent.md`
 
 ### 其他文档
 
 - [设计决策](./docs/decisions.md)：架构决策记录
 - [部署指南](./docs/deployment.md)：部署方式和配置
-- [企业功能](./docs/enterprise/)：企业功能文档（可选）
 
 ## 文档维护规范
 
@@ -118,23 +199,23 @@ messages = client.get_messages(conversation_id)
 
 ## 开发状态
 
-### 已实现
-
-- ✅ Agent 注册和在线状态管理（旧版）
-- ✅ 消息路由（Webhook 推送，旧版）
-
-### 开发中
+### 已完成 ✅
 
-- 🚧 重构为新架构（Core 层 + API 层）
-- 🚧 Agent 生命周期管理
-- 🚧 对话管理
-- 🚧 飞书集成
+- 需求规划和架构设计
+- Channels 模块详细设计（飞书接入）
+- Lifecycle 模块详细设计
+- Executor 模块详细设计
 
-### 计划中
+### 待实现 📋
 
-- 📋 联系人管理
-- 📋 企业功能（认证、审计、多租户）
+- Core 层代码实现
+- API 层代码实现
+- Client SDK 实现
+- 使用指南更新
+- API 文档更新
 
 ## 相关项目
 
 - [Agent Core](../agent/README.md)：Agent 核心框架
+- [IM Server](../im-server/README.md)：IM 通信系统
+- [IM Client](../im-client/README.md)：IM 客户端工具

gateway/docs/README.md

@@ -13,24 +13,24 @@
 ## 核心文档
 
 ### [需求规划](./requirements.md)
-**状态：** ✅ 已确认
+**状态：** ✅ 已更新（2026-03-14）
 
 已确认的功能需求和范围：
-- Agent 生命周期管理
-- 对话管理（Conversations）
-- 消息路由（Routing）
+- Gateway 的核心定位：使命/职能对话系统
+- 两大核心模块（Lifecycle、Executor）
 - 两种 Agent 类型（个人助理、数字员工）
 - 两种接入方式（内部、外部）
-- 企业功能（可选）
+- 与 IM 系统的区别和集成
 
 ### [架构设计](./architecture.md)
-**状态：** ✅ 已确认
+**状态：** ✅ 已更新（2026-03-14）
 
 Gateway 的架构设计和核心模块：
-- 分层架构（Core 层、API 层）
-- 三大核心模块（Lifecycle、Conversations、Routing）
+- 整体架构（Gateway + IM Server）
+- 两大核心模块（Lifecycle、Executor）
+- 两种对话模式（使命/职能对话 vs 主体间交流）
 - 两种接入方式
-- 企业功能
+- 与 IM 系统的集成
 
 ---
 
@@ -38,55 +38,56 @@ Gateway 的架构设计和核心模块：
 
 ### 核心模块（Core）
 
-**状态：** ✅ 已创建
+**状态：** ✅ 已完成
 
-- [lifecycle.md](./core/lifecycle.md) - 生命周期管理模块
-- [conversations.md](./core/conversations.md) - 对话管理模块
-- [routing.md](./core/routing.md) - 消息路由模块
+- [channels.md](./core/channels.md) - 外部渠道接入模块 ✅ 详细设计完成
+- [lifecycle.md](./core/lifecycle.md) - 生命周期管理模块 ✅ 详细设计完成
+- [executor.md](./core/executor.md) - 任务执行调度模块 ✅ 详细设计完成
 
 ### API 文档
 
-**状态：** ✅ 已创建
+**状态：** 📋 待更新
 
-- [lifecycle.md](./api/lifecycle.md) - 生命周期管理 API
-- [conversations.md](./api/conversations.md) - 对话管理 API
-- [routing.md](./api/routing.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 使用指南
+- [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) - 个人助理型 Agent 配置
-- [digital-employee.md](./guides/digital-employee.md) - 数字员工型 Agent 配置
+- [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）。
+架构决策记录（ADR）。需要记录本次架构调整的决策。
 
 ### [部署指南](./deployment.md)
-**状态：** ✅ 保留
+**状态：** 📋 待更新
 
 部署方式和配置说明。
 
 ### 企业功能文档
 
-**状态：** ✅ 保留（可选）
+**状态：** 📋 保留（可选）
 
 - [enterprise/overview.md](./enterprise/overview.md) - 企业功能概览
 - [enterprise/implementation.md](./enterprise/implementation.md) - 企业功能实现
@@ -97,15 +98,57 @@ Gateway 的架构设计和核心模块：
 
 ### 已完成 ✅
 
-1. **requirements.md** - 需求规划
-2. **architecture.md** - 架构设计
-3. **docs/README.md** - 文档索引（本文件）
-4. **core/** - 核心模块文档（3 个文件）
-5. **api/** - API 文档（3 个文件）
-6. **client/** - 客户端文档（1 个文件）
-7. **guides/** - 使用指南（5 个文件）
+1. **requirements.md** - 需求规划（已更新）
+2. **architecture.md** - 架构设计（已更新）
+3. **docs/README.md** - 文档索引（本文件，已更新）
+4. **core/channels.md** - 外部渠道接入模块（详细设计完成）
+5. **core/lifecycle.md** - 生命周期管理模块（详细设计完成）
+6. **core/executor.md** - 任务执行调度模块（详细设计完成）
 
-**总计：** 15 个文档文件已创建
+### 待更新 📋
+
+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 接入
+   - 使用不同的飞书账号
 
 ---
 
@@ -113,4 +156,5 @@ Gateway 的架构设计和核心模块：
 
 - [Agent Core 架构](../../agent/docs/architecture.md)：Agent 框架核心设计
 - [Gateway README](../README.md)：项目概览
-- [Gateway 客户端](../client/README.md)：客户端 SDK 和 CLI 工具
+- [IM Server 架构](../../im-server/docs/architecture.md)：IM 系统架构设计
+- [IM Client 文档](../../im-client/docs/)：IM Client 使用指南

gateway/docs/architecture.md

@@ -1,6 +1,6 @@
 # Gateway 架构设计
 
-**更新日期：** 2026-03-12
+**更新日期：** 2026-03-14
 
 ## 文档维护规范
 
@@ -10,41 +10,72 @@
 
 ---
 
-## 架构概述
+## 整体架构
 
-Gateway 采用分层架构：
+Gateway 是自研 Agent 框架的管理系统，负责 Agent 的生命周期管理和任务执行调度。
+
+**核心定位：** 使命/职能对话系统
+- 用户给 Agent 分配任务
+- Agent 汇报工作、述职
+- 是"管理-执行"关系
+
+**与 IM 系统的区别：**
+- IM 系统：LLM 作为主体的平等交流（协作-沟通关系）
+- Gateway：用户对 LLM 的使命/职能对话（管理-执行关系）
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│ API 层（HTTP 接口）                                          │
-│ - 供外部 Agent 调用                                          │
-│ - RESTful API                                               │
-└────────────────────────┬────────────────────────────────────┘
+                    ┌──────────────────────┐
+                    │   飞书（个人助理）    │
+                    │  使命/职能对话        │
+                    └──────────┬───────────┘
+                               │
+                               │ Webhook
+                               │
+   ┌───────────────────────────▼───────────────────────────┐
+   │              Gateway（Agent 管理系统）                 │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Channels（外部渠道接入）                          │ │
+   │  │ - 飞书集成（个人助理型）                          │ │
+   │  │ - 消息路由                                        │ │
+   │  └──────────────────────────────────────────────────┘ │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Lifecycle（生命周期管理）                         │ │
+   │  │ - Trace 注册和查询                               │ │
+   │  │ - Workspace 管理                                 │ │
+   │  │ - 配置热重载                                      │ │
+   │  └──────────────────────────────────────────────────┘ │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ Executor（任务执行调度）                          │ │
+   │  │ - 接收用户任务                                    │ │
+   │  │ - 调度 Agent 执行                                │ │
+   │  │ - 管理执行状态                                    │ │
+   │  └──────────────────────────────────────────────────┘ │
+   │                                                        │
+   │  ┌──────────────────────────────────────────────────┐ │
+   │  │ IM Client（可选）                                 │ │
+   │  │ - Agent 主动通信                                  │ │
+   │  └──────────────────────────────────────────────────┘ │
+   └────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│                    IM Server                             │
+│  - 所有主体（Agent、用户）的平等通信系统                    │
+│  - 接入飞书（数字员工型）、微信等渠道                       │
+│  - LLM 作为主体参与对话                                    │
+└─────────────────────────────────────────────────────────┘
+                         ↑
+                         │ IM Protocol
                          │
-┌────────────────────────▼────────────────────────────────────┐
-│ Core 层（核心服务）                                          │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐  │
-│  │ Lifecycle（生命周期管理）                            │  │
-│  │ - Trace 注册和元数据管理                             │  │
-│  │ - Workspace 管理                                    │  │
-│  │ - 配置热重载                                         │  │
-│  └─────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐  │
-│  │ Conversations（对话管理）                            │  │
-│  │ - 对话管理                                           │  │
-│  │ - 消息历史存储                                       │  │
-│  │ - 消息队列和调度                                     │  │
-│  └─────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─────────────────────────────────────────────────────┐  │
-│  │ Routing（消息路由）                                  │  │
-│  │ - 飞书消息接收和转发                                 │  │
-│  │ - 消息路由规则管理                                   │  │
-│  │ - Agent 联系人列表维护                               │  │
-│  └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
+        ┌────────────────┼────────────────┐
+        │                │                │
+   ┌────▼────┐      ┌───▼────┐      ┌───▼────┐
+   │IM Client│      │IM Client│     │IM Client│
+   │(自研)   │      │(Claude  │     │(飞书数字 │
+   │         │      │ Code)   │     │ 员工)   │
+   └─────────┘      └─────────┘     └─────────┘
 ```
 
 ---
@@ -54,37 +85,32 @@ Gateway 采用分层架构：
 ```
 gateway/
 ├── core/                          # 核心服务层（内部接口）
+│   ├── channels/                  # 外部渠道接入
+│   │   ├── feishu/                # 飞书集成
+│   │   │   ├── connector.py       # 飞书连接器
+│   │   │   ├── webhook.py         # Webhook 处理
+│   │   │   └── api.py             # 飞书 API 调用
+│   │   ├── router.py              # 消息路由
+│   │   └── channel_manager.py     # 渠道管理
+│   │
 │   ├── lifecycle/                 # Agent 生命周期管理
-│   │   ├── trace_manager.py      # Trace 注册和元数据管理
+│   │   ├── trace_manager.py      # Trace 注册和查询
 │   │   ├── workspace_manager.py  # Workspace 管理
 │   │   └── config_watcher.py     # 配置热重载
 │   │
-│   ├── conversations/             # 对话管理
-│   │   ├── conversation_manager.py  # 对话管理
-│   │   ├── message_store.py         # 消息历史存储
-│   │   └── message_queue.py         # 消息队列和调度
-│   │
-│   ├── routing/                   # 消息路由
-│   │   ├── router.py              # 消息路由核心
-│   │   ├── feishu_connector.py   # 飞书集成
-│   │   └── contact_manager.py    # 联系人管理
-│   │
-│   └── registry.py                # Agent 注册表（保留，兼容旧代码）
+│   └── executor/                  # 任务执行调度
+│       ├── task_manager.py        # 任务管理
+│       ├── scheduler.py           # 调度器
+│       └── execution_context.py   # 执行上下文
 │
 ├── api/                           # HTTP API 层（外部接口）
 │   ├── lifecycle_api.py           # 生命周期管理 API
-│   ├── conversations_api.py       # 对话管理 API
-│   └── routing_api.py             # 消息路由 API
-│
-├── enterprise/                    # 企业功能（可选）
-│   ├── auth/                      # 认证授权
-│   ├── audit/                     # 审计日志
-│   └── multi_tenant/              # 多租户
+│   ├── executor_api.py            # 任务执行 API
+│   └── webhook_api.py             # Webhook API（飞书等）
 │
 └── client/                        # 客户端 SDK
     └── python/                    # Python SDK
         ├── client.py              # GatewayClient
-        ├── tools.py               # 工具函数
         └── cli.py                 # CLI 工具
 ```
 
@@ -92,45 +118,89 @@ gateway/
 
 ## 核心模块
 
+### Channels（外部渠道接入）
+
+**职责：**
+- 接入飞书等外部渠道（个人助理型 Agent）
+- 消息路由（飞书用户 ID → Trace ID）
+- 自动创建 Trace（首次对话）
+
+**实现位置：**
+- `gateway/core/channels/feishu/connector.py`
+- `gateway/core/channels/router.py`
+- `gateway/core/channels/channel_manager.py`
+
+**详细文档：** [channels.md](./core/channels.md)
+
 ### Lifecycle（生命周期管理）
 
 **职责：**
-- Trace 注册和元数据管理
-- Workspace 管理
-- 配置热重载
+- 调用 Agent 框架创建/查询 Trace
+- 管理 Workspace（创建、引用计数、清理）
+- 监听配置变化并热重载
 
 **实现位置：**
 - `gateway/core/lifecycle/trace_manager.py`
 - `gateway/core/lifecycle/workspace_manager.py`
 - `gateway/core/lifecycle/config_watcher.py`
 
-### Conversations（对话管理）
+**详细文档：** [lifecycle.md](./core/lifecycle.md)
+
+### Executor（任务执行调度）
 
 **职责：**
-- 对话管理
-- 消息历史存储
-- 消息队列和调度
+- 接收用户分配的任务
+- 调度 Agent 框架执行任务
+- 管理任务执行状态和结果
 
 **实现位置：**
-- `gateway/core/conversations/conversation_manager.py`
-- `gateway/core/conversations/message_store.py`
-- `gateway/core/conversations/message_queue.py`
+- `gateway/core/executor/task_manager.py`
+- `gateway/core/executor/scheduler.py`
+- `gateway/core/executor/execution_context.py`
 
-### Routing（消息路由）
+**详细文档：** [executor.md](./core/executor.md)
 
-**职责：**
-- 飞书消息接收和转发
-- 消息路由规则管理
-- Agent 联系人列表维护
+---
 
-**实现位置：**
-- `gateway/core/routing/router.py`
-- `gateway/core/routing/feishu_connector.py`
-- `gateway/core/routing/contact_manager.py`
+## 两种对话模式
+
+### 使命/职能对话（通过 Gateway）
+
+**场景：**
+- 用户通过管理界面给 Agent 分配任务
+- Agent 定期向用户汇报工作进度
+- 用户查询 Agent 的执行状态
+
+**消息流转：**
+```
+用户 → Gateway API → Executor → Agent 框架执行 → Executor → Gateway API → 用户
+```
+
+**特点：**
+- 用户是管理者，Agent 是执行者
+- 任务导向，有明确的目标和结果
+- 通过 Gateway 的 API 接口
+
+### 主体间交流（通过 IM 系统）
+
+**场景：**
+- 用户在飞书上和 Agent 聊天（平等对话）
+- Agent A 请求 Agent B 协助完成任务
+- Agent 主动向用户发送通知
+
+**消息流转：**
+```
+用户/Agent A → IM Client → IM Server → IM Client → Agent B
+```
+
+**特点：**
+- 所有参与者都是平等主体
+- 协作导向，强调沟通和交流
+- 通过 IM Server 的消息系统
 
 ---
 
-## 两种接入方式
+## 接入方式
 
 ### 内部 Agent 接入
 
@@ -142,10 +212,17 @@ gateway/
 **使用方式：**
 ```python
 # 直接导入 Core 层模块
-from gateway.core.conversations import ConversationManager
+from gateway.core.lifecycle import TraceManager
+from gateway.core.executor import TaskManager
 
-manager = ConversationManager()
-messages = manager.get_messages(conversation_id)
+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 接入
@@ -161,32 +238,31 @@ messages = manager.get_messages(conversation_id)
 from gateway.client.python import GatewayClient
 
 client = GatewayClient("http://gateway-host:8000")
-messages = client.get_messages(conversation_id)
+
+# 创建 Trace
+trace_id = client.create_trace(workspace_id="user_001", agent_type="personal_assistant")
+
+# 提交任务
+task_id = client.submit_task(trace_id, task_description="分析销售数据")
 ```
 
 ---
 
-## 企业功能（可选）
+## 与 IM 系统的集成
 
-### 认证授权（Auth）
-- API Key 认证
-- OAuth 集成
-- 权限控制
-- 单点登录
+Gateway 管理的 Agent 可以通过 IM Client 参与 IM 系统的通信：
 
-### 审计日志（Audit）
-- 操作日志记录
-- 消息审计
-- 合规报告
+1. **Agent 执行过程中需要协作**：
+   - Agent 通过 IM Client 发送消息给其他 Agent
+   - 其他 Agent 通过 IM 回复
 
-### 多租户（Multi-Tenant）
-- 租户隔离
-- 资源配额
-- 计费管理
+2. **Agent 主动通知用户**：
+   - Agent 通过 IM Client 发送消息给用户
+   - 用户在飞书等渠道收到消息
 
-**说明：**
-- 作为可选模块，独立于核心功能
-- 具体实现方式待确认
+3. **消息历史管理**：
+   - IM Client 存储在 Workspace 内
+   - 管理该 Agent 的所有 IM 对话历史
 
 ---
 
@@ -196,4 +272,5 @@ messages = client.get_messages(conversation_id)
 - [核心模块文档](./core/)：各核心模块详细文档
 - [API 文档](./api/)：HTTP API 参考
 - [Client SDK 文档](./client/)：客户端 SDK 使用指南
-- [设计决策](./decisions.md)：架构决策记录
+- [IM Server 架构](../../im-server/docs/architecture.md)：IM 系统架构设计
+- [IM Client 文档](../../im-client/docs/)：IM Client 使用指南

gateway/docs/core/channels.md

@@ -0,0 +1,278 @@
+# Channels（外部渠道接入）
+
+**模块：** `gateway/core/channels/`
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的设计
+
+---
+
+## 模块职责
+
+外部渠道接入，包括：
+
+- **飞书集成**：接收飞书消息，发送回复
+- **消息路由**：将飞书消息路由到对应的 Agent
+- **渠道管理**：管理渠道配置和状态
+
+**说明：** Channels 模块只用于个人助理型 Agent 的飞书接入（使命/职能对话）
+
+---
+
+## 核心概念
+
+### Channel（渠道）
+
+- **定义**：外部消息来源（飞书、微信等）
+- **特点**：
+  - 每个渠道有独立的配置
+  - 每个渠道有独立的消息处理逻辑
+
+### 路由规则
+
+- **个人助理型 Agent**：
+  - 飞书用户 ID → Trace ID
+  - 每个用户有独立的 Trace
+  - 首次对话自动创建 Trace
+
+### 消息流转
+
+```
+飞书用户 → 飞书 Webhook → Channels 模块 → Executor 模块 → Agent 执行 → Executor → Channels → 飞书
+```
+
+---
+
+## 模块结构
+
+```
+gateway/core/channels/
+├── feishu/                    # 飞书集成
+│   ├── connector.py           # 飞书连接器
+│   ├── webhook.py             # Webhook 处理
+│   └── api.py                 # 飞书 API 调用
+│
+├── router.py                  # 消息路由
+└── channel_manager.py         # 渠道管理
+```
+
+---
+
+## 关键功能
+
+### FeishuConnector
+
+**实现位置：** `gateway/core/channels/feishu/connector.py`
+
+**职责：**
+- 接收飞书 Webhook 消息
+- 调用飞书 API 发送回复
+- 管理飞书连接状态
+
+**核心接口：**
+
+```python
+class FeishuConnector:
+    def __init__(self, app_id: str, app_secret: str):
+        """初始化飞书连接器"""
+        pass
+
+    def handle_webhook(self, event: dict) -> dict:
+        """处理飞书 Webhook 事件"""
+        pass
+
+    def send_message(self, user_id: str, text: str):
+        """发送消息给飞书用户"""
+        pass
+
+    def get_user_info(self, user_id: str) -> dict:
+        """获取飞书用户信息"""
+        pass
+```
+
+### MessageRouter
+
+**实现位置：** `gateway/core/channels/router.py`
+
+**职责：**
+- 根据飞书用户 ID 查找对应的 Trace
+- 如果 Trace 不存在，自动创建
+- 将消息转换为任务提交给 Executor
+
+**核心接口：**
+
+```python
+class MessageRouter:
+    def route_message(self, channel: str, user_id: str, message: dict) -> str:
+        """路由消息，返回 task_id"""
+        pass
+
+    def get_trace_id(self, channel: str, user_id: str) -> str:
+        """获取或创建 Trace ID"""
+        pass
+
+    def create_trace_for_user(self, channel: str, user_id: str) -> str:
+        """为用户创建 Trace"""
+        pass
+```
+
+### ChannelManager
+
+**实现位置：** `gateway/core/channels/channel_manager.py`
+
+**职责：**
+- 管理所有渠道的配置
+- 启动和停止渠道
+- 监控渠道状态
+
+**核心接口：**
+
+```python
+class ChannelManager:
+    def register_channel(self, channel_id: str, config: dict):
+        """注册渠道"""
+        pass
+
+    def start_channel(self, channel_id: str):
+        """启动渠道"""
+        pass
+
+    def stop_channel(self, channel_id: str):
+        """停止渠道"""
+        pass
+
+    def get_channel_status(self, channel_id: str) -> dict:
+        """获取渠道状态"""
+        pass
+```
+
+---
+
+## 典型流程
+
+### 用户首次通过飞书发送消息
+
+1. 飞书用户发送消息
+2. 飞书 Webhook 触发，调用 `FeishuConnector.handle_webhook()`
+3. FeishuConnector 提取用户 ID 和消息内容
+4. 调用 `MessageRouter.route_message()`
+5. MessageRouter 查询是否有对应的 Trace
+6. 无 Trace → 调用 `Lifecycle.TraceManager.create_trace()`
+7. 创建 Trace（workspace_id=feishu_user_id, agent_type="personal_assistant"）
+8. 调用 `Executor.TaskManager.submit_task()`
+9. Executor 调度 Agent 执行
+10. Agent 执行完成，返回结果
+11. Executor 调用 `FeishuConnector.send_message()` 发送回复
+12. 用户在飞书收到回复
+
+### 用户再次发送消息
+
+1. 飞书用户发送消息
+2. FeishuConnector 处理 Webhook
+3. MessageRouter 查询到已有 Trace
+4. 直接提交任务给 Executor
+5. Agent 执行并回复
+
+---
+
+## 与其他模块的集成
+
+### 与 Lifecycle 模块
+
+```python
+# 创建 Trace
+from gateway.core.lifecycle import TraceManager
+
+trace_mgr = TraceManager()
+trace_id = trace_mgr.create_trace(
+    workspace_id=f"feishu:{user_id}",
+    agent_type="personal_assistant"
+)
+```
+
+### 与 Executor 模块
+
+```python
+# 提交任务
+from gateway.core.executor import TaskManager
+
+task_mgr = TaskManager()
+task_id = task_mgr.submit_task(
+    trace_id=trace_id,
+    task_description=message_text,
+    mode="async"
+)
+```
+
+---
+
+## 配置示例
+
+```yaml
+# config.yaml
+channels:
+  feishu:
+    enabled: true
+    app_id: "cli_xxx"
+    app_secret: "xxx"
+    webhook_url: "https://gateway.example.com/webhook/feishu"
+
+    # 路由配置
+    routing:
+      # 自动为新用户创建 Trace
+      auto_create_trace: true
+      # Workspace ID 前缀
+      workspace_prefix: "feishu"
+```
+
+---
+
+## 与 IM Server 的区别
+
+### Gateway Channels（个人助理型）
+
+- **对话性质**：使命/职能对话
+- **飞书账号**：个人助理账号
+- **Trace 管理**：每个用户独立 Trace
+- **消息处理**：转换为任务提交给 Executor
+
+### IM Server Channels（数字员工型）
+
+- **对话性质**：主体间平等交流
+- **飞书账号**：数字员工账号
+- **Trace 管理**：所有用户共享 Trace
+- **消息处理**：通过 IM Client 管理消息队列
+
+---
+
+## 错误处理
+
+### Webhook 处理失败
+
+- 飞书 Webhook 验证失败 → 返回 401
+- 消息格式错误 → 记录日志，返回 400
+- 内部错误 → 返回 500，通知管理员
+
+### 任务提交失败
+
+- Trace 创建失败 → 向用户发送错误提示
+- Executor 繁忙 → 消息入队，稍后处理
+- Agent 执行超时 → 向用户发送超时提示
+
+### 飞书 API 调用失败
+
+- Token 过期 → 自动刷新 Token
+- 限流 → 等待后重试
+- 网络错误 → 重试 3 次，失败后记录日志
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：外部渠道接入需求
+- [架构设计](../architecture.md)：模块在整体架构中的位置
+- [Lifecycle 模块](./lifecycle.md)：生命周期管理模块
+- [Executor 模块](./executor.md)：任务执行调度模块

gateway/docs/core/conversations.md

@@ -1,110 +0,0 @@
-# Conversations（对话管理）
-
-**模块：** `gateway/core/conversations/`
-
-## 文档维护规范
-
-0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
-1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-2. **简洁快照，日志分离** - 只记录已确认的设计
-
----
-
-## 模块职责
-
-对话管理，包括：
-
-- **对话管理**：管理用户和 Agent 的对话
-- **消息历史存储**：存储和查询消息历史
-- **消息队列和调度**：管理消息队列，调度 Agent 执行
-
----
-
-## 核心概念
-
-### Conversation（对话）
-
-- **定义**：一个用户和一个 Agent 的永久对话
-- **特点**：
-  - 每个对话有独立的消息历史
-  - 对话是永久的
-  - 对话 ID 格式：`conversation:{trace_id}:{user_id}`
-
-### 消息历史
-
-- 每个对话的消息按时间顺序存储
-- 包含用户消息和 Agent 回复
-- 支持查询历史消息
-
-### 消息队列
-
-- 管理待处理的消息
-- 支持消息调度
-- 防止并发冲突
-
----
-
-## 模块结构
-
-```
-gateway/core/conversations/
-├── conversation_manager.py  # 对话管理
-├── message_store.py         # 消息历史存储
-└── message_queue.py         # 消息队列和调度
-```
-
----
-
-## 关键功能
-
-### 对话管理
-
-**实现位置：** `gateway/core/conversations/conversation_manager.py`
-
-**职责：**
-- 创建对话
-- 查询对话信息
-- 列出所有对话
-
-### 消息历史存储
-
-**实现位置：** `gateway/core/conversations/message_store.py`
-
-**职责：**
-- 存储消息
-- 查询消息历史
-- 消息持久化
-
-### 消息队列和调度
-
-**实现位置：** `gateway/core/conversations/message_queue.py`
-
-**职责：**
-- 消息入队
-- 消息调度
-- 调用 Agent 执行
-
----
-
-## 两种 Agent 类型的对话管理
-
-### 个人助理型 Agent
-
-- 每个用户有独立的 Trace
-- 每个用户有独立的对话
-- 对话 ID：`conversation:trace-alice-001:user_alice`
-
-### 数字员工型 Agent
-
-- 所有用户共享一个 Trace
-- 每个用户有独立的对话
-- 对话 ID：`conversation:trace-receptionist:user_alice`
-- Agent 可以查看所有对话的消息历史
-
----
-
-## 相关文档
-
-- [需求规划](../requirements.md)：对话管理需求
-- [架构设计](../architecture.md)：模块在整体架构中的位置
-- [两种 Agent 类型](../requirements.md#两种-agent-类型)：详细说明

gateway/docs/core/executor.md

@@ -0,0 +1,295 @@
+# Executor（任务执行调度）
+
+**模块：** `gateway/core/executor/`
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的设计
+
+---
+
+## 模块职责
+
+任务执行调度，包括：
+
+- **任务管理**：接收、存储、查询用户任务
+- **执行调度**：调度 Agent 框架执行任务
+- **状态管理**：管理任务执行状态和结果
+
+**说明：** Executor 负责"使命/职能对话"的执行部分
+
+---
+
+## 核心概念
+
+### Task（任务）
+
+- **定义**：用户分配给 Agent 的工作任务
+- **特点**：
+  - 有明确的目标和预期结果
+  - 是"管理-执行"关系的体现
+  - 不同于 IM 系统的平等对话
+
+### 任务状态
+
+- `pending`：待执行
+- `running`：执行中
+- `completed`：已完成
+- `failed`：执行失败
+- `cancelled`：已取消
+
+### 执行模式
+
+- **同步执行**：提交任务后等待结果返回
+- **异步执行**：提交任务后立即返回，通过查询获取结果
+
+---
+
+## 模块结构
+
+```
+gateway/core/executor/
+├── task_manager.py        # 任务管理
+├── scheduler.py           # 调度器
+└── execution_context.py   # 执行上下文
+```
+
+---
+
+## 关键功能
+
+### TaskManager
+
+**实现位置：** `gateway/core/executor/task_manager.py`
+
+**职责：**
+- 接收用户任务
+- 存储任务信息
+- 查询任务状态和结果
+
+**核心接口：**
+
+```python
+class TaskManager:
+    def submit_task(
+        self,
+        trace_id: str,
+        task_description: str,
+        mode: str = "async",  # "sync" | "async"
+        metadata: dict = None
+    ) -> str:
+        """提交任务，返回 task_id"""
+        pass
+
+    def get_task(self, task_id: str) -> dict:
+        """查询任务信息"""
+        pass
+
+    def list_tasks(
+        self,
+        trace_id: str = None,
+        status: str = None
+    ) -> list[dict]:
+        """查询任务列表"""
+        pass
+
+    def cancel_task(self, task_id: str):
+        """取消任务"""
+        pass
+```
+
+### Scheduler
+
+**实现位置：** `gateway/core/executor/scheduler.py`
+
+**职责：**
+- 调度 Agent 框架执行任务
+- 管理执行队列
+- 处理并发和串行逻辑
+
+**核心接口：**
+
+```python
+class Scheduler:
+    def schedule(self, task_id: str):
+        """调度任务执行"""
+        pass
+
+    def execute(self, task_id: str) -> dict:
+        """执行任务（调用 Agent 框架）"""
+        pass
+
+    def get_queue_status(self, trace_id: str) -> dict:
+        """获取队列状态"""
+        pass
+```
+
+### ExecutionContext
+
+**实现位置：** `gateway/core/executor/execution_context.py`
+
+**职责：**
+- 管理任务执行上下文
+- 提供 Agent 执行所需的环境信息
+- 记录执行日志
+
+**核心接口：**
+
+```python
+class ExecutionContext:
+    def create_context(self, task_id: str, trace_id: str) -> dict:
+        """创建执行上下文"""
+        pass
+
+    def get_workspace_path(self, trace_id: str) -> str:
+        """获取 Workspace 路径"""
+        pass
+
+    def log_execution(self, task_id: str, log_entry: dict):
+        """记录执行日志"""
+        pass
+```
+
+---
+
+## 两种 Agent 类型的调度策略
+
+### 个人助理型 Agent
+
+**调度策略：**
+- 每个用户的任务独立调度
+- 支持并发执行（不同用户的任务）
+- 同一用户的任务需要排队
+
+**实现：**
+```python
+# 每个 Trace 有独立的任务队列
+queue_key = f"task_queue:{trace_id}"
+
+# 同一 Trace 的任务串行执行
+# 不同 Trace 的任务可以并发执行
+```
+
+### 数字员工型 Agent
+
+**调度策略：**
+- 所有任务串行处理
+- 任务队列全局共享
+- Agent 主动查看和处理任务
+
+**实现：**
+```python
+# 数字员工型 Agent 共享一个全局队列
+queue_key = f"task_queue:digital_employee:{agent_id}"
+
+# 所有任务串行执行
+# Agent 通过工具主动查看队列
+```
+
+**说明：** 数字员工型 Agent 的任务队列可能由 IM Client 管理，Executor 只负责任务的提交和状态管理
+
+---
+
+## 典型流程
+
+### 同步任务执行
+
+1. 用户通过 API 提交任务
+2. TaskManager 创建任务记录（状态：pending）
+3. Scheduler 立即调度执行
+4. 调用 Agent 框架执行任务
+5. 等待执行完成
+6. 更新任务状态（completed/failed）
+7. 返回结果给用户
+
+### 异步任务执行
+
+1. 用户通过 API 提交任务
+2. TaskManager 创建任务记录（状态：pending）
+3. 立即返回 task_id 给用户
+4. Scheduler 异步调度执行
+5. 调用 Agent 框架执行任务
+6. 更新任务状态（running → completed/failed）
+7. 用户通过 task_id 查询结果
+
+### 任务取消
+
+1. 用户通过 API 取消任务
+2. TaskManager 检查任务状态
+3. 如果任务未开始（pending）→ 直接标记为 cancelled
+4. 如果任务执行中（running）→ 通知 Agent 框架停止执行
+5. 更新任务状态为 cancelled
+
+---
+
+## 与 Lifecycle 模块的集成
+
+Executor 依赖 Lifecycle 模块：
+
+1. **获取 Trace 信息**：
+   ```python
+   trace_info = lifecycle.trace_manager.get_trace(trace_id)
+   ```
+
+2. **获取 Workspace 路径**：
+   ```python
+   workspace_path = lifecycle.workspace_manager.get_workspace_path(workspace_id)
+   ```
+
+3. **检查 Trace 状态**：
+   ```python
+   # 确保 Trace 存在且可用
+   if not trace_info:
+       raise TraceNotFoundError(trace_id)
+   ```
+
+---
+
+## 与 IM 系统的集成
+
+Agent 执行任务时可能需要通过 IM 系统通信：
+
+1. **Agent 请求协作**：
+   - Agent 执行过程中通过 IM Client 发送消息给其他 Agent
+   - 等待其他 Agent 回复
+   - 继续执行任务
+
+2. **Agent 通知用户**：
+   - Agent 执行过程中通过 IM Client 发送消息给用户
+   - 用户在飞书等渠道收到通知
+
+3. **任务完成通知**：
+   - 任务完成后，可以通过 IM Client 通知用户
+   - 或者用户主动查询任务状态
+
+---
+
+## 错误处理
+
+### 任务提交失败
+
+- Trace 不存在 → 返回错误，提示创建 Trace
+- Workspace 不可用 → 返回错误，提示检查 Workspace
+
+### 任务执行失败
+
+- Agent 框架执行异常 → 记录错误日志，更新任务状态为 failed
+- 超时 → 标记任务为 failed，记录超时信息
+- 资源不足 → 任务重新入队，等待资源释放
+
+### 并发控制
+
+- 同一 Trace 的任务串行执行，避免冲突
+- 全局并发数限制，避免资源耗尽
+- 任务队列满时拒绝新任务
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：任务执行调度需求
+- [架构设计](../architecture.md)：模块在整体架构中的位置
+- [Lifecycle 模块](./lifecycle.md)：生命周期管理模块
+- [Agent Core 架构](../../../agent/docs/architecture.md)：Agent 框架核心设计

gateway/docs/core/lifecycle.md

@@ -35,9 +35,10 @@ Agent 生命周期管理，包括：
 
 ### Workspace
 
-- 每个 Trace 有独立的工作目录
+- 多个 Trace 可以共享一个 Workspace（主 Agent 和子 Agent）
 - 包含 Agent 的配置、记忆、技能等
-- 路径格式：`~/.gateway/traces/{trace_id}/workspace/`
+- 路径格式：`~/.gateway/workspaces/{workspace_id}/`
+- 需要引用计数机制，确保清理时无活跃 Trace
 
 ---
 
@@ -54,33 +55,166 @@ gateway/core/lifecycle/
 
 ## 关键功能
 
-### Trace 注册和元数据管理
+### TraceManager
 
 **实现位置：** `gateway/core/lifecycle/trace_manager.py`
 
 **职责：**
-- 注册新的 Trace
-- 查询 Trace 元数据
-- 更新 Trace 状态
+- 调用 Agent 框架创建 Trace
+- 查询 Trace 信息
+- 管理 Trace 和 Workspace 的关联关系
+
+**核心接口：**
+
+```python
+class TraceManager:
+    def create_trace(
+        self,
+        workspace_id: str,
+        agent_type: str,  # "personal_assistant" | "digital_employee"
+        metadata: dict = None
+    ) -> str:
+        """创建新 Trace，返回 trace_id"""
+        pass
+
+    def get_trace(self, trace_id: str) -> dict:
+        """查询 Trace 信息（调用 Agent 框架）"""
+        pass
+
+    def list_traces(
+        self,
+        workspace_id: str = None,
+        agent_type: str = None
+    ) -> list[dict]:
+        """查询 Trace 列表"""
+        pass
+
+    def get_workspace_id(self, trace_id: str) -> str:
+        """获取 Trace 对应的 workspace_id"""
+        pass
+```
 
-### Workspace 管理
+### WorkspaceManager
 
 **实现位置：** `gateway/core/lifecycle/workspace_manager.py`
 
 **职责：**
-- 创建 Trace 的 Workspace
-- 获取 Workspace 路径
-- 清理 Workspace
+- 创建和初始化 Workspace 目录
+- 管理 Workspace 引用计数
+- 清理无活跃 Trace 的 Workspace
+
+**核心接口：**
+
+```python
+class WorkspaceManager:
+    def create_workspace(self, workspace_id: str) -> str:
+        """创建 Workspace 目录，返回路径"""
+        pass
+
+    def get_workspace_path(self, workspace_id: str) -> str:
+        """获取 Workspace 路径"""
+        pass
+
+    def add_trace_ref(self, workspace_id: str, trace_id: str):
+        """增加 Trace 引用"""
+        pass
+
+    def remove_trace_ref(self, workspace_id: str, trace_id: str):
+        """移除 Trace 引用"""
+        pass
+
+    def cleanup_workspace(self, workspace_id: str, force: bool = False):
+        """清理 Workspace（检查引用计数，force=True 强制清理）"""
+        pass
+
+    def list_workspaces(self) -> list[dict]:
+        """列出所有 Workspace 及其引用计数"""
+        pass
+```
 
-### 配置热重载
+### ConfigWatcher
 
 **实现位置：** `gateway/core/lifecycle/config_watcher.py`
 
 **职责：**
-- 监听配置文件变化
-- 热重载配置
+- 监听 Agent 技能配置文件变化
+- 触发热重载回调
+- 不影响正在运行的 Trace
+
+**核心接口：**
+
+```python
+class ConfigWatcher:
+    def watch(self, workspace_id: str, callback: callable):
+        """监听指定 Workspace 的配置变化"""
+        pass
+
+    def stop_watch(self, workspace_id: str):
+        """停止监听"""
+        pass
+```
+
+---
+
+## 典型流程
+
+### 个人助理型 Agent 首次对话
+
+1. 用户通过飞书发送消息
+2. Routing 模块收到消息，查询是否有对应 Trace
+3. 无 Trace → 调用 `TraceManager.create_trace(workspace_id=user_id, agent_type="personal_assistant")`
+4. TraceManager 调用 Agent 框架创建 Trace，返回 trace_id
+5. 调用 `WorkspaceManager.create_workspace(workspace_id=user_id)`（如果不存在）
+6. 调用 `WorkspaceManager.add_trace_ref(workspace_id=user_id, trace_id=trace_id)`
+7. 开始对话
+
+### 数字员工型 Agent 串行处理
+
+1. 用户 A 发送消息
+2. Routing 模块查询数字员工的 Trace（共享 workspace_id）
+3. 如果无 Trace → 创建（同上）
+4. 如果有 Trace 且正在处理 → 消息进入队列
+5. 当前对话结束 → 从队列取下一条消息
+
+### 主 Agent 调用子 Agent
+
+1. 主 Agent 执行过程中需要调用子 Agent
+2. 调用 `TraceManager.create_trace(workspace_id=主Agent的workspace_id, agent_type=...)`
+3. 子 Trace 共享主 Trace 的 Workspace
+4. 调用 `WorkspaceManager.add_trace_ref(workspace_id, 子trace_id)`
+5. 子 Agent 执行完成 → `WorkspaceManager.remove_trace_ref(...)`
+
+### Workspace 清理
+
+1. Trace 结束时调用 `WorkspaceManager.remove_trace_ref(...)`
+2. WorkspaceManager 检查引用计数
+3. 引用计数为 0 → 可以清理（可选延迟清理策略）
+4. 删除 Workspace 目录
+
+---
+
+## 错误处理
+
+### Trace 创建失败
+
+- Agent 框架返回错误 → 向用户返回友好错误信息
+- Workspace 创建失败 → 清理已创建的 Trace，返回错误
+
+### Workspace 引用计数不一致
+
+- 定期检查 Workspace 引用计数和实际 Trace 状态
+- 发现不一致 → 记录日志，修正引用计数
+
+### 配置热重载失败
+
+- 配置文件格式错误 → 记录日志，保持旧配置
 - 不影响正在运行的 Trace
 
+### 并发安全
+
+- TraceManager 和 WorkspaceManager 的关键操作需要加锁
+- 避免多个请求同时创建相同 workspace_id 的 Workspace
+
 ---
 
 ## 相关文档

gateway/docs/core/routing.md

@@ -1,125 +0,0 @@
-# Routing（消息路由）
-
-**模块：** `gateway/core/routing/`
-
-## 文档维护规范
-
-0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
-1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-2. **简洁快照，日志分离** - 只记录已确认的设计
-
----
-
-## 模块职责
-
-消息路由，包括：
-
-- **飞书消息接收和转发**：接收飞书消息并转发到对应的 Agent
-- **消息路由规则管理**：管理消息路由规则
-- **Agent 联系人列表维护**：维护 Agent 的可见联系人列表
-
----
-
-## 核心概念
-
-### 消息路由
-
-- 根据配置将飞书消息路由到对应的 Trace
-- 支持两种 Agent 类型的路由规则
-
-### 飞书集成
-
-- 接收飞书消息
-- 发送消息到飞书
-- 处理飞书事件
-
-### 联系人管理
-
-- 维护每个 Agent 的可见联系人列表
-- 联系人包括：Agent ID、介绍、运行设备信息
-- 支持 Agent 之间发送消息
-
----
-
-## 模块结构
-
-```
-gateway/core/routing/
-├── router.py              # 消息路由核心
-├── feishu_connector.py    # 飞书集成
-└── contact_manager.py     # 联系人管理
-```
-
----
-
-## 关键功能
-
-### 消息路由核心
-
-**实现位置：** `gateway/core/routing/router.py`
-
-**职责：**
-- 接收消息
-- 根据路由规则转发消息
-- 管理路由规则
-
-### 飞书集成
-
-**实现位置：** `gateway/core/routing/feishu_connector.py`
-
-**职责：**
-- 接收飞书消息
-- 发送消息到飞书
-- 处理飞书事件（消息、@提及等）
-
-### 联系人管理
-
-**实现位置：** `gateway/core/routing/contact_manager.py`
-
-**职责：**
-- 注册 Agent 联系人
-- 查询联系人列表
-- 更新联系人信息
-
----
-
-## 两种 Agent 类型的路由规则
-
-### 个人助理型 Agent
-
-**路由规则：**
-```
-飞书用户 ID → Agent Trace ID
-
-示例：
-- 用户 Alice 发消息给助理账号 → 路由到 trace-alice-001
-- 用户 Bob 发消息给助理账号 → 路由到 trace-bob-001
-```
-
-**实现方式：**
-- 维护 `飞书用户 ID → Trace ID` 的映射
-- 消息到达时查找对应的 Trace
-
-### 数字员工型 Agent
-
-**路由规则：**
-```
-所有发给数字员工账号的消息 → 同一个 Trace
-
-示例：
-- 用户 Alice 发消息 → trace-receptionist
-- 用户 Bob 发消息 → trace-receptionist（同一个）
-```
-
-**工作模式：**
-- Agent 定时检查或收到新消息通知
-- Agent 通过工具主动查看消息
-- Agent 通过工具主动回复消息
-
----
-
-## 相关文档
-
-- [需求规划](../requirements.md)：消息路由需求
-- [架构设计](../architecture.md)：模块在整体架构中的位置
-- [两种 Agent 类型](../requirements.md#两种-agent-类型)：详细说明

gateway/docs/guides/digital-employee.md

@@ -1,60 +0,0 @@
-# 数字员工型 Agent 配置
-
-## 文档维护规范
-
-0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
-1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-2. **简洁快照，日志分离** - 只记录已确认的配置方式
-
----
-
-## 概述
-
-本指南介绍如何配置数字员工型 Agent。
-
----
-
-## 特征
-
-- 1 个飞书账号（数字员工） ← 所有用户
-- 1 个 Agent Trace，但有多个对话（每个用户一个）
-- Agent 可以查看所有对话的消息历史
-- 串行工作（按全局消息顺序处理，或定时检查）
-
----
-
-## 工作模式
-
-```
-1. Agent 定时检查（如每 5 分钟）或收到新消息通知
-2. 调用工具查看所有对话
-3. 调用工具查看具体消息
-4. 调用工具回复消息
-5. 串行处理下一个对话
-```
-
----
-
-## 路由规则
-
-```
-所有发给数字员工账号的消息 → 同一个 Trace
-
-示例：
-- 用户 Alice 发消息 → trace-receptionist
-- 用户 Bob 发消息 → trace-receptionist（同一个）
-```
-
----
-
-## 配置方式
-
-**说明：** 具体配置格式待设计
-
----
-
-## 相关文档
-
-- [需求规划](../requirements.md)：数字员工型 Agent 需求
-- [Routing 模块](../core/routing.md)：路由规则实现
-- [Conversations 模块](../core/conversations.md)：对话管理实现

gateway/docs/guides/personal-assistant.md

@@ -1,46 +0,0 @@
-# 个人助理型 Agent 配置
-
-## 文档维护规范
-
-0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
-1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-2. **简洁快照，日志分离** - 只记录已确认的配置方式
-
----
-
-## 概述
-
-本指南介绍如何配置个人助理型 Agent。
-
----
-
-## 特征
-
-- 1 个飞书账号（助理） ← 多个用户
-- 每个用户有独立的 Trace + Workspace
-- 聊天历史隔离
-
----
-
-## 路由规则
-
-```
-飞书用户 ID → Agent Trace ID
-
-示例：
-- 用户 Alice 发消息给助理账号 → 路由到 trace-alice-001
-- 用户 Bob 发消息给助理账号 → 路由到 trace-bob-001
-```
-
----
-
-## 配置方式
-
-**说明：** 具体配置格式待设计
-
----
-
-## 相关文档
-
-- [需求规划](../requirements.md)：个人助理型 Agent 需求
-- [Routing 模块](../core/routing.md)：路由规则实现

gateway/docs/requirements.md

@@ -1,6 +1,6 @@
 # Gateway 需求规划
 
-**更新日期：** 2026-03-12
+**更新日期：** 2026-03-14
 
 ## 文档维护规范
 
@@ -21,44 +21,74 @@
 - **动态并发**：
   - 1000 个用户可能有 1000 份 Trace 数据和 Workspace
   - 但运行中的 Agent 实例是动态的，预计 ~10 个并发
+- **Workspace 共享**：主 Agent 创建的子 Agent 可以共享同一个 Workspace
+
+### Gateway 的定位
+
+**核心定位：** 使命/职能对话系统
+
+- 用户给 Agent 分配任务
+- Agent 汇报工作、述职
+- 是"管理-执行"关系
+
+**与 IM 系统的区别：**
+- **IM 系统**：LLM 作为主体的平等交流（协作-沟通关系）
+  - Agent 之间对等通信
+  - 用户和 Agent 平等对话
+  - 可以接入飞书、微信等任何渠道
+- **Gateway**：用户对 LLM 的使命/职能对话（管理-执行关系）
+  - 用户分配任务给 Agent
+  - Agent 执行任务并汇报
+  - 通过 API 接口调用
 
 ---
 
 ## 三大核心模块
 
-### 1. Agent 生命周期管理（Lifecycle）
+### 1. 外部渠道接入（Channels）
 
 **职责：**
-- Trace 注册和元数据管理
-- Workspace 管理
-- 配置热重载
+- 接入飞书等外部渠道（个人助理型 Agent）
+- 消息路由（飞书用户 ID → Trace ID）
+- 自动创建 Trace（首次对话）
 
 **关键点：**
-- Trace 数据结构由 Agent Core 定义
-- Gateway 负责管理 Trace 的元数据和 Workspace 路径
-- 配置变更时热重载，不影响正在运行的 Trace
+- 只用于个人助理型 Agent 的飞书接入
+- 数字员工型 Agent 的飞书接入通过 IM Server
+- 使用不同的飞书账号区分两种类型
+- 首次对话自动创建 Trace 和 Workspace
+
+**详细文档：** [channels.md](./core/channels.md)
 
-### 2. 对话管理（Conversations）
+### 2. 生命周期管理（Lifecycle）
 
 **职责：**
-- 对话（Conversation）管理
-- 消息历史存储
-- 消息队列和调度
+- 调用 Agent 框架创建/查询 Trace
+- 管理 Workspace（创建、引用计数、清理）
+- 监听配置变化并热重载
 
-**关键概念：**
-- **对话（Conversation）** = 一个用户和一个 Agent 的永久对话
-- 每个对话有独立的消息历史
+**关键点：**
+- Trace 元数据由 Agent 框架管理，Gateway 不维护副本
+- 多个 Trace 可以共享一个 Workspace（主 Agent + 子 Agent）
+- Workspace 需要引用计数机制
+- 配置变更时热重载，不影响正在运行的 Trace
+
+**详细文档：** [lifecycle.md](./core/lifecycle.md)
 
-### 3. 消息路由（Routing）
+### 3. 任务执行调度（Executor）
 
 **职责：**
-- 飞书消息接收和转发
-- 消息路由规则管理
-- Agent 联系人列表维护
+- 接收用户分配的任务
+- 调度 Agent 框架执行任务
+- 管理任务执行状态和结果
+
+**关键点：**
+- 支持同步和异步任务执行
+- 管理任务队列（个人助理型 Agent）
+- 提供任务状态查询接口
+- 与 Channels 模块集成，处理来自飞书的任务
 
-**路由规则：**
-- 根据配置将飞书消息路由到对应的 Trace
-- 支持两种 Agent 类型的路由（见下文）
+**详细文档：** [executor.md](./core/executor.md)
 
 ---
 
@@ -67,57 +97,62 @@
 ### 类型 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 可以查看所有对话的消息历史
-- 串行工作（按全局消息顺序处理，或定时检查）
+**飞书接入：**
+- 通过 Gateway Channels 模块接入
+- 使用个人助理飞书账号
+- 飞书用户 ID → Trace ID（一对一映射）
+- 首次对话自动创建 Trace
 
-**工作模式：**
-- Agent 通过工具主动查看消息
-- Agent 通过工具主动回复消息
-- 类似人类的工作方式
+**任务调度：**
+- 每个用户的任务独立调度
+- 支持并发执行（不同用户的任务）
+- 同一用户的任务需要排队
 
-**示例工作流程：**
+**消息流转：**
 ```
-1. Agent 定时检查（如每 5 分钟）或收到新消息通知
-2. 调用工具查看所有对话
-3. 调用工具查看具体消息
-4. 调用工具回复消息
-5. 串行处理下一个对话
+飞书用户 → Gateway Channels → Executor → Agent 执行 → Executor → Channels → 飞书
 ```
 
-**路由规则：**
-```
-所有发给数字员工账号的消息 → 同一个 Trace
+### 类型 2：数字员工型 Agent
 
-示例：
-- 用户 Alice 发消息 → trace-receptionist
-- 用户 Bob 发消息 → trace-receptionist（同一个）
+**特征：**
+- 所有用户共享一个 Trace
+- 每个用户有独立的对话（通过 IM 系统）
+- 串行工作（按全局消息顺序处理）
+
+**使用场景：**
+- 前台接待
+- 客服中心
+- 工单处理
+
+**飞书接入：**
+- 通过 IM Server 接入（不通过 Gateway）
+- 使用数字员工飞书账号
+- 所有用户消息 → 同一个 Trace
+- 消息队列由 IM Client 管理
+
+**任务调度：**
+- 所有任务串行处理
+- 任务队列由 IM Client 管理
+- Agent 主动查看和处理任务
+
+**消息流转：**
+```
+飞书用户 → IM Server → IM Client → Agent 主动查看 → Agent 执行 → IM Client → IM Server → 飞书
 ```
 
 ---
 
-## 两种 Agent 接入方式
+## 两种接入方式
 
 ### 内部 Agent（同设备，我们的框架）
 
@@ -131,6 +166,21 @@
 - Webhook
 - 网络通信
 
+**使用方式：**
+```python
+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（其他设备/其他框架）
 
 **特点：**
@@ -143,42 +193,50 @@
 - Webhook 接收消息
 - 网络通信
 
----
+**使用方式：**
+```python
+from gateway.client.python import GatewayClient
 
-## 联系人管理
+client = GatewayClient("http://gateway-host:8000")
 
-**职责：**
-- 维护每个注册 Agent 的可见联系人列表
-- 联系人包括：Agent ID、介绍、运行设备信息
-- 支持 Agent 之间发送消息
+# 创建 Trace
+trace_id = client.create_trace(workspace_id="user_001", agent_type="personal_assistant")
 
-**说明：**
-- Agent 介绍中可能体现其运行在不同设备
-- 具体实现细节待后续设计
+# 提交任务
+task_id = client.submit_task(trace_id, task_description="分析销售数据")
+```
 
 ---
 
-## 企业功能（可选）
+## 与 IM 系统的集成
 
-### 认证授权（Auth）
-- API Key 认证
-- OAuth 集成
-- 权限控制
-- 单点登录
+Gateway 管理的 Agent 可以通过 IM Client 参与 IM 系统的通信：
 
-### 审计日志（Audit）
-- 操作日志记录
-- 消息审计
-- 合规报告
+### Agent 主动通信
 
-### 多租户（Multi-Tenant）
-- 租户隔离
-- 资源配额
-- 计费管理
+- 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 可以同时参与两种对话模式
 
 ---
 
@@ -191,6 +249,13 @@
 - 当前阶段暂不实现
 - 未来如有需求再考虑
 
+### 其他外部渠道
+
+**说明：**
+- 当前只实现飞书接入（个人助理型）
+- 微信、钉钉等其他渠道暂不实现
+- 未来可以参考飞书集成方式扩展
+
 ---
 
 ## 相关文档
@@ -199,4 +264,5 @@
 - [Gateway 架构](./architecture.md)：Gateway 架构设计
 - [核心模块文档](./core/)：各核心模块详细文档
 - [API 文档](./api/)：HTTP API 参考
-- [设计决策](./decisions.md)：架构决策记录
+- [IM Server 架构](../../im-server/docs/architecture.md)：IM 系统架构设计
+- [IM Client 文档](../../im-client/docs/)：IM Client 使用指南

im-client/README.md

@@ -0,0 +1,191 @@
+# IM Client - Agent 即时通讯客户端
+
+**Agent 的通信客户端工具**，管理消息历史、联系人、消息收发。
+
+## 概述
+
+IM Client 是每个 Agent 的通信客户端，负责：
+
+- **消息收发**：与 IM Server 通信，发送和接收消息
+- **消息历史**：存储该 Agent 的所有对话消息历史
+- **联系人管理**：管理该 Agent 的联系人列表
+- **消息队列**：管理待处理的消息（特别是数字员工型 Agent）
+
+## 核心功能
+
+- **连接 IM Server**：建立和维护与 IM Server 的连接
+- **发送消息**：发送消息给指定联系人（Agent 或用户）
+- **接收消息**：接收来自其他主体的消息
+- **消息历史存储**：本地存储消息历史（在 Workspace 内）
+- **联系人管理**：维护联系人列表和信息
+
+## 存储位置
+
+IM Client 的数据存储在 Agent 的 Workspace 内：
+
+```
+~/.gateway/workspaces/{workspace_id}/
+├── im_client/
+│   ├── config.json              # IM Client 配置
+│   ├── contacts.json            # 联系人列表
+│   ├── conversations/           # 对话历史
+│   │   ├── {conversation_id}.jsonl
+│   │   └── ...
+│   └── queue/                   # 消息队列（数字员工型）
+│       └── pending.json
+```
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    IM Client                             │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Connection Manager（连接管理）                      │ │
+│  │ - 连接 IM Server                                    │ │
+│  │ - 心跳保活                                          │ │
+│  │ - 断线重连                                          │ │
+│  └────────────────────────────────────────────────────┘ │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Message Handler（消息处理）                         │ │
+│  │ - 发送消息                                          │ │
+│  │ - 接收消息                                          │ │
+│  │ - 消息确认                                          │ │
+│  └────────────────────────────────────────────────────┘ │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Storage Manager（存储管理）                         │ │
+│  │ - 消息历史存储                                      │ │
+│  │ - 联系人管理                                        │ │
+│  │ - 消息队列管理                                      │ │
+│  └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+                         ↑
+                         │ IM Protocol
+                         │
+                    ┌────▼────┐
+                    │IM Server│
+                    └─────────┘
+```
+
+## 目录结构
+
+```
+im-client/
+├── core/                          # 核心功能
+│   ├── connection.py              # 连接管理
+│   ├── message_handler.py         # 消息处理
+│   └── storage.py                 # 存储管理
+│
+├── api/                           # Python API
+│   └── client.py                  # IMClient 类
+│
+└── docs/                          # 文档
+    ├── architecture.md            # 架构设计
+    ├── api.md                     # API 文档
+    └── storage.md                 # 存储格式文档
+```
+
+## 快速开始
+
+### 创建 IM Client 实例
+
+```python
+from im_client.api.client import IMClient
+
+# 创建 IM Client
+client = IMClient(
+    workspace_path="~/.gateway/workspaces/user_001",
+    im_server_url="http://im-server:8080",
+    agent_id="agent_001"
+)
+
+# 连接 IM Server
+client.connect()
+```
+
+### 发送消息
+
+```python
+# 发送消息给指定联系人
+client.send_message(
+    to="agent_002",
+    text="你好，我需要你的帮助"
+)
+```
+
+### 接收消息
+
+```python
+# 注册消息处理回调
+def on_message(message):
+    print(f"收到消息：{message['text']}")
+    print(f"来自：{message['from']}")
+
+client.on_message(on_message)
+
+# 或者主动查询消息队列（数字员工型）
+messages = client.get_pending_messages()
+for msg in messages:
+    print(msg)
+```
+
+### 查询消息历史
+
+```python
+# 查询与指定联系人的对话历史
+messages = client.get_conversation_history(
+    contact_id="agent_002",
+    limit=50
+)
+
+for msg in messages:
+    print(f"{msg['from']}: {msg['text']}")
+```
+
+### 管理联系人
+
+```python
+# 添加联系人
+client.add_contact(
+    contact_id="agent_002",
+    name="助理 Agent",
+    description="负责数据分析的助理"
+)
+
+# 查询联系人列表
+contacts = client.list_contacts()
+for contact in contacts:
+    print(f"{contact['name']}: {contact['description']}")
+```
+
+## 文档
+
+### 核心文档
+
+- [架构设计](./docs/architecture.md)：IM Client 架构和核心模块
+- [API 文档](./docs/api.md)：Python API 参考
+- [存储格式](./docs/storage.md)：消息历史和联系人的存储格式
+
+## 开发状态
+
+### 待设计 📋
+
+- 架构设计
+- API 设计
+- 存储格式设计
+- IM 协议实现
+
+### 待实现 📋
+
+- 核心代码实现
+- Python API 实现
+- 存储管理实现
+
+## 相关项目
+
+- [IM Server](../im-server/README.md)：IM 通信服务器
+- [Gateway](../gateway/README.md)：Agent 管理系统
+- [Agent Core](../agent/README.md)：Agent 核心框架

im-server/README.md

@@ -0,0 +1,149 @@
+# IM Server - Agent 即时通讯服务器
+
+**通用的 Agent 间通信系统**，支持所有主体（Agent、用户）的平等交流。
+
+## 概述
+
+IM Server 是一个通用的即时通讯服务器，专注于"主体间平等交流"：
+
+- **主体间交流**：Agent ↔ Agent、Agent ↔ 用户的平等对话
+- **协作-沟通关系**：所有参与者都是平等主体
+- **LLM 作为主体**：LLM 主动参与对话，而不是被动响应
+
+**与 Gateway 的区别：**
+- **IM Server**：LLM 作为主体的平等交流（协作-沟通关系）
+- **Gateway**：用户对 LLM 的使命/职能对话（管理-执行关系）
+
+## 核心功能
+
+- **消息转发**：在 IM Client 之间转发消息
+- **联系人管理**：管理每个 Agent 的联系人列表
+- **渠道接入**：支持飞书、微信等外部渠道接入
+- **消息历史**：存储和查询消息历史（可选）
+
+## 支持的 Agent 框架
+
+- 自研 Agent 框架
+- Claude Code
+- OpenClaw
+- 任何实现了 IM Client 协议的 Agent
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    IM Server                             │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Message Router（消息路由）                          │ │
+│  │ - 接收来自 IM Client 的消息                         │ │
+│  │ - 根据目标地址转发消息                              │ │
+│  └────────────────────────────────────────────────────┘ │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Contact Manager（联系人管理）                       │ │
+│  │ - 管理每个 Agent 的联系人列表                       │ │
+│  │ - 联系人信息同步                                    │ │
+│  └────────────────────────────────────────────────────┘ │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │ Channel Connector（渠道连接器）                     │ │
+│  │ - 飞书集成                                          │ │
+│  │ - 微信集成                                          │ │
+│  │ - 其他渠道...                                       │ │
+│  └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+                         ↑
+                         │ IM Protocol
+                         │
+        ┌────────────────┼────────────────┐
+        │                │                │
+   ┌────▼────┐      ┌───▼────┐      ┌───▼────┐
+   │IM Client│      │IM Client│     │IM Client│
+   │(自研)   │      │(Claude  │     │(飞书用户)│
+   │         │      │ Code)   │     │         │
+   └─────────┘      └─────────┘     └─────────┘
+```
+
+## 目录结构
+
+```
+im-server/
+├── core/                          # 核心服务
+│   ├── router.py                  # 消息路由
+│   ├── contact_manager.py         # 联系人管理
+│   └── channel_connector.py       # 渠道连接器
+│
+├── channels/                      # 渠道集成
+│   ├── feishu.py                  # 飞书集成
+│   ├── wechat.py                  # 微信集成
+│   └── ...
+│
+├── api/                           # HTTP API
+│   └── server.py                  # API 服务器
+│
+└── docs/                          # 文档
+    ├── architecture.md            # 架构设计
+    ├── protocol.md                # IM 协议规范
+    └── channels/                  # 渠道集成文档
+```
+
+## 快速开始
+
+### 启动 IM Server
+
+```bash
+# 安装依赖
+pip install -r requirements.txt
+
+# 启动服务器
+python -m im_server.api.server --host 0.0.0.0 --port 8080
+```
+
+### 配置渠道
+
+```yaml
+# config.yaml
+channels:
+  feishu:
+    app_id: "your_app_id"
+    app_secret: "your_app_secret"
+    enabled: true
+
+  wechat:
+    enabled: false
+```
+
+## 文档
+
+### 核心文档
+
+- [架构设计](./docs/architecture.md)：IM Server 架构和核心模块
+- [IM 协议规范](./docs/protocol.md)：IM Client 和 IM Server 之间的通信协议
+
+### 渠道集成文档
+
+- [飞书集成](./docs/channels/feishu.md)：飞书渠道接入指南
+- [微信集成](./docs/channels/wechat.md)：微信渠道接入指南
+
+## 开发状态
+
+### 待设计 📋
+
+- 架构设计
+- IM 协议规范
+- 消息路由机制
+- 联系人管理机制
+- 渠道接入机制
+
+### 待实现 📋
+
+- 核心代码实现
+- 渠道集成实现
+- API 服务器实现
+
+## 相关项目
+
+- [Gateway](../gateway/README.md)：Agent 管理系统
+- [IM Client](../im-client/README.md)：IM 客户端工具
+- [Agent Core](../agent/README.md)：Agent 核心框架