From d013d969d951c3e48d60f5566430571be4556210 Mon Sep 17 00:00:00 2001 From: yunxiafei <307327147@qq.com> Date: Sat, 14 Mar 2026 18:58:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20PIT=20=E7=BD=91?= =?UTF-8?q?=E5=85=B3=E8=B7=AF=E7=94=B1=E5=BA=94=E7=94=A8=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E6=96=B9=E6=A1=88=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 项目概述与技术栈 - 系统架构设计 - 数据模型定义 - HTTP API 设计 - WebSocket 协议 - 部署架构 - 安全设计 - 开发计划 版本: v1.0 作者: 小白 🐶 --- README.md | 315 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 313 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7f16d1f..3e8c31c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,314 @@ -# pit-router +# PIT 网关路由应用 -PIT 网关路由应用 - Personal Intelligent Team Router Service \ No newline at end of file +> Personal Intelligent Team Router Service + +## 项目概述 + +PIT（Personal Intelligent Team）网关路由应用是 PIT 系统的核心组件，负责连接用户交互层和 Agent 层，实现消息路由、会话管理、Agent 调度等功能。 + +### 核心目标 + +- 提供统一的 WebSocket 接入点 +- 实现多 Agent 智能路由 +- 管理会话生命周期 +- 支持 Agent 负载均衡 + +--- + +## 技术栈 + +| 层级 | 技术 | 版本 | 说明 | +|------|------|------|------| +| 语言 | Python | 3.12 | 高性能异步支持 | +| Web框架 | Flask | 3.0+ | 轻量级、灵活 | +| WebSocket | Flask-SocketIO | 5.3+ | 实时双向通信 | +| ORM | SQLAlchemy | 3.1+ | 数据库抽象层 | +| 认证 | Flask-Login + JWT | - | 用户身份验证 | +| 缓存 | Redis | 7+ | 会话缓存、消息队列 | +| 部署 | Gunicorn + Nginx | - | 生产环境部署 | + +--- + +## 系统架构 + +``` +用户交互层 (Clients) + ↓ WebSocket / HTTP +PIT 网关路由应用 (Gateway Router) + ├── 接入层 (Access Layer) + │ ├── HTTP Server (Flask) + │ ├── WebSocket (SocketIO) + │ └── Auth Middleware + ├── 业务层 (Business Layer) + │ ├── Session Manager + │ ├── Message Router + │ └── Agent Scheduler + └── 数据层 (Data Layer) + ├── SQLite (持久化) + ├── Redis (缓存) + └── Config Store + ↓ PIT Channel 插件 +Agent 层 (OpenClaw Gateways) +``` + +--- + +## 项目结构 + +``` +pit-router/ +├── app/ +│ ├── __init__.py # Flask 应用工厂 +│ ├── config.py # 配置管理 +│ ├── models/ # 数据模型层 +│ │ ├── user.py # 用户模型 +│ │ ├── session.py # 会话模型 +│ │ ├── agent.py # Agent 模型 +│ │ ├── gateway.py # Gateway 模型 +│ │ └── message.py # 消息模型 +│ ├── routes/ # HTTP 路由层 +│ │ ├── auth.py # 认证路由 +│ │ ├── sessions.py # 会话路由 +│ │ ├── agents.py # Agent 路由 +│ │ └── gateways.py # Gateway 路由 +│ ├── socketio/ # WebSocket 处理层 +│ │ ├── handlers.py # Socket.IO 事件处理 +│ │ └── events.py # 事件定义 +│ ├── services/ # 业务逻辑层 +│ │ ├── session_service.py # 会话服务 +│ │ ├── agent_service.py # Agent 服务 +│ │ ├── message_service.py # 消息服务 +│ │ └── scheduler.py # Agent 调度器 +│ └── utils/ # 工具函数 +├── migrations/ # 数据库迁移 +├── tests/ # 测试 +├── requirements.txt # Python 依赖 +├── config.yaml # 配置文件 +├── docker-compose.yaml # Docker 编排 +└── run.py # 启动入口 +``` + +--- + +## 数据模型 + +### 用户模型 (User) + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String(36) | 主键 UUID | +| username | String(80) | 用户名，唯一索引 | +| password_hash | String(256) | 密码哈希 | +| email | String(120) | 邮箱，唯一 | +| nickname | String(80) | 昵称 | +| role | String(20) | 角色：admin/user | +| status | String(20) | 状态：active/disabled | +| created_at | DateTime | 创建时间 | +| last_login_at | DateTime | 最后登录时间 | + +### 会话模型 (Session) + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String(36) | 主键 UUID | +| user_id | String(36) | 用户 ID，外键 | +| agent_id | String(36) | Agent ID，外键 | +| gateway_id | String(36) | Gateway ID，外键 | +| title | String(200) | 会话标题 | +| channel_type | String(20) | 渠道类型：web/desktop/mobile | +| status | String(20) | 状态：active/paused/closed | +| message_count | Integer | 消息计数 | +| created_at | DateTime | 创建时间 | +| last_active_at | DateTime | 最后活跃时间 | + +### Agent 模型 + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String(36) | 主键 UUID | +| name | String(80) | Agent 名称 | +| display_name | String(80) | 显示名称 | +| gateway_id | String(36) | Gateway ID，外键 | +| model | String(80) | 使用的模型 | +| capabilities | JSON | 能力列表 | +| status | String(20) | 状态：online/offline/busy | +| priority | Integer | 优先级 | +| weight | Integer | 权重（用于调度） | +| last_heartbeat | DateTime | 最后心跳时间 | + +### Gateway 模型 + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String(36) | 主键 UUID | +| name | String(80) | Gateway 名称，唯一 | +| url | String(256) | Gateway 地址 | +| token | String(256) | 认证 Token（加密存储） | +| status | String(20) | 状态：online/offline | +| agent_count | Integer | Agent 数量 | +| last_heartbeat | DateTime | 最后心跳时间 | + +--- + +## HTTP API 设计 + +### 认证 API + +``` +POST /api/auth/register - 注册新用户 +POST /api/auth/login - 用户登录，返回 JWT Token +POST /api/auth/logout - 用户登出 +POST /api/auth/refresh - 刷新 Token +GET /api/auth/me - 获取当前用户信息 +``` + +### 会话 API + +``` +GET /api/sessions - 获取会话列表 +POST /api/sessions - 创建会话 +GET /api/sessions/:id - 获取会话详情 +DELETE /api/sessions/:id - 关闭会话 +GET /api/sessions/:id/messages - 获取会话消息 +``` + +### Agent API + +``` +GET /api/agents - 获取 Agent 列表 +GET /api/agents/:id - 获取 Agent 详情 +GET /api/agents/:id/status - 获取 Agent 实时状态 +PUT /api/agents/:id/config - 更新 Agent 配置 +``` + +### Gateway API + +``` +GET /api/gateways - 获取 Gateway 列表 +POST /api/gateways - 注册 Gateway +DELETE /api/gateways/:id - 注销 Gateway +GET /api/gateways/:id/status - 获取 Gateway 状态 +``` + +--- + +## WebSocket 协议 + +### 事件定义 + +| 事件 | 方向 | 说明 | +|------|------|------| +| connect | C→S | 连接请求 | +| connected | S→C | 连接成功 | +| session.create | C→S | 创建会话 | +| session.created | S→C | 会话已创建 | +| session.join | C→S | 加入会话 | +| session.joined | S→C | 已加入会话 | +| message.send | C→S | 发送消息 | +| message | S→C | 收到消息 | +| message.stream | S→C | 流式消息 | +| error | S→C | 错误通知 | + +--- + +## 部署架构 + +### Docker Compose + +```yaml +version: '3.8' + +services: + pit-router: + build: . + ports: + - "9000:9000" + environment: + - FLASK_ENV=production + - SECRET_KEY=${SECRET_KEY} + - JWT_SECRET=${JWT_SECRET} + - DATABASE_URL=sqlite:///data/pit.db + - REDIS_URL=redis://redis:6379 + volumes: + - pit-data:/app/data + - pit-logs:/app/logs + depends_on: + - redis + restart: unless-stopped + + redis: + image: redis:7-alpine + volumes: + - redis-data:/data + restart: unless-stopped + +volumes: + pit-data: + pit-logs: + redis-data: +``` + +--- + +## 安全设计 + +### 认证机制 + +| 机制 | 说明 | +|------|------| +| JWT Token | 无状态认证 | +| Token 过期 | 24 小时 | +| Refresh Token | 7 天 | + +### 安全措施 + +| 措施 | 说明 | +|------|------| +| HTTPS | 强制 HTTPS | +| CORS | 配置允许的源 | +| Rate Limit | 请求频率限制 | +| Input Validation | 输入验证 | +| SQL Injection | SQLAlchemy ORM 防护 | +| XSS | 内容转义 | + +--- + +## 开发计划 + +### Phase 1: 核心功能 (2-3 天) + +- [ ] 数据模型实现 +- [ ] 认证 API +- [ ] 会话 API +- [ ] WebSocket 处理 +- [ ] Agent 调度 + +### Phase 2: 扩展功能 (1-2 天) + +- [ ] Gateway 管理 +- [ ] 配置管理 +- [ ] 日志系统 +- [ ] 监控接口 + +### Phase 3: 测试部署 (1-2 天) + +- [ ] 单元测试 +- [ ] 集成测试 +- [ ] Docker 部署 +- [ ] Nginx 配置 + +--- + +## 相关项目 + +- [PIT Channel 插件](http://localhost:3000/yunxiafei/pit-channel) - OpenClaw Channel 插件 + +--- + +## 许可证 + +MIT License + +--- + +*创建时间: 2026-03-14 | 作者: 小白 🐶*