Agent/gateway

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（同设备，我们的框架）

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

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

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

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

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

文档

核心文档

• 需求规划：已确认的需求和功能范围
• 架构设计：Gateway 架构和核心模块
• 文档索引：完整文档导航

模块文档（待创建）

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

其他文档

• 设计决策：架构决策记录
• 部署指南：部署方式和配置
• 企业功能：企业功能文档（可选）

文档维护规范

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

开发状态

已实现

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

开发中

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

计划中

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

相关项目

• Agent Core：Agent 核心框架