# Gateway - Agent 消息路由和生命周期管理服务

**框架无关的 Agent 即时通讯网关**，提供 Agent 生命周期管理、消息路由、对话管理。

## 概述

Gateway 是一个 Agent 即时通讯和管理系统，支持任何 Agent 框架使用。核心功能：

- **Agent 生命周期管理**：Trace 注册、Workspace 管理、配置热重载
- **对话管理**：对话管理、消息历史、消息队列
- **消息路由**：飞书集成、消息路由、联系人管理

**独立性**：Gateway 与 Agent Core 并列，可以独立部署。

## 设计原则

1. **框架无关**：Gateway 核心不依赖任何特定的 Agent 框架
2. **分层架构**：Core 层（内部接口）+ API 层（外部接口）
3. **易于集成**：内部 Agent 直接调用，外部 Agent 使用 SDK
4. **可扩展**：支持企业功能扩展（认证、审计、多租户）

## 架构

```
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 工具
│
└── docs/                          # 文档
    ├── requirements.md            # 需求规划
    ├── architecture.md            # 架构设计
    ├── core/                      # 核心模块文档
    ├── api/                       # API 文档
    ├── client/                    # 客户端文档
    ├── guides/                    # 使用指南
    └── decisions.md               # 设计决策
```

## 快速开始

### 内部 Agent（同设备，我们的框架）

```python
# 直接导入 Core 层模块
from gateway.core.conversations import ConversationManager

manager = ConversationManager()
messages = manager.get_messages(conversation_id)
```

### 外部 Agent（其他设备/其他框架）

```python
# 使用 Client SDK
from gateway.client.python import GatewayClient

client = GatewayClient("http://gateway-host:8000")
messages = client.get_messages(conversation_id)
```

## 文档

### 核心文档

- [需求规划](./docs/requirements.md)：已确认的需求和功能范围
- [架构设计](./docs/architecture.md)：Gateway 架构和核心模块
- [文档索引](./docs/README.md)：完整文档导航

### 模块文档（待创建）

- 核心模块文档：`docs/core/`
- API 文档：`docs/api/`
- 客户端文档：`docs/client/`
- 使用指南：`docs/guides/`

### 其他文档

- [设计决策](./docs/decisions.md)：架构决策记录
- [部署指南](./docs/deployment.md)：部署方式和配置
- [企业功能](./docs/enterprise/)：企业功能文档（可选）

## 文档维护规范

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

## 开发状态

### 已实现

- ✅ Agent 注册和在线状态管理（旧版）
- ✅ 消息路由（Webhook 推送，旧版）

### 开发中

- 🚧 重构为新架构（Core 层 + API 层）
- 🚧 Agent 生命周期管理
- 🚧 对话管理
- 🚧 飞书集成

### 计划中

- 📋 联系人管理
- 📋 企业功能（认证、审计、多租户）

## 相关项目

- [Agent Core](../agent/README.md)：Agent 核心框架