345 lines
12 KiB
Markdown
345 lines
12 KiB
Markdown
# 智队中枢 - 技术方案
|
||
|
||
> Personal Intelligent Team Router Service
|
||
|
||
## 📋 项目概述
|
||
|
||
**智队中枢**是 PIT（Personal Intelligent Team）系统的核心组件，负责连接用户交互层和 Agent 层，实现消息路由、会话管理、Agent 调度等功能。
|
||
|
||
---
|
||
|
||
## 🏗️ 系统架构
|
||
|
||
```
|
||
用户交互层 (Clients)
|
||
↓ WebSocket / HTTP
|
||
智队中枢 (PIT Router)
|
||
├── 接入层 (Access Layer)
|
||
│ ├── HTTP Server (Flask)
|
||
│ ├── WebSocket (SocketIO)
|
||
│ ├── Auth Middleware (JWT)
|
||
│ └── Rate Limiter
|
||
├── 业务层 (Business Layer)
|
||
│ ├── Session Manager
|
||
│ ├── Message Router
|
||
│ ├── Agent Scheduler (加权轮询)
|
||
│ └── Message Queue (ACK机制)
|
||
└── 数据层 (Data Layer)
|
||
├── PostgreSQL (持久化)
|
||
├── Redis (缓存/消息队列)
|
||
└── Config Store
|
||
↓ WebSocket + 智队频道协议
|
||
Agent 层 (OpenClaw Gateways)
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 已完成功能
|
||
|
||
### Phase 1: 核心功能
|
||
|
||
| 功能模块 | 文件 | 状态 | 说明 |
|
||
|----------|------|------|------|
|
||
| **项目结构** | `app/` | ✅ 完成 | Flask 应用工厂，三层架构 |
|
||
| **配置管理** | `app/config.py` | ✅ 完成 | 开发/生产/测试环境配置 |
|
||
| **扩展初始化** | `app/extensions.py` | ✅ 完成 | Flask 扩展统一管理 |
|
||
| **数据模型** | | | |
|
||
| └─ User | `app/models/user.py` | ✅ 完成 | 用户模型，bcrypt 密码哈希 |
|
||
| └─ Session | `app/models/session.py` | ✅ 完成 | 会话模型，多 Agent 协作 |
|
||
| └─ Agent | `app/models/agent.py` | ✅ 完成 | Agent 模型，优先级/权重 |
|
||
| └─ Gateway | `app/models/gateway.py` | ✅ 完成 | Gateway 模型，Token 哈希 |
|
||
| └─ Message | `app/models/message.py` | ✅ 完成 | 消息模型，ACK 状态追踪 |
|
||
| └─ Connection | `app/models/connection.py` | ✅ 完成 | 连接模型，Socket 追踪 |
|
||
| **HTTP API** | | | |
|
||
| └─ 认证 API | `app/routes/auth.py` | ✅ 完成 | 注册/登录/Token 刷新/用户信息 |
|
||
| └─ 会话 API | `app/routes/sessions.py` | ✅ 完成 | 创建/查询/关闭会话 |
|
||
| └─ Agent API | `app/routes/agents.py` | ✅ 完成 | 列表/详情/状态/配置/心跳 |
|
||
| └─ Gateway API | `app/routes/gateways.py` | ✅ 完成 | 注册/注销/状态/心跳 |
|
||
| └─ 消息 API | `app/routes/messages.py` | ✅ 完成 | 发送/获取/确认/已读 |
|
||
| └─ 统计 API | `app/routes/stats.py` | ✅ 完成 | 系统/会话/消息/Agent 统计 |
|
||
| **WebSocket** | `app/socketio/handlers.py` | ✅ 完成 | 认证/心跳/会话/消息 |
|
||
| **数据库迁移** | `migrations/` | ✅ 完成 | Alembic 初始迁移 |
|
||
|
||
### Phase 2: 服务层
|
||
|
||
| 功能模块 | 文件 | 状态 | 说明 |
|
||
|----------|------|------|------|
|
||
| **AgentScheduler** | `app/services/scheduler.py` | ✅ 完成 | 5 种调度策略 |
|
||
| └─ RoundRobinScheduler | | ✅ 完成 | 轮询调度 |
|
||
| └─ WeightedRoundRobinScheduler | | ✅ 完成 | 加权轮询（默认） |
|
||
| └─ LeastConnectionsScheduler | | ✅ 完成 | 最少连接 |
|
||
| └─ LeastResponseTimeScheduler | | ✅ 完成 | 最快响应 |
|
||
| └─ CapabilityMatchScheduler | | ✅ 完成 | 能力匹配 |
|
||
| **MessageQueue** | `app/services/message_queue.py` | ✅ 完成 | 消息队列，ACK，重试 |
|
||
| **SessionService** | `app/services/session_service.py` | ✅ 完成 | 会话创建/关闭/分配 |
|
||
| **MessageService** | `app/services/message_service.py` | ✅ 完成 | 消息管理/确认/重试 |
|
||
| **AgentService** | `app/services/agent_service.py` | ✅ 完成 | Agent 注册/状态/心跳 |
|
||
|
||
### Phase 3: 工具层
|
||
|
||
| 功能模块 | 文件 | 状态 | 说明 |
|
||
|----------|------|------|------|
|
||
| **validators.py** | `app/utils/validators.py` | ✅ 完成 | Marshmallow 验证 |
|
||
| **security.py** | `app/utils/security.py` | ✅ 完成 | Token/密码哈希/限流/IP白名单 |
|
||
| **helpers.py** | `app/utils/helpers.py` | ✅ 完成 | 日期/分页/JSON |
|
||
|
||
### Phase 4: 测试
|
||
|
||
| 测试模块 | 状态 | 说明 |
|
||
|----------|------|------|
|
||
| 调度器测试 | ✅ 11/11 通过 | 所有调度策略 |
|
||
| 消息队列测试 | ✅ 7/7 通过 | 队列基本功能 |
|
||
| 验证工具测试 | ⚠️ 3/4 通过 | 1 个规则问题 |
|
||
| 认证 API 测试 | ⚠️ 3/9 通过 | 测试配置问题 |
|
||
|
||
**单元测试总计**: 24/31 通过
|
||
|
||
### 部署配置
|
||
|
||
| 文件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| `Dockerfile` | ✅ 完成 | 生产环境 Docker 镜像 |
|
||
| `docker-compose.yaml` | ✅ 完成 | Docker 编排（PostgreSQL + Redis + Nginx） |
|
||
| `requirements.txt` | ✅ 完成 | Python 依赖 |
|
||
| `requirements-dev.txt` | ✅ 完成 | 开发依赖 |
|
||
| `.env.example` | ✅ 完成 | 环境变量模板 |
|
||
| `run.py` | ✅ 完成 | 启动入口 |
|
||
|
||
---
|
||
|
||
## ⏳ 待完成功能
|
||
|
||
### 高优先级
|
||
|
||
| 功能模块 | 文件 | 说明 |
|
||
|----------|------|------|
|
||
| **集成测试** | `tests/test_websocket.py` | WebSocket 流程测试 |
|
||
| **性能测试** | - | 压力测试/负载测试 |
|
||
| **Nginx 配置** | `nginx.conf` | HTTPS + WSS 反向代理 |
|
||
| **SSL 证书** | - | 生产环境 HTTPS |
|
||
| **配置热更新** | - | 修改配置无需重启 |
|
||
| **日志系统** | - | 结构化日志 + 日志轮转 |
|
||
| **监控告警** | - | Prometheus + Grafana |
|
||
|
||
### 中优先级
|
||
|
||
| 功能模块 | 说明 |
|
||
|----------|------|
|
||
| **消息历史查询** | 分页查询会话消息历史 |
|
||
| **配置迁移** | 新版本配置自动迁移 |
|
||
| **回滚机制** | 配置版本回滚 |
|
||
| **Web UI** | 管理界面（可选） |
|
||
|
||
### 低优先级
|
||
|
||
| 功能模块 | 说明 |
|
||
|----------|------|
|
||
| **多租户支持** | 多个组织隔离 |
|
||
| **消息加密** | 端到端加密 |
|
||
| **审计日志** | 操作审计 |
|
||
|
||
---
|
||
|
||
## 📊 数据流设计
|
||
|
||
### 用户消息流程
|
||
|
||
```
|
||
1. 用户 → WebSocket 连接 → 智队中枢
|
||
2. 智队中枢 → 验证 JWT Token
|
||
3. 智队中枢 → SessionService 创建/获取会话
|
||
4. 智队中枢 → AgentScheduler 选择最优 Agent
|
||
5. 智队中枢 → WebSocket 转发消息给 Agent
|
||
6. Agent 处理 → 返回响应
|
||
7. 智队中枢 → 消息持久化 (PostgreSQL)
|
||
8. 智队中枢 → WebSocket 返回给用户
|
||
9. 用户 → 消息确认 (ACK)
|
||
10. 智队中枢 → 更新消息状态
|
||
```
|
||
|
||
### Agent 注册流程
|
||
|
||
```
|
||
1. Gateway → POST /api/gateways 注册 Gateway
|
||
2. Gateway → POST /api/agents/:id/heartbeat 心跳
|
||
3. 智队中枢 → AgentService 更新状态
|
||
4. 智队中枢 → Scheduler 添加到候选列表
|
||
5. 用户请求 → Scheduler 选择 Agent
|
||
6. 智队中枢 → WebSocket 分配会话
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API 设计
|
||
|
||
### 认证 API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| POST | /api/auth/register | ✅ |
|
||
| POST | /api/auth/login | ✅ |
|
||
| POST | /api/auth/logout | ✅ |
|
||
| POST | /api/auth/refresh | ✅ |
|
||
| GET | /api/auth/me | ✅ |
|
||
| POST | /api/auth/verify | ✅ |
|
||
|
||
### 会话 API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| GET | /api/sessions | ✅ |
|
||
| POST | /api/sessions | ✅ |
|
||
| GET | /api/sessions/:id | ✅ |
|
||
| PUT | /api/sessions/:id/close | ✅ |
|
||
| GET | /api/sessions/:id/messages | ✅ |
|
||
| GET | /api/sessions/:id/participants | ✅ |
|
||
| POST | /api/sessions/:id/transfer | ✅ |
|
||
|
||
### Agent API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| GET | /api/agents | ✅ |
|
||
| GET | /api/agents/:id | ✅ |
|
||
| GET | /api/agents/:id/status | ✅ |
|
||
| PUT | /api/agents/:id/config | ✅ |
|
||
| POST | /api/agents/:id/heartbeat | ✅ |
|
||
| GET | /api/agents/available | ✅ |
|
||
|
||
### Gateway API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| GET | /api/gateways | ✅ |
|
||
| POST | /api/gateways | ✅ |
|
||
| DELETE | /api/gateways/:id | ✅ |
|
||
| GET | /api/gateways/:id/status | ✅ |
|
||
| POST | /api/gateways/:id/heartbeat | ✅ |
|
||
|
||
### 消息 API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| POST | /api/messages | ✅ |
|
||
| GET | /api/messages/:id | ✅ |
|
||
| PUT | /api/messages/:id/ack | ✅ |
|
||
| PUT | /api/messages/:id/read | ✅ |
|
||
|
||
### 统计 API
|
||
|
||
| 方法 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| GET | /api/stats | ✅ |
|
||
| GET | /api/stats/sessions | ✅ |
|
||
| GET | /api/stats/messages | ✅ |
|
||
| GET | /api/stats/agents | ✅ |
|
||
|
||
---
|
||
|
||
## 🔧 技术栈
|
||
|
||
| 层级 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 语言 | Python | 3.12 |
|
||
| Web 框架 | Flask | 3.0+ |
|
||
| WebSocket | Flask-SocketIO | 5.3+ |
|
||
| ORM | SQLAlchemy | 3.1+ |
|
||
| 认证 | Flask-Login + JWT | - |
|
||
| 缓存/队列 | Redis | 7+ |
|
||
| 数据库 | PostgreSQL | 15+ |
|
||
| 部署 | Gunicorn + Nginx | - |
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
pit-router/
|
||
├── app/
|
||
│ ├── __init__.py # Flask 应用工厂 ✅
|
||
│ ├── config.py # 配置管理 ✅
|
||
│ ├── extensions.py # Flask 扩展初始化 ✅
|
||
│ ├── models/ # 数据模型 ✅
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── session.py # 会话模型
|
||
│ │ ├── agent.py # Agent 模型
|
||
│ │ ├── gateway.py # Gateway 模型
|
||
│ │ ├── message.py # 消息模型
|
||
│ │ └── connection.py # 连接模型
|
||
│ ├── routes/ # HTTP API ✅
|
||
│ │ ├── auth.py
|
||
│ │ ├── sessions.py
|
||
│ │ ├── agents.py
|
||
│ │ ├── gateways.py
|
||
│ │ ├── messages.py
|
||
│ │ └── stats.py
|
||
│ ├── socketio/ # WebSocket ✅
|
||
│ │ ├── handlers.py
|
||
│ │ └── events.py
|
||
│ ├── services/ # 业务逻辑 ✅
|
||
│ │ ├── scheduler.py # 5 种调度策略
|
||
│ │ ├── message_queue.py
|
||
│ │ ├── session_service.py
|
||
│ │ ├── message_service.py
|
||
│ │ └── agent_service.py
|
||
│ └── utils/ # 工具函数 ✅
|
||
│ ├── validators.py
|
||
│ ├── security.py
|
||
│ └── helpers.py
|
||
├── migrations/ # 数据库迁移 ✅
|
||
├── tests/ # 测试 ⚠️ 部分完成
|
||
│ ├── test_scheduler.py # ✅ 11/11
|
||
│ ├── test_message_queue.py # ✅ 7/7
|
||
│ └── test_auth.py # ⚠️ 3/9
|
||
├── requirements.txt # 依赖 ✅
|
||
├── requirements-dev.txt # 开发依赖 ✅
|
||
├── docker-compose.yaml # Docker 编排 ✅
|
||
├── Dockerfile # Docker 镜像 ✅
|
||
├── run.py # 启动入口 ✅
|
||
└── CHANGELOG.md # 版本记录 ✅
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 开发进度
|
||
|
||
```
|
||
Phase 1: 核心功能 ████████████████████ 100% ✅
|
||
Phase 2: 服务层 ████████████████████ 100% ✅
|
||
Phase 3: 工具层 ████████████████████ 100% ✅
|
||
Phase 4: 测试部署 ████████░░░░░░░░░░░░ 40% ⚠️
|
||
├─ 单元测试 ██████████████░░░░░ 80%
|
||
├─ 集成测试 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
├─ 性能测试 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
└─ 部署 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
Phase 5: 运维工具 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
├─ Nginx + SSL ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
├─ 日志系统 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
└─ 监控告警 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 已知问题
|
||
|
||
| 问题 | 严重性 | 说明 |
|
||
|------|--------|------|
|
||
| 认证测试失败 | 低 | 测试配置问题，不影响实际运行 |
|
||
| 验证规则过严 | 低 | 用户名不允许 `-` 字符 |
|
||
| 缺少 nginx.conf | 中 | 需要手动配置 HTTPS/WSS |
|
||
| SSL 证书 | 中 | 生产环境需要配置 |
|
||
|
||
---
|
||
|
||
## 🚀 下一步计划
|
||
|
||
1. **集成测试** - 完善 WebSocket 流程测试
|
||
2. **部署测试** - Docker Compose 本地部署验证
|
||
3. **Nginx 配置** - 添加 HTTPS + WSS 反向代理
|
||
4. **日志系统** - 结构化日志 + 日志轮转
|
||
5. **监控告警** - Prometheus + Grafana
|
||
|
||
---
|
||
|
||
*最后更新: 2026-03-14 | 作者: 小黑 🐕*
|