doc: gateway redesign

gateway/README.md

@@ -1,441 +1,140 @@
-# Gateway - Agent 消息路由服务
+# Gateway - Agent 消息路由和生命周期管理服务
 
-**框架无关的 Agent 间即时通讯网关**，提供 Agent 注册、消息路由（Webhook 推送）、在线状态管理。
+**框架无关的 Agent 即时通讯网关**，提供 Agent 生命周期管理、消息路由、对话管理。
 
 ## 概述
 
-Gateway 是一个任务导向的 Agent 即时通讯系统，支持任何 Agent 框架使用。核心功能：
+Gateway 是一个 Agent 即时通讯和管理系统，支持任何 Agent 框架使用。核心功能：
 
-- Agent 注册和发现
-- 消息路由（HTTP Webhook 推送）
-- 在线状态管理（HTTP 心跳）
-- 活跃协作者管理
+- **Agent 生命周期管理**：Trace 注册、Workspace 管理、配置热重载
+- **对话管理**：对话管理、消息历史、消息队列
+- **消息路由**：飞书集成、消息路由、联系人管理
 
 **独立性**：Gateway 与 Agent Core 并列，可以独立部署。
 
 ## 设计原则
 
 1. **框架无关**：Gateway 核心不依赖任何特定的 Agent 框架
