# PIT 网关路由应用

> 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 | 作者: 小白 🐶*