# Gateway - Agent 使命/职能对话系统

**自研 Agent 框架的管理系统**，负责 Agent 的生命周期管理和任务执行调度。

## 概述

Gateway 是自研 Agent 框架的管理系统，专注于"使命/职能对话"：

- **使命/职能对话**：用户给 Agent 分配任务，Agent 汇报工作
- **管理-执行关系**：用户是管理者，Agent 是执行者
- **任务导向**：有明确的目标和预期结果

**与 IM 系统的区别：**
- **IM 系统**：LLM 作为主体的平等交流（协作-沟通关系）
- **Gateway**：用户对 LLM 的使命/职能对话（管理-执行关系）

## 核心功能

- **外部渠道接入（Channels）**：飞书集成（个人助理型）、消息路由、自动创建 Trace
- **生命周期管理（Lifecycle）**：Trace 注册/查询、Workspace 管理、配置热重载
- **任务执行调度（Executor）**：接收任务、调度执行、状态管理

## 设计原则

1. **职责清晰**：专注于使命/职能对话，不处理平等交流
2. **分层架构**：Core 层（内部接口）+ API 层（外部接口）
3. **易于集成**：内部 Agent 直接调用，外部 Agent 使用 SDK
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 注册和查询
│   │   ├── workspace_manager.py  # Workspace 管理
│   │   └── config_watcher.py     # 配置热重载
│   │
│   └── executor/                  # 任务执行调度
│       ├── task_manager.py        # 任务管理
│       ├── scheduler.py           # 调度器
│       └── execution_context.py   # 执行上下文
│
├── api/                           # HTTP API 层（外部接口）
│   ├── lifecycle_api.py           # 生命周期管理 API
│   ├── executor_api.py            # 任务执行 API
│   └── webhook_api.py             # Webhook API（飞书等）
│
├── client/                        # 客户端 SDK
│   └── python/                    # Python SDK
│       ├── client.py              # GatewayClient
│       └── cli.py                 # CLI 工具
│
└── docs/                          # 文档
    ├── requirements.md            # 需求规划
    ├── architecture.md            # 架构设计
    ├── core/                      # 核心模块文档
    │   ├── channels.md            # 外部渠道接入
    │   ├── lifecycle.md           # 生命周期管理
    │   └── executor.md            # 任务执行调度
    ├── api/                       # API 文档
    ├── client/                    # 客户端文档
    ├── guides/                    # 使用指南
    └── decisions.md               # 设计决策
```

## 快速开始

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

```python
# 直接导入 Core 层模块
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（其他设备/其他框架）

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

client = GatewayClient("http://gateway-host:8000")

# 创建 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"])
```

## 文档

### 核心文档

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

### 模块文档

- [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)：部署方式和配置

## 文档维护规范

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

## 开发状态

### 已完成 ✅

- 需求规划和架构设计
- 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 客户端工具