-2. **纯 HTTP**：所有交互均通过标准 HTTP API 完成，无 WebSocket 依赖
-3. **易于集成**：提供通用的 Python SDK 和 CLI 工具
-4. **可扩展**：支持不同框架的适配和集成
+2. **分层架构**：Core 层（内部接口）+ API 层（外部接口）
+3. **易于集成**：内部 Agent 直接调用，外部 Agent 使用 SDK
+4. **可扩展**：支持企业功能扩展（认证、审计、多租户）
 
 ## 架构
 
 ```
 gateway/
-├── core/              # Gateway 核心服务（框架无关）
-│   ├── registry.py    # Agent 注册和在线状态管理（含 webhook_url）
-│   └── router.py      # HTTP API 端点和消息路由
+├── core/                          # 核心服务层（内部接口）
+│   ├── lifecycle/                 # Agent 生命周期管理
+│   │   ├── 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 注册表（保留，兼容旧代码）
 │
-├── client/            # 通用客户端工具
-│   ├── python/        # Python SDK
-│   │   ├── tools.py   # 通用工具函数
-│   │   ├── client.py  # GatewayClient
-│   │   └── cli.py     # CLI 工具
-│   └── a2a_im.md      # Agent Skill 文档
+├── api/                           # HTTP API 层（外部接口）
+│   ├── lifecycle_api.py           # 生命周期管理 API
+│   ├── conversations_api.py       # 对话管理 API
+│   └── routing_api.py             # 消息路由 API
 │
-├── docs/              # 详细文档
-│   ├── architecture.md
-│   ├── deployment.md
-│   ├── api.md
-│   ├── decisions.md
-│   └── enterprise/
+├── enterprise/                    # 企业功能（可选）
+│   ├── auth/                      # 认证授权
+│   ├── audit/                     # 审计日志
+│   └── multi_tenant/              # 多租户
 │
-└── enterprise/        # 企业功能（可选）
-    ├── auth.py
-    ├── audit.py
-    └── cost.py
-
-examples/gateway_integration/  # 集成示例（项目根目录）
-```
-
-## 快速开始
-
-### 1. 启动 Gateway 服务
-
-```bash
-python gateway_server.py
-```
-
-服务器将在 `http://localhost:8001` 启动。
-
-### 2. 注册 Agent（含 Webhook 地址）
-
-```python
-from gateway.client.python import GatewayClient, AgentCard
-
-client = GatewayClient(
-    gateway_url="http://localhost:8001",
-    agent_card=AgentCard(
-        agent_id="my-agent-001",
-        agent_name="My Agent",
-        capabilities=["search", "analyze"]
-    ),
-    webhook_url="http://my-agent.local:8080/webhook/a2a-messages"
-)
-await client.connect()  # 注册 + 启动心跳
-```
-
-### 3. 发送消息
-
-```python
-await client.send_message(
-    to_agent_id="target-agent",
-    content=[{"type": "text", "text": "Hello"}],
-    conversation_id="conv-123"
-)
-```
-
-### 4. 接收消息（Webhook）
-
-在 Agent 服务中添加 webhook 端点，Gateway 收到消息后会 POST 到此地址：
-
-```python
-# api_server.py
-@app.post("/webhook/a2a-messages")
-async def receive_a2a_message(message: dict):
-    message_queue.push(message)
-    return {"status": "received"}
-```
-
-消息通过 **Context Injection Hook** 机制周期性提醒 LLM，由 LLM 调用 `check_messages` 工具查看详情。详见 [消息通知机制](./docs/architecture.md#消息通知到-agentllm)。
-
-### 5. 使用 CLI
-
-```bash
-gateway-cli send --from my-agent --to target-agent --message "Hello!"
-gateway-cli list
-gateway-cli status target-agent
-```
-
-详见 [gateway/client/a2a_im.md](./client/a2a_im.md)（Agent Skill 文档）。
-
-## API 端点
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/gateway/register` | 注册 Agent（含 webhook_url） |
-| POST | `/gateway/heartbeat` | 心跳（每 30 秒） |
-| POST | `/gateway/unregister` | 注销 Agent |
-| POST | `/gateway/send` | 发送消息 |
-| GET  | `/gateway/status/{agent_id}` | 查询 Agent 状态 |
-| GET  | `/gateway/agents` | 列出在线 Agent |
-| GET  | `/gateway/health` | Gateway 状态 |
-
-详见 [API 文档](./docs/api.md)。
-
-## 文档
-
-- [架构设计](./docs/architecture.md)：通信流程、消息通知机制、设计决策
-- [API 文档](./docs/api.md)：完整的 API 参考
-- [部署指南](./docs/deployment.md)：部署方式和配置
-- [设计决策](./docs/decisions.md)：架构决策记录
-- [Enterprise 层](./docs/enterprise/overview.md)：认证、审计、多租户
-- [A2A IM Skill](./client/a2a_im.md)：Agent Skill 使用文档
-
-## 文档维护规范
-
-1. **先改文档，再动代码**
-2. **文档分层，链接代码** - 格式：`module/file.py:function_name`
-3. **简洁快照，日志分离** - 决策依据在 `docs/decisions.md` 记录
-
-## 相关项目
-
-- [Agent Core](../agent/README.md)：Agent 核心框架
-
-## 概述
-
-Gateway 是一个任务导向的 Agent 即时通讯系统，支持任何 Agent 框架使用。核心功能：
-
-- Agent 注册和发现
-- 消息路由（WebSocket/HTTP）
-- 在线状态管理
-- 活跃协作者管理
-- 联系人管理
-
-**独立性**：Gateway 与 Agent Core 并列，可以独立部署。
-
-**依赖关系**：Gateway 依赖 Agent Core（使用 ToolContext、TraceStore 等组件）。
-
-## 设计原则
-
-1. **框架无关**：Gateway 核心不依赖任何特定的 Agent 框架
-2. **通用协议**：使用 MAMP（Minimal Agent Message Protocol）
-3. **易于集成**：提供通用的 Python SDK 和 CLI 工具
-4. **可扩展**：支持不同框架的适配和集成
-
-## 架构
-
-```
-gateway/
-├── core/              # Gateway 核心服务（框架无关）
-│   ├── registry.py    # Agent 注册和在线状态管理
-│   ├── router.py      # 消息路由
-│   └── client.py      # Gateway 客户端
+├── client/                        # 客户端 SDK
+│   └── python/                    # Python SDK
+│       ├── client.py              # GatewayClient
+│       ├── tools.py               # 工具函数
+│       └── cli.py                 # CLI 工具
 │
-├── client/            # 通用客户端工具
-│   ├── python/        # Python SDK
-│   │   ├── tools.py   # 通用工具函数
-│   │   ├── client.py  # GatewayClient
-│   │   └── cli.py     # CLI 工具
-│   └── a2a_im.md      # Agent Skill 文档
-│
-├── docs/              # 详细文档
-│   ├── architecture.md
-│   ├── deployment.md
-│   ├── api.md
-│   ├── decisions.md
-│   └── enterprise/
-│
-└── enterprise/        # 企业功能（可选）
-    ├── auth.py        # 认证和授权
-    ├── audit.py       # 审计和监控
-    └── cost.py        # 成本管理
-
-examples/gateway_integration/  # 集成示例（项目根目录）
-├── README.md
-├── python_client_example.py      # 通用 SDK 使用示例
-├── agent_tools_example.py        # Agent 框架集成示例
-└── agent_skill_example.md        # Agent 框架 Skill 示例
+└── docs/                          # 文档
+    ├── requirements.md            # 需求规划
+    ├── architecture.md            # 架构设计
+    ├── core/                      # 核心模块文档
+    ├── api/                       # API 文档
+    ├── client/                    # 客户端文档
+    ├── guides/                    # 使用指南
+    └── decisions.md               # 设计决策
 ```
 
 ## 快速开始
 
-### 1. 启动 Gateway 服务
-
-```bash
-python gateway_server.py
-```
-
-服务器将在 `http://localhost:8001` 启动（默认端口）。
-
-### 2. 使用 CLI 工具
-
-```bash
-# 发送消息
-gateway-cli send --from my-agent --to target-agent --message "Hello!"
-
-# 查询在线 Agent
-gateway-cli list
-
-# 查询 Agent 状态
-gateway-cli status target-agent
-```
-
-详见 [gateway/client/a2a_im.md](./client/a2a_im.md)（Agent Skill 文档）。
-
-### 3. 使用 Python SDK
+### 内部 Agent（同设备，我们的框架）
 
 ```python
-from gateway.client.python import tools
-
-# 发送消息
-result = await tools.send_message(
-    gateway_url="http://localhost:8001",
-    from_agent_id="my-agent",
-    to_agent_id="target-agent",
-    message="Hello!"
-)
-
-# 查询在线 Agent
-agents = await tools.list_online_agents(
-    gateway_url="http://localhost:8001"
-)
-
-# 查询 Agent 状态
-status = await tools.get_agent_status(
-    gateway_url="http://localhost:8001",
-    agent_id="target-agent"
-)
-```
-
-### 4. 集成到 Agent 框架
-
-参考 `examples/gateway_integration/` 中的示例：
+# 直接导入 Core 层模块
+from gateway.core.conversations import ConversationManager
 
-```python
-# 在 agent 启动时注册 Gateway 工具
-from examples.gateway_integration.agent_tools_example import (
-    send_to_agent,
-    get_active_collaborators,
-    get_online_agents,
-    get_agent_status
-)
-
-# 注册工具
-tool_registry.register(send_to_agent)
-tool_registry.register(get_active_collaborators)
-tool_registry.register(get_online_agents)
-tool_registry.register(get_agent_status)
-
-# 加载 skill
-skill_loader.load("gateway/client/a2a_im.md")
+manager = ConversationManager()
+messages = manager.get_messages(conversation_id)
 ```
 
-## 核心功能
-
-### Agent 注册
-
-PC Agent 启动时通过 WebSocket 连接到 Gateway 并注册。
-
-**实现位置**：`gateway/core/registry.py:AgentRegistry`
+### 外部 Agent（其他设备/其他框架）
 
 ```python
-from gateway.client.python import GatewayClient, AgentCard
-
-# 创建客户端并注册
-async with GatewayClient(
-    gateway_url="http://localhost:8001",
-    agent_card=AgentCard(
-        agent_id="my-agent-001",
-        agent_name="My Agent",
-        capabilities=["search", "analyze"]
-    )
-) as client:
-    # 发送消息
-    await client.send_message(
-        to_agent_id="target-agent",
-        content=[{"type": "text", "text": "Hello"}],
-        conversation_id="conv-123"
-    )
-```
-
-### 消息路由
-
-Gateway 根据目标 Agent ID 路由消息。
+# 使用 Client SDK
+from gateway.client.python import GatewayClient
 
-**实现位置**：`gateway/core/router.py:GatewayRouter`
-
-```python
-# 发送消息
-POST /gateway/send
-{
-    "from_agent_id": "my-agent",
-    "to_agent_id": "target-agent",
-    "content": [{"type": "text", "text": "帮我分析代码"}]
-}
+client = GatewayClient("http://gateway-host:8000")
+messages = client.get_messages(conversation_id)
 ```
 
-### 在线状态管理
-
-通过心跳机制跟踪 Agent 在线状态。
-
-**实现位置**：`gateway/core/registry.py:AgentRegistry.heartbeat`
-
-```python
-# 查询在线状态
-GET /gateway/status/{agent_id}
-```
-
-## API 端点
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| WS | `/gateway/connect` | Agent 注册和保持连接 |
-| POST | `/gateway/send` | 发送消息到其他 Agent |
-| GET | `/gateway/status/{agent_id}` | 查询 Agent 在线状态 |
-| GET | `/gateway/agents` | 列出所有在线 Agent |
-
-**实现位置**：`gateway/core/router.py:GatewayRouter`
-
-详见 [API 文档](./docs/api.md)。
-
-## 部署方式
-
-### 方式 1：单体部署
-
-```bash
-# 一个进程运行 Agent + Gateway
-python main.py
-```
-
-### 方式 2：分离部署
-
-```bash
-# 两个独立进程
-python api_server.py      # Agent Core
-python gateway_server.py  # Gateway
-```
-
-### 方式 3：分层部署
-
-```bash
-# 三个独立进程
-python api_server.py              # Agent Core
-python gateway_server.py          # Gateway Core
-python enterprise_gateway.py      # Enterprise Gateway
-```
-
-详见 [部署指南](./docs/deployment.md)。
-
-## 为其他框架创建集成
-
-参考 `examples/gateway_integration/` 中的示例创建你自己的集成：
-
-1. 使用 `gateway/client/python/` 的通用 SDK 或 CLI 工具
-2. 创建适配你框架的工具/函数
-3. 根据需要适配框架特有的功能
-
-详见 [集成示例文档](../examples/gateway_integration/README.md)。
-
 ## 文档
 
-### 模块文档（gateway/docs/）
+### 核心文档
 
-- [架构设计](./docs/architecture.md)：Gateway 架构和设计决策
-- [部署指南](./docs/deployment.md)：部署方式和配置
-- [API 文档](./docs/api.md)：完整的 API 参考
-- [设计决策](./docs/decisions.md)：架构决策记录
-- [Enterprise 层](./docs/enterprise/overview.md)：组织级功能（认证、审计、多租户）
+- [需求规划](./docs/requirements.md)：已确认的需求和功能范围
+- [架构设计](./docs/architecture.md)：Gateway 架构和核心模块
+- [文档索引](./docs/README.md)：完整文档导航
 
-### 项目级文档（../docs/）
+### 模块文档（待创建）
 
-- [A2A IM 系统](../docs/a2a-im.md)：完整的 A2A IM 文档
-- [MAMP 协议](../docs/research/a2a-mamp-protocol.md)：消息格式和传输协议
+- 核心模块文档：`docs/core/`
+- API 文档：`docs/api/`
+- 客户端文档：`docs/client/`
+- 使用指南：`docs/guides/`
 
-### 客户端文档
+### 其他文档
 
-- [A2A IM Skill](./client/a2a_im.md)：Agent Skill 使用文档
-- [Client README](./client/README.md)：客户端安装和配置
+- [设计决策](./docs/decisions.md)：架构决策记录
+- [部署指南](./docs/deployment.md)：部署方式和配置
+- [企业功能](./docs/enterprise/)：企业功能文档（可选）
 
 ## 文档维护规范
 
-1. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
-2. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-3. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议，或大量代码；决策依据或修改日志若有必要，可在`docs/decisions.md`另行记录
+1. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+2. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+3. **简洁快照，日志分离** - 只记录已确认的需求和设计，避免推测和未确认的内容
+
+## 开发状态
 
-## 是否应该拆分到独立 Git 项目？
+### 已实现
 
-**当前建议：暂时不拆分**
+- ✅ Agent 注册和在线状态管理（旧版）
+- ✅ 消息路由（Webhook 推送，旧版）
 
-理由：
-- ✅ Gateway 和 Agent 框架还在快速迭代
-- ✅ 保持在 monorepo 便于协同开发
-- ✅ 避免版本兼容性管理的复杂度
+### 开发中
 
-**未来拆分时机**（满足以下条件时考虑）：
-- Gateway API 稳定（v1.0）
-- 有其他团队/项目开始使用 Gateway
-- Gateway 和 Agent 的发布周期明显不同
+- 🚧 重构为新架构（Core 层 + API 层）
+- 🚧 Agent 生命周期管理
+- 🚧 对话管理
+- 🚧 飞书集成
 
-**现在的准备**：
-- ✅ Gateway 核心完全独立（不依赖 agent 模块）
-- ✅ 通用的 Gateway 客户端 SDK 和 CLI 工具
-- ✅ 集成示例在 examples/ 目录
-- ✅ 独立的文档结构
-- ⚠️ 独立的测试（待完善）
+### 计划中
 
-当需要拆分时，只需：
-1. 将 `gateway/` 目录移到新仓库
-2. 在 Agent 项目中通过 pip 安装 Gateway SDK
-3. 保持 `examples/gateway_integration/` 在 Agent 项目中作为集成示例
+- 📋 联系人管理
+- 📋 企业功能（认证、审计、多租户）
 
 ## 相关项目
 
 - [Agent Core](../agent/README.md)：Agent 核心框架
-
-## License
-
-MIT
-

gateway/docs/README.md

@@ -0,0 +1,116 @@
+# Gateway 文档索引
+
+本目录包含 Gateway 的完整文档。
+
+## 文档维护规范
+
+1. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+2. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+3. **简洁快照，日志分离** - 只记录已确认的需求和设计，避免推测和未确认的内容
+
+---
+
+## 核心文档
+
+### [需求规划](./requirements.md)
+**状态：** ✅ 已确认
+
+已确认的功能需求和范围：
+- Agent 生命周期管理
+- 对话管理（Conversations）
+- 消息路由（Routing）
+- 两种 Agent 类型（个人助理、数字员工）
+- 两种接入方式（内部、外部）
+- 企业功能（可选）
+
+### [架构设计](./architecture.md)
+**状态：** ✅ 已确认
+
+Gateway 的架构设计和核心模块：
+- 分层架构（Core 层、API 层）
+- 三大核心模块（Lifecycle、Conversations、Routing）
+- 两种接入方式
+- 企业功能
+
+---
+
+## 模块文档
+
+### 核心模块（Core）
+
+**状态：** ✅ 已创建
+
+- [lifecycle.md](./core/lifecycle.md) - 生命周期管理模块
+- [conversations.md](./core/conversations.md) - 对话管理模块
+- [routing.md](./core/routing.md) - 消息路由模块
+
+### API 文档
+
+**状态：** ✅ 已创建
+
+- [lifecycle.md](./api/lifecycle.md) - 生命周期管理 API
+- [conversations.md](./api/conversations.md) - 对话管理 API
+- [routing.md](./api/routing.md) - 消息路由 API
+
+### 客户端文档
+
+**状态：** ✅ 已创建
+
+- [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 配置
+
+---
+
+## 其他文档
+
+### [设计决策](./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/** - 核心模块文档（3 个文件）
+5. **api/** - API 文档（3 个文件）
+6. **client/** - 客户端文档（1 个文件）
+7. **guides/** - 使用指南（5 个文件）
+
+**总计：** 15 个文档文件已创建
+
+---
+
+## 相关文档
+
+- [Agent Core 架构](../../agent/docs/architecture.md)：Agent 框架核心设计
+- [Gateway README](../README.md)：项目概览
+- [Gateway 客户端](../client/README.md)：客户端 SDK 和 CLI 工具

gateway/docs/api/conversations.md

@@ -0,0 +1,59 @@
+# Conversations API
+
+**HTTP API：** 对话管理
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的 API 设计
+
+---
+
+## 概述
+
+对话管理 API 供外部 Agent 调用，用于：
+
+- 查询对话列表
+- 获取消息历史
+- 发送消息
+
+**实现位置：** `gateway/api/conversations_api.py`
+
+**基础路径：** `/api/conversations`
+
+---
+
+## API 端点
+
+### 列出对话
+
+**端点：** `GET /api/conversations`
+
+**用途：** 列出所有对话
+
+**说明：** 具体请求/响应格式待设计
+
+### 获取消息历史
+
+**端点：** `GET /api/conversations/{conversation_id}/messages`
+
+**用途：** 获取对话的消息历史
+
+**说明：** 具体请求/响应格式待设计
+
+### 发送消息
+
+**端点：** `POST /api/conversations/{conversation_id}/messages`
+
+**用途：** 向对话发送消息
+
+**说明：** 具体请求/响应格式待设计
+
+---
+
+## 相关文档
+
+- [Conversations 核心模块](../core/conversations.md)：核心实现
+- [需求规划](../requirements.md)：对话管理需求
+- [架构设计](../architecture.md)：API 层在整体架构中的位置

gateway/docs/api/lifecycle.md

@@ -0,0 +1,59 @@
+# Lifecycle API
+
+**HTTP API：** 生命周期管理
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的 API 设计
+
+---
+
+## 概述
+
+生命周期管理 API 供外部 Agent 调用，用于：
+
+- 注册 Trace
+- 查询 Trace 信息
+- 管理 Workspace
+
+**实现位置：** `gateway/api/lifecycle_api.py`
+
+**基础路径：** `/api/lifecycle`
+
+---
+
+## API 端点
+
+### 注册 Trace
+
+**端点：** `POST /api/lifecycle/traces/register`
+
+**用途：** 注册新的 Trace
+
+**说明：** 具体请求/响应格式待设计
+
+### 查询 Trace 信息
+
+**端点：** `GET /api/lifecycle/traces/{trace_id}`
+
+**用途：** 查询 Trace 的元数据和状态
+
+**说明：** 具体请求/响应格式待设计
+
+### 获取 Workspace 路径
+
+**端点：** `GET /api/lifecycle/traces/{trace_id}/workspace`
+
+**用途：** 获取 Trace 的 Workspace 路径
+
+**说明：** 具体请求/响应格式待设计
+
+---
+
+## 相关文档
+
+- [Lifecycle 核心模块](../core/lifecycle.md)：核心实现
+- [需求规划](../requirements.md)：生命周期管理需求
+- [架构设计](../architecture.md)：API 层在整体架构中的位置

gateway/docs/api/routing.md

@@ -0,0 +1,59 @@
+# Routing API
+
+**HTTP API：** 消息路由
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的 API 设计
+
+---
+
+## 概述
+
+消息路由 API 供外部 Agent 调用，用于：
+
+- 查询联系人列表
+- 发送消息到其他 Agent
+- 管理路由规则
+
+**实现位置：** `gateway/api/routing_api.py`
+
+**基础路径：** `/api/routing`
+
+---
+
+## API 端点
+
+### 查询联系人列表
+
+**端点：** `GET /api/routing/contacts`
+
+**用途：** 查询当前 Agent 的可见联系人列表
+
+**说明：** 具体请求/响应格式待设计
+
+### 发送消息
+
+**端点：** `POST /api/routing/messages`
+
+**用途：** 发送消息到其他 Agent
+
+**说明：** 具体请求/响应格式待设计
+
+### 查询路由规则
+
+**端点：** `GET /api/routing/rules`
+
+**用途：** 查询消息路由规则
+
+**说明：** 具体请求/响应格式待设计
+
+---
+
+## 相关文档
+
+- [Routing 核心模块](../core/routing.md)：核心实现
+- [需求规划](../requirements.md)：消息路由需求
+- [架构设计](../architecture.md)：API 层在整体架构中的位置

gateway/docs/architecture.md

@@ -1,238 +1,199 @@
 # Gateway 架构设计
 
-**更新日期：** 2026-03-05
+**更新日期：** 2026-03-12
 
 ## 文档维护规范
 
 0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
 1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
-2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或明确的已完成的设计
+2. **简洁快照，日志分离** - 只记录已确认的架构设计
 
 ---
 
 ## 架构概述
 
-Gateway 采用两层架构：
+Gateway 采用分层架构：
 
 ```
-┌─────────────────────────────────────────────────┐
-│ Router 层（路由和 API）                          │
-│ - HTTP API 端点                                  │
-│ - 消息路由（Webhook 推送）                       │
-└─────────────────────────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│ Registry 层（注册和状态）                         │
-│ - Agent 注册信息（含 webhook_url）               │
-│ - 在线状态管理                                    │
-│ - 心跳超时检测                                    │
-└─────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│ API 层（HTTP 接口）                                          │
+│ - 供外部 Agent 调用                                          │
+│ - RESTful API                                               │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────┐
+│ Core 层（核心服务）                                          │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Lifecycle（生命周期管理）                            │  │
+│  │ - Trace 注册和元数据管理                             │  │
+│  │ - Workspace 管理                                    │  │
+│  │ - 配置热重载                                         │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Conversations（对话管理）                            │  │
+│  │ - 对话管理                                           │  │
+│  │ - 消息历史存储                                       │  │
+│  │ - 消息队列和调度                                     │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Routing（消息路由）                                  │  │
+│  │ - 飞书消息接收和转发                                 │  │
+│  │ - 消息路由规则管理                                   │  │
+│  │ - Agent 联系人列表维护                               │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## 核心组件
-
-### AgentRegistry
-
-管理在线 Agent 的注册信息。
-
-**实现位置**：`gateway/core/registry.py:AgentRegistry`
-
-**职责**：
-- Agent 注册和注销（含 webhook_url）
-- 在线状态跟踪
-- 心跳超时检测
-- 自动清理过期连接
-
-**关键方法**：
-- `register(agent_id, webhook_url, ...)` - 注册 Agent
-- `unregister(agent_id)` - 注销 Agent
-- `heartbeat(agent_id)` - 更新心跳
-- `is_online(agent_id)` - 检查在线状态
-- `list_agents()` - 列出 Agent
-
-### GatewayRouter
-
-处理消息路由和 HTTP API 端点。
-
-**实现位置**：`gateway/core/router.py:GatewayRouter`
-
-**职责**：
-- Agent 注册/注销/心跳端点
-- 消息接收，Webhook 推送到目标 Agent
-- 在线状态查询
-- Agent 列表查询
-
-**API 端点**：
-- `POST /gateway/register` - Agent 注册
-- `POST /gateway/heartbeat` - 心跳
-- `POST /gateway/unregister` - 注销
-- `POST /gateway/send` - 发送消息
-- `GET /gateway/status/{agent_id}` - 查询状态
-- `GET /gateway/agents` - 列出 Agent
-- `GET /gateway/health` - Gateway 状态
-
-详见 [API 文档](./api.md)。
-
-### GatewayClient（SDK）
-
-Agent 端用于与 Gateway 交互的客户端。
-
-**实现位置**：`gateway/client/python/client.py:GatewayClient`
-
-**职责**：
-- HTTP 注册/注销/心跳
-- 发送消息
-- 查询 Agent 列表和状态
-
----
-
-## 通信流程
-
-### Agent 注册流程
+## 模块结构
 
 ```
-Agent                       Gateway
-   │                           │
-   │  POST /gateway/register   │
-   │  {agent_id, webhook_url,  │
-   │   capabilities, ...}      │
-   ├──────────────────────────>│
-   │                           │  Registry.register()
-   │                           │  保存 webhook_url
-   │                           │
-   │  {"status": "registered"} │
-   │<──────────────────────────┤
-   │                           │
-   │  POST /gateway/heartbeat  │  (每 30 秒)
-   ├──────────────────────────>│
-   │                           │  Registry.heartbeat()
-   │<──────────────────────────┤
-```
-
-### 消息路由流程
-
-```
-Agent A                 Gateway                 Agent B
-   │                       │                       │
-   │  POST /gateway/send   │                       │
-   │  {from, to, content}  │                       │
-   ├──────────────────────>│                       │
-   │                       │  Registry.lookup()    │
-   │                       │  获取 webhook_url     │
-   │                       │                       │
-   │                       │  POST {webhook_url}   │
-   │                       ├──────────────────────>│
-   │                       │                       │  message_queue.push()
-   │                       │  200 OK               │
-   │                       │<──────────────────────┤
-   │                       │                       │
-   │  {"status": "sent"}   │                       │
-   │<──────────────────────┤                       │
+gateway/
+├── core/                          # 核心服务层（内部接口）
+│   ├── lifecycle/                 # Agent 生命周期管理
+│   │   ├── 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 注册表（保留，兼容旧代码）
+│
+├── api/                           # HTTP API 层（外部接口）
+│   ├── lifecycle_api.py           # 生命周期管理 API
+│   ├── conversations_api.py       # 对话管理 API
+│   └── routing_api.py             # 消息路由 API
+│
+├── enterprise/                    # 企业功能（可选）
+│   ├── auth/                      # 认证授权
+│   ├── audit/                     # 审计日志
+│   └── multi_tenant/              # 多租户
+│
+└── client/                        # 客户端 SDK
+    └── python/                    # Python SDK
+        ├── client.py              # GatewayClient
+        ├── tools.py               # 工具函数
+        └── cli.py                 # CLI 工具
 ```
 
 ---
 
-## 消息通知到 Agent/LLM
-
-### 设计方案：Context Injection Hook
-
-借鉴 Agent 框架中的 **Active Collaborators** 设计，通过 context injection hook 机制周期性提醒 LLM 检查消息。
-
-```
-Webhook → A2AMessageQueue → Context Hook → Runner 每 10 轮注入 → LLM
-                ↓                                                    ↓
-          消息队列                                         调用 check_messages 工具
-```
+## 核心模块
 
-### 组件
+### Lifecycle（生命周期管理）
 
-**A2AMessageQueue** - 消息缓冲队列
+**职责：**
+- Trace 注册和元数据管理
+- Workspace 管理
+- 配置热重载
 
-**实现位置**：`agent/tools/builtin/a2a_im.py:A2AMessageQueue`（待实现）
+**实现位置：**
+- `gateway/core/lifecycle/trace_manager.py`
+- `gateway/core/lifecycle/workspace_manager.py`
+- `gateway/core/lifecycle/config_watcher.py`
 
-**create_a2a_context_hook** - 创建注入钩子，有消息时返回提醒文本
+### Conversations（对话管理）
 
-**实现位置**：`agent/tools/builtin/a2a_im.py:create_a2a_context_hook`（待实现）
+**职责：**
+- 对话管理
+- 消息历史存储
+- 消息队列和调度
 
-**check_messages 工具** - LLM 调用后返回完整消息内容，并清空队列
+**实现位置：**
+- `gateway/core/conversations/conversation_manager.py`
+- `gateway/core/conversations/message_store.py`
+- `gateway/core/conversations/message_queue.py`
 
-**实现位置**：`agent/tools/builtin/a2a_im.py:check_messages`（待实现）
+### Routing（消息路由）
 
-**Runner context_hooks 参数** - 每 10 轮注入时调用所有 hooks
+**职责：**
+- 飞书消息接收和转发
+- 消息路由规则管理
+- Agent 联系人列表维护
 
-**实现位置**：`agent/core/runner.py:AgentRunner._build_context_injection`（待实现）
-
-### 注入效果
-
-```markdown
-## Current Plan
-1. [in_progress] 分析代码架构
-
-## Active Collaborators
-- researcher [agent, completed]: 已完成调研
-
-## Messages
-💬 来自 code-reviewer 的 1 条新消息（使用 check_messages 工具查看）
-```
-
-LLM 自主决定何时调用 `check_messages` 工具查看详细内容。
-
-详见 [Agent 架构文档：Context Injection Hooks](../../agent/docs/architecture.md#context-injection-hooks)
+**实现位置：**
+- `gateway/core/routing/router.py`
+- `gateway/core/routing/feishu_connector.py`
+- `gateway/core/routing/contact_manager.py`
 
 ---
 
-## 设计决策
-
-### 决策 1：消息接收采用 Webhook
+## 两种接入方式
 
-**问题**：Agent 如何接收来自 Gateway 的消息？
+### 内部 Agent 接入
 
-**决策**：Webhook 推送，Agent 注册时提供 `webhook_url`
+**特点：**
+- 和 Gateway 运行在同一台机器
+- 使用我们的 Agent 框架
+- 直接调用 Core 层的 Python 接口
 
-**理由**：
-- 任务协作场景，秒级延迟完全可接受
-- 无状态 HTTP，无需管理长连接和重连
-- Agent 已运行 FastAPI 服务，添加端点简单
-- 标准 HTTP，易调试和监控
-
-详见 [设计决策文档](./decisions.md#2-消息接收采用-webhook-而非-websocket)
+**使用方式：**
+```python
+# 直接导入 Core 层模块
+from gateway.core.conversations import ConversationManager
 
-### 决策 2：心跳维持在线状态
+manager = ConversationManager()
+messages = manager.get_messages(conversation_id)
+```
 
-**问题**：如何判断 Agent 是否在线？
+### 外部 Agent 接入
 
-**决策**：Agent 每 30 秒 HTTP POST 心跳，60 秒未收到则标记离线
+**特点：**
+- 运行在不同机器或使用其他框架
+- 通过 HTTP API 接入
+- 使用 Client SDK 简化调用
 
-**理由**：
-- 无状态 HTTP，与 Webhook 方案一致
-- 参数选择：30s 间隔平衡实时性和网络开销，60s 超时允许一次心跳丢失
+**使用方式：**
+```python
+# 使用 Client SDK
+from gateway.client.python import GatewayClient
 
-**实现位置**：`gateway/core/registry.py:AgentRegistry._cleanup_loop`
+client = GatewayClient("http://gateway-host:8000")
+messages = client.get_messages(conversation_id)
+```
 
 ---
 
-## 扩展点
+## 企业功能（可选）
 
-### Enterprise 集成
+### 认证授权（Auth）
+- API Key 认证
+- OAuth 集成
+- 权限控制
+- 单点登录
 
-Enterprise 功能通过中间件模式扩展：
+### 审计日志（Audit）
+- 操作日志记录
+- 消息审计
+- 合规报告
 
-```python
-router = GatewayRouter(
-    registry=registry,
-    middlewares=[EnterpriseAuth(), EnterpriseAudit()]
-)
-```
+### 多租户（Multi-Tenant）
+- 租户隔离
+- 资源配额
+- 计费管理
 
-详见 [Enterprise 层文档](./enterprise/overview.md)。
+**说明：**
+- 作为可选模块，独立于核心功能
+- 具体实现方式待确认
 
 ---
 
 ## 相关文档
 
-- [部署指南](./deployment.md)：部署方式和配置
-- [API 文档](./api.md)：完整的 API 参考
+- [需求规划](./requirements.md)：已确认的需求和功能范围
+- [核心模块文档](./core/)：各核心模块详细文档
+- [API 文档](./api/)：HTTP API 参考
+- [Client SDK 文档](./client/)：客户端 SDK 使用指南
 - [设计决策](./decisions.md)：架构决策记录
-- [Agent Context Injection Hooks](../../agent/docs/architecture.md#context-injection-hooks)

gateway/docs/client/python.md

@@ -0,0 +1,79 @@
+# Python SDK 使用指南
+
+**客户端 SDK：** `gateway/client/python/`
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的使用方式
+
+---
+
+## 概述
+
+Python SDK 供外部 Agent 调用 Gateway HTTP API。
+
+**适用场景：**
+- 运行在不同机器的 Agent
+- 使用其他 Agent 框架的 Agent
+
+**不适用场景：**
+- 和 Gateway 运行在同一台机器的内部 Agent（应直接调用 Core 层）
+
+---
+
+## 安装
+
+```bash
+pip install gateway-client
+```
+
+---
+
+## 基本使用
+
+### 创建客户端
+
+```python
+from gateway.client.python import GatewayClient
+
+client = GatewayClient("http://gateway-host:8000")
+```
+
+### 查询对话列表
+
+```python
+conversations = client.list_conversations()
+```
+
+### 获取消息历史
+
+```python
+messages = client.get_messages(conversation_id)
+```
+
+### 发送消息
+
+```python
+client.send_message(conversation_id, text="Hello!")
+```
+
+---
+
+## 模块结构
+
+```
+gateway/client/python/
+├── client.py    # GatewayClient 主类
+├── tools.py     # 工具函数
+└── cli.py       # CLI 工具
+```
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：外部 Agent 接入需求
+- [架构设计](../architecture.md)：Client SDK 在整体架构中的位置
+- [API 文档](../api/)：HTTP API 参考

gateway/docs/core/conversations.md

@@ -0,0 +1,110 @@
+# 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/lifecycle.md

@@ -0,0 +1,87 @@
+# Lifecycle（生命周期管理）
+
+**模块：** `gateway/core/lifecycle/`
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的设计
+
+---
+
+## 模块职责
+
+Agent 生命周期管理，包括：
+
+- **Trace 注册和元数据管理**：管理 Trace 的注册信息和元数据
+- **Workspace 管理**：管理每个 Trace 的工作空间
+- **配置热重载**：监听配置文件变化并热重载
+
+---
+
+## 核心概念
+
+### Trace
+
+基于 Agent Core 架构（详见 `../../../agent/docs/architecture.md`）：
+
+- **Trace = Agent 的执行记录**
+- 每个 Trace 有独立的 Workspace
+- Trace 数据结构由 Agent Core 定义
+
+### Workspace
+
+- 每个 Trace 有独立的工作目录
+- 包含 Agent 的配置、记忆、技能等
+- 路径格式：`~/.gateway/traces/{trace_id}/workspace/`
+
+---
+
+## 模块结构
+
+```
+gateway/core/lifecycle/
+├── trace_manager.py      # Trace 注册和元数据管理
+├── workspace_manager.py  # Workspace 管理
+└── config_watcher.py     # 配置热重载
+```
+
+---
+
+## 关键功能
+
+### Trace 注册和元数据管理
+
+**实现位置：** `gateway/core/lifecycle/trace_manager.py`
+
+**职责：**
+- 注册新的 Trace
+- 查询 Trace 元数据
+- 更新 Trace 状态
+
+### Workspace 管理
+
+**实现位置：** `gateway/core/lifecycle/workspace_manager.py`
+
+**职责：**
+- 创建 Trace 的 Workspace
+- 获取 Workspace 路径
+- 清理 Workspace
+
+### 配置热重载
+
+**实现位置：** `gateway/core/lifecycle/config_watcher.py`
+
+**职责：**
+- 监听配置文件变化
+- 热重载配置
+- 不影响正在运行的 Trace
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：生命周期管理需求
+- [架构设计](../architecture.md)：模块在整体架构中的位置
+- [Agent Core 架构](../../../agent/docs/architecture.md)：Trace 数据结构定义

gateway/docs/core/routing.md

@@ -0,0 +1,125 @@
+# 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

@@ -0,0 +1,60 @@
+# 数字员工型 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/external-agent.md

@@ -0,0 +1,66 @@
+# 外部 Agent 集成指南
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的集成方式
+
+---
+
+## 概述
+
+本指南介绍如何集成外部 Agent（运行在不同机器或使用其他 Agent 框架）。
+
+---
+
+## 特点
+
+- 运行在不同机器
+- 或使用其他 Agent 框架
+- 通过 HTTP API 接入
+- 使用 Client SDK 简化调用
+
+---
+
+## 集成步骤
+
+### 1. 安装 SDK
+
+```bash
+pip install gateway-client
+```
+
+### 2. 创建客户端
+
+```python
+from gateway.client.python import GatewayClient
+
+client = GatewayClient("http://gateway-host:8000")
+```
+
+### 3. 使用核心功能
+
+**查询对话列表：**
+```python
+conversations = client.list_conversations()
+```
+
+**获取消息历史：**
+```python
+messages = client.get_messages(conversation_id)
+```
+
+**发送消息：**
+```python
+client.send_message(conversation_id, text="Hello!")
+```
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：外部 Agent 接入需求
+- [架构设计](../architecture.md)：API 层架构
+- [API 文档](../api/)：HTTP API 参考
+- [Python SDK 文档](../client/python.md)：SDK 详细文档

gateway/docs/guides/internal-agent.md

@@ -0,0 +1,60 @@
+# 内部 Agent 集成指南
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的集成方式
+
+---
+
+## 概述
+
+本指南介绍如何集成内部 Agent（和 Gateway 运行在同一台机器，使用我们的 Agent 框架）。
+
+---
+
+## 特点
+
+- 和 Gateway 运行在同一台机器
+- 使用我们的 Agent 框架
+- 直接调用 Core 层的 Python 接口
+- 无需 HTTP 通信
+
+---
+
+## 集成步骤
+
+### 1. 导入模块
+
+```python
+from gateway.core.lifecycle import TraceManager
+from gateway.core.conversations import ConversationManager
+from gateway.core.routing import Router
+```
+
+### 2. 使用核心功能
+
+**查询对话列表：**
+```python
+manager = ConversationManager()
+conversations = manager.list_conversations()
+```
+
+**获取消息历史：**
+```python
+messages = manager.get_messages(conversation_id)
+```
+
+**发送消息：**
+```python
+manager.send_message(conversation_id, text="Hello!")
+```
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：内部 Agent 接入需求
+- [架构设计](../architecture.md)：Core 层架构
+- [核心模块文档](../core/)：各模块详细文档

gateway/docs/guides/personal-assistant.md

@@ -0,0 +1,46 @@
+# 个人助理型 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/guides/quickstart.md

@@ -0,0 +1,94 @@
+# 快速开始
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的使用方式
+
+---
+
+## 概述
+
+本指南帮助你快速开始使用 Gateway。
+
+---
+
+## 内部 Agent（同设备，我们的框架）
+
+### 特点
+
+- 和 Gateway 运行在同一台机器
+- 使用我们的 Agent 框架
+- 直接调用 Core 层的 Python 接口
+
+### 使用方式
+
+```python
+# 直接导入 Core 层模块
+from gateway.core.conversations import ConversationManager
+
+# 创建管理器
+manager = ConversationManager()
+
+# 查询对话列表
+conversations = manager.list_conversations()
+
+# 获取消息历史
+messages = manager.get_messages(conversation_id)
+
+# 发送消息
+manager.send_message(conversation_id, text="Hello!")
+```
+
+---
+
+## 外部 Agent（其他设备/其他框架）
+
+### 特点
+
+- 运行在不同机器
+- 或使用其他 Agent 框架
+- 通过 HTTP API + Client SDK 接入
+
+### 安装
+
+```bash
+pip install gateway-client
+```
+
+### 使用方式
+
+```python
+# 使用 Client SDK
+from gateway.client.python import GatewayClient
+
+# 创建客户端
+client = GatewayClient("http://gateway-host:8000")
+
+# 查询对话列表
+conversations = client.list_conversations()
+
+# 获取消息历史
+messages = client.get_messages(conversation_id)
+
+# 发送消息
+client.send_message(conversation_id, text="Hello!")
+```
+
+---
+
+## 下一步
+
+- [内部 Agent 集成指南](./internal-agent.md)：详细的内部 Agent 集成步骤
+- [外部 Agent 集成指南](./external-agent.md)：详细的外部 Agent 集成步骤
+- [个人助理配置](./personal-assistant.md)：配置个人助理型 Agent
+- [数字员工配置](./digital-employee.md)：配置数字员工型 Agent
+
+---
+
+## 相关文档
+
+- [需求规划](../requirements.md)：两种接入方式的详细说明
+- [架构设计](../architecture.md)：整体架构
+- [API 文档](../api/)：HTTP API 参考

gateway/docs/requirements.md

@@ -0,0 +1,202 @@
+# Gateway 需求规划
+
+**更新日期：** 2026-03-12
+
+## 文档维护规范
+
+0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
+1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
+2. **简洁快照，日志分离** - 只记录已确认的需求，避免推测和未确认的设计细节
+
+---
+
+## 核心理解
+
+### 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 机制（跨设备能力调用）
+- 当前阶段暂不实现
+- 未来如有需求再考虑
+
+---
+
+## 相关文档
+
+- [Agent Core 架构](../../agent/docs/architecture.md)：Agent 框架核心设计
+- [Gateway 架构](./architecture.md)：Gateway 架构设计
+- [核心模块文档](./core/)：各核心模块详细文档
+- [API 文档](./api/)：HTTP API 参考
+- [设计决策](./decisions.md)：架构决策记录