yunxiafei/pit-router

Fork 0

Files

feifei.xu 4d4e4db16b docs: 添加技术方案文档，更新开发进度

2026-03-14 21:55:16 +08:00

12 KiB

Raw Permalink Blame History

智队中枢 - 技术方案

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 证书	中	生产环境需要配置

🚀 下一步计划

集成测试 - 完善 WebSocket 流程测试
部署测试 - Docker Compose 本地部署验证
Nginx 配置 - 添加 HTTPS + WSS 反向代理
日志系统 - 结构化日志 + 日志轮转
监控告警 - Prometheus + Grafana

最后更新: 2026-03-14 | 作者: 小黑 🐕

12 KiB Raw Permalink Blame History Unescape Escape

智队中枢 - 技术方案

📋 项目概述

🏗️ 系统架构

✅ 已完成功能

Phase 1: 核心功能

Phase 2: 服务层

Phase 3: 工具层

Phase 4: 测试

部署配置

⏳ 待完成功能

高优先级

中优先级

低优先级

📊 数据流设计

用户消息流程

Agent 注册流程

🔌 API 设计

认证 API

会话 API

Agent API

Gateway API

消息 API

统计 API

🔧 技术栈

📁 项目结构

📈 开发进度

⚠️ 已知问题

🚀 下一步计划

12 KiB

Raw Permalink Blame History