yunxiafei/pit-router
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 新增智队机器人功能详细技术方案 (v0.8.0)

Browse Source 
- 新增智队机器人功能模块设计
- 新增 Bot 数据模型设计
- 新增机器人管理 API 设计
- 新增聊天界面设计
- 新增聊天 WebSocket 事件设计
- 更新已完成工作列表
- 更新待完成工作列表
- 更新项目版本至 v0.8.0
This commit is contained in:
小白
2026-03-15 09:47:31 +08:00
parent 92dede8793
commit 066ccf0d28
1 changed files with 315 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

471
README.md
View File

@@ -5,12 +5,20 @@
**中文名**：智队中枢
**英文名**：PIT Router
**当前版本**：v0.7.2
**当前版本**：v0.8.0
---
## 更新日志
### v0.8.0 (2026-03-15) 🚀 新功能
- ✅ 新增智队机器人功能模块设计
- ✅ 新增 Bot 数据模型设计
- ✅ 新增机器人管理 API 设计
- ✅ 新增聊天界面设计
- ✅ 新增聊天 WebSocket 事件设计
- ⏳ 智队机器人功能开发中
### v0.7.2 (2026-03-15)
- ✅ 修复暗黑主题切换不生效的问题
- ✅ 修复暗黑主题切换时的页面闪烁问题
@@ -36,6 +44,117 @@
- 管理会话生命周期
- 支持 Agent 负载均衡
- 保证消息可靠传输
- **🆕 提供内置聊天界面和机器人功能**
---
## 🆕 智队机器人功能
### 功能概述
智队机器人是智队中枢内置的聊天机器人功能，用户可以通过智队中枢的聊天界面与绑定的 OpenClaw Agent 进行对话。
**类比 QQ Bot**：
```
QQ 用户 → QQ 客户端 → QQ Bot（Channel 插件）→ OpenClaw Agent
智队用户 → 智队中枢聊天界面 → 智队机器人 → 智队频道插件 → OpenClaw Agent
```
### 架构设计
```
┌─────────────────────────────────────────────────────────────────────┐
│ 智队中枢 (Flask) │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 聊天界面 (Chat UI) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 会话列表 │ │ 聊天窗口 │ │ 机器人列表 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 智队机器人管理 (Bot Manager) │ │
│ │ - 机器人注册 │ │
│ │ - 机器人绑定 Agent │ │
│ │ - 机器人状态监控 │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 现有核心功能 │ │
│ │ - WebSocket Server │ │
│ │ - Session Manager │ │
│ │ - Agent Scheduler │ │
│ │ - Message Router │ │
│ └───────────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────────────┘
│ WebSocket + PIT Protocol
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 智队频道插件 (PIT Channel) │
│ 连接到绑定的 OpenClaw Agent │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ OpenClaw Agent (小白等) │
└─────────────────────────────────────────────────────────────────────┘
```
### 消息流
```
┌──────────┐ 登录 ┌──────────────┐
│ 用户 │ ──────────→ │ 智队中枢 │
└──────────┘ └──────────────┘
│ │
│ 选择机器人 │
↓ ↓
┌──────────┐ 创建会话 ┌──────────────┐
│ 机器人列表│ ──────────→ │ Session │
│ (小白等) │ │ (bot_id) │
└──────────┘ └──────────────┘
│ │
│ 发送消息 │
↓ ↓
┌──────────┐ 路由消息 ┌──────────────┐
│ 聊天窗口 │ ──────────→ │ Message │
│ │ │ Router │
└──────────┘ └──────────────┘
│
│ WebSocket
↓
┌──────────────┐
│ 智队频道插件 │
└──────────────┘
│
↓
┌──────────────┐
│ OpenClaw │
│ Agent (小白) │
└──────────────┘
```
### 与 QQ Bot 的对比
| 特性 | QQ Bot | 智队机器人 |
|------|--------|-----------|
| **用户入口** | QQ 客户端 | 智队中枢 Web/App |
| **消息通道** | QQ 协议 | WebSocket |
| **认证方式** | QQ 账号 | JWT Token |
| **会话管理** | QQ 群/私聊 | Session 模型 |
| **消息格式** | QQ 消息 | PIT 协议 |
| **Agent 绑定** | Channel 插件配置 | Bot → Gateway → Agent |
| **多机器人** | 多个 QQ Bot | 多个智队机器人 |
| **优势** | 用户基数大、无需安装 | 完全自主、功能可控 |
### 优势分析
| 优势 | 说明 |
|------|------|
| 🎯 **完全自主** | 不依赖第三方平台，完全可控 |
| 🔧 **功能可控** | 可以自定义所有功能，无平台限制 |
| 🔗 **统一入口** | 用户、机器人、Agent 统一管理 |
| 📊 **数据私有** | 所有数据存储在本地，隐私安全 |
| 🚀 **易于扩展** | 可以轻松添加新功能、新机器人 |
| 💰 **零成本** | 无需支付平台费用 |
---
@@ -51,6 +170,7 @@
| 缓存 | Redis | 7+ | 会话缓存、消息队列 |
| 数据库 | PostgreSQL | 15+ | 生产环境持久化 |
| 部署 | Gunicorn + Nginx | - | 生产环境部署 |
| **前端** | **Jinja2 + Vue.js 3** | **-** | **🆕 聊天界面** |
---
@@ -69,7 +189,8 @@
│ ├── Session Manager
│ ├── Message Router
│ ├── Agent Scheduler (加权轮询)
│ └── Message Queue (ACK机制)
│ ├── Message Queue (ACK机制)
│ └── 🆕 Bot Manager (机器人管理)
└── 数据层 (Data Layer)
├── PostgreSQL (持久化)
├── Redis (缓存/消息队列)
@@ -95,7 +216,8 @@ pit-router/
│ │ ├── agent.py # Agent 模型
│ │ ├── gateway.py # Gateway 模型
│ │ ├── message.py # 消息模型
│ │ └── connection.py # 连接模型
│ │ ├── connection.py # 连接模型
│ │ └── 🆕 bot.py # 机器人模型
│ ├── routes/ # HTTP 路由层
│ │ ├── __init__.py
│ │ ├── auth.py # 认证路由
@@ -103,24 +225,43 @@ pit-router/
│ │ ├── agents.py # Agent 路由
│ │ ├── gateways.py # Gateway 路由
│ │ ├── messages.py # 消息路由
│ │ └── stats.py # 统计接口
│ │ ├── stats.py # 统计接口
│ │ ├── 🆕 bots.py # 机器人管理 API
│ │ └── 🆕 chat.py # 聊天 API
│ ├── socketio/ # WebSocket 处理层
│ │ ├── __init__.py
│ │ ├── handlers.py # Socket.IO 事件处理
│ │ ├── events.py # 事件定义
│ │ └── auth.py # WebSocket 认证
│ │ ├── auth.py # WebSocket 认证
│ │ └── 🆕 chat_handlers.py # 聊天事件处理
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py
│ │ ├── session_service.py # 会话服务
│ │ ├── agent_service.py # Agent 服务
│ │ ├── message_service.py # 消息服务
│ │ ├── scheduler.py # Agent 调度器
│ │ └── message_queue.py # 消息队列管理
│ │ ├── message_queue.py # 消息队列管理
│ │ └── 🆕 bot_service.py # 机器人服务
│ ├── utils/ # 工具函数
│ │ ├── __init__.py
│ │ ├── validators.py # 输入验证
│ │ ├── security.py # 安全工具
│ │ └── helpers.py # 辅助函数
│ ├── templates/ # 🆕 前端模板
│ │ ├── base.html
│ │ ├── auth/
│ │ │ └── login.html
│ │ ├── components/
│ │ │ ├── navbar.html
│ │ │ ├── sidebar.html
│ │ │ └── toast.html
│ │ ├── 🆕 chat/ # 聊天界面
│ │ │ ├── index.html # 聊天主页
│ │ │ ├── session.html # 会话详情
│ │ │ └── bots.html # 机器人列表
│ │ └── 🆕 components/
│ │ ├── chat_window.html
│ │ └── message_bubble.html
│ └── extensions.py # Flask 扩展初始化
├── migrations/ # 数据库迁移
├── tests/ # 测试
@@ -128,7 +269,8 @@ pit-router/
│ ├── test_auth.py
│ ├── test_sessions.py
│ ├── test_messages.py
│ └── test_websocket.py
│ ├── test_websocket.py
│ └── 🆕 test_bots.py # 机器人测试
├── requirements.txt # Python 依赖
├── requirements-dev.txt # 开发依赖
├── config.yaml # 配置文件模板
@@ -156,17 +298,34 @@ pit-router/
| created_at | DateTime | 创建时间 |
| last_login_at | DateTime | 最后登录时间 |
### 🆕 机器人模型 (Bot)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | String(36) | 主键 UUID |
| name | String(80) | 机器人名称（如"小白"），唯一索引 |
| display_name | String(80) | 显示名称 |
| avatar | String(256) | 头像 URL |
| description | Text | 机器人描述 |
| gateway_id | String(36) | 绑定的 Gateway ID，外键 |
| agent_id | String(36) | 绑定的 Agent ID，外键 |
| status | String(20) | 状态：online/offline/busy |
| config | JSON | 配置（模型、温度等） |
| created_at | DateTime | 创建时间 |
| last_active_at | DateTime | 最后活跃时间 |
### 会话模型 (Session)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | String(36) | 主键 UUID |
| user_id | String(36) | 用户 ID，外键 |
| **🆕 bot_id** | **String(36)** | **机器人 ID，外键** |
| primary_agent_id | String(36) | 主 Agent ID |
| participating_agent_ids | JSON | 参与 Agent ID 列表 |
| user_socket_id | String(100) | 用户 WebSocket Socket ID |
| title | String(200) | 会话标题 |
| channel_type | String(20) | 渠道类型：web/desktop/mobile |
| channel_type | String(20) | 渠道类型：web/desktop/mobile/pit-bot |
| status | String(20) | 状态：active/paused/closed |
| message_count | Integer | 消息计数 |
| unread_count | Integer | 未读消息数 |
@@ -209,13 +368,13 @@ pit-router/
| last_heartbeat | DateTime | 最后心跳时间 |
| created_at | DateTime | 创建时间 |
### 消息模型 (Message) ⭐ 新增
### 消息模型 (Message)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | String(36) | 主键 UUID |
| session_id | String(36) | 会话 ID，外键 |
| sender_type | String(20) | 发送者类型：user/agent/system |
| sender_type | String(20) | 发送者类型：user/agent/bot/system |
| sender_id | String(36) | 发送者 ID |
| message_type | String(20) | 消息类型：text/media/system |
| content | Text | 消息内容 |
@@ -227,15 +386,15 @@ pit-router/
| created_at | DateTime | 创建时间 |
| delivered_at | DateTime | 送达时间 |
### 连接模型 (Connection) ⭐ 新增
### 连接模型 (Connection)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | String(36) | 主键 UUID |
| socket_id | String(100) | Socket.IO Socket ID |
| connection_type | String(20) | 连接类型：user/agent/gateway |
| connection_type | String(20) | 连接类型：user/agent/gateway/bot |
| entity_id | String(36) | 关联实体 ID |
| entity_type | String(20) | 实体类型：user/agent |
| entity_type | String(20) | 实体类型：user/agent/bot |
| ip_address | String(45) | IP 地址 (支持 IPv6) |
| user_agent | String(500) | 客户端信息 |
| status | String(20) | 状态：connected/disconnected |
@@ -259,6 +418,32 @@ GET /api/auth/me - 获取当前用户信息
POST /api/auth/verify - 验证 Token 有效性
```
### 🆕 机器人管理 API
```
GET /api/bots - 获取机器人列表
POST /api/bots - 创建机器人
GET /api/bots/:id - 获取机器人详情
PUT /api/bots/:id - 更新机器人配置
DELETE /api/bots/:id - 删除机器人
POST /api/bots/:id/bind - 绑定 Agent
POST /api/bots/:id/unbind - 解绑 Agent
GET /api/bots/:id/status - 获取机器人状态
POST /api/bots/:id/heartbeat - 机器人心跳上报
```
### 🆕 聊天 API
```
GET /api/chat/sessions - 获取聊天会话列表
POST /api/chat/sessions - 创建聊天会话
GET /api/chat/sessions/:id - 获取会话详情
GET /api/chat/sessions/:id/messages - 获取消息历史
POST /api/chat/sessions/:id/messages - 发送消息
PUT /api/chat/sessions/:id/read - 标记消息已读
DELETE /api/chat/sessions/:id - 关闭会话
```
### 会话 API
```
@@ -267,8 +452,8 @@ POST /api/sessions - 创建会话
GET /api/sessions/:id - 获取会话详情
PUT /api/sessions/:id/close - 关闭会话 (替代 DELETE)
GET /api/sessions/:id/messages - 获取会话消息
GET /api/sessions/:id/participants - 获取会话参与者 ⭐ 新增
POST /api/sessions/:id/transfer - 会话转接 ⭐ 新增
GET /api/sessions/:id/participants - 获取会话参与者
POST /api/sessions/:id/transfer - 会话转接
```
### Agent API
@@ -278,8 +463,8 @@ GET /api/agents - 获取 Agent 列表
GET /api/agents/:id - 获取 Agent 详情
GET /api/agents/:id/status - 获取 Agent 实时状态
PUT /api/agents/:id/config - 更新 Agent 配置
POST /api/agents/:id/heartbeat - Agent 心跳上报 ⭐ 新增
GET /api/agents/available - 获取可用 Agent 列表 ⭐ 新增
POST /api/agents/:id/heartbeat - Agent 心跳上报
GET /api/agents/available - 获取可用 Agent 列表
```
### Gateway API
@@ -289,11 +474,11 @@ GET /api/gateways - 获取 Gateway 列表
POST /api/gateways - 注册 Gateway
DELETE /api/gateways/:id - 注销 Gateway
GET /api/gateways/:id/status - 获取 Gateway 状态
POST /api/gateways/:id/heartbeat - Gateway 心跳上报 ⭐ 新增
PUT /api/gateways/:id/agents - 更新 Gateway 的 Agent 列表 ⭐ 新增
POST /api/gateways/:id/heartbeat - Gateway 心跳上报
PUT /api/gateways/:id/agents - 更新 Gateway 的 Agent 列表
```
### 消息 API ⭐ 新增
### 消息 API
```
POST /api/messages - 发送消息 (HTTP 方式)
@@ -302,13 +487,14 @@ PUT /api/messages/:id/ack - 确认消息已送达
PUT /api/messages/:id/read - 标记消息已读
```
### 统计 API ⭐ 新增
### 统计 API
```
GET /api/stats - 系统统计信息
GET /api/stats/sessions - 会话统计
GET /api/stats/messages - 消息统计
GET /api/stats/agents - Agent 统计
GET /api/stats/bots - 🆕 机器人统计
```
---
@@ -334,7 +520,7 @@ GET /api/stats/agents - Agent 统计
| `authenticated` | S→C | 认证成功 | `{ user_id: string, socket_id: string }` |
| `auth_error` | S→C | 认证失败 | `{ code: string, message: string }` |
### 心跳事件 ⭐ 新增
### 心跳事件
| 事件 | 方向 | 说明 | 参数 |
|------|------|------|------|
@@ -342,6 +528,23 @@ GET /api/stats/agents - Agent 统计
| `pong` | S→C | 心跳响应 | `{ timestamp: number }` |
| `heartbeat_timeout` | S→C | 心跳超时 | `{ socket_id: string }` |
### 🆕 聊天事件
| 事件 | 方向 | 说明 | 参数 |
|------|------|------|------|
| `chat.create` | C→S | 创建聊天会话 | `{ bot_id, title? }` |
| `chat.created` | S→C | 会话已创建 | `{ session_id, bot }` |
| `chat.join` | C→S | 加入会话 | `{ session_id }` |
| `chat.joined` | S→C | 已加入会话 | `{ session_id, bot, messages }` |
| `chat.leave` | C→S | 离开会话 | `{ session_id }` |
| `chat.left` | S→C | 已离开会话 | `{ session_id }` |
| `chat.message` | C→S | 发送消息 | `{ session_id, content, reply_to? }` |
| `chat.message` | S→C | 收到消息 | `{ message_id, session_id, sender_type, content, timestamp }` |
| `chat.typing` | C→S | 正在输入 | `{ session_id, is_typing }` |
| `chat.typing` | S→C | 对方正在输入 | `{ session_id, is_typing }` |
| `chat.read` | C→S | 消息已读 | `{ session_id, message_ids }` |
| `chat.closed` | S→C | 会话被关闭 | `{ session_id, reason }` |
### 会话事件
| 事件 | 方向 | 说明 | 参数 |
@@ -350,10 +553,10 @@ GET /api/stats/agents - Agent 统计
| `session.created` | S→C | 会话已创建 | `{ session_id, agent_id }` |
| `session.join` | C→S | 加入会话 | `{ session_id }` |
| `session.joined` | S→C | 已加入会话 | `{ session_id, participants: [] }` |
| `session.leave` | C→S | 离开会话 ⭐ 新增 | `{ session_id }` |
| `session.left` | S→C | 已离开会话 ⭐ 新增 | `{ session_id, user_id }` |
| `session.closed` | S→C | 会话被关闭 ⭐ 新增 | `{ session_id, reason }` |
| `session.assigned` | S→C | Agent 分配通知 ⭐ 新增 | `{ session_id, agent_id }` |
| `session.leave` | C→S | 离开会话 | `{ session_id }` |
| `session.left` | S→C | 已离开会话 | `{ session_id, user_id }` |
| `session.closed` | S→C | 会话被关闭 | `{ session_id, reason }` |
| `session.assigned` | S→C | Agent 分配通知 | `{ session_id, agent_id }` |
### 消息事件
@@ -361,11 +564,11 @@ GET /api/stats/agents - Agent 统计
|------|------|------|------|
| `message.send` | C→S | 发送消息 | `{ session_id, content, type, reply_to? }` |
| `message` | S→C | 收到消息 | `{ message_id, session_id, sender, content, timestamp }` |
| `message.ack` | C→S | 消息确认 ⭐ 新增 | `{ message_id, status: delivered/read }` |
| `message.acked` | S→C | 确认已收到 ⭐ 新增 | `{ message_id, status }` |
| `message.ack` | C→S | 消息确认 | `{ message_id, status: delivered/read }` |
| `message.acked` | S→C | 确认已收到 | `{ message_id, status }` |
| `message.stream` | S→C | 流式消息 | `{ session_id, chunk, is_end }` |
| `message.read` | C→S | 消息已读 ⭐ 新增 | `{ session_id, message_ids: [] }` |
| `typing` | C→S | 正在输入 ⭐ 新增 | `{ session_id, is_typing: boolean }` |
| `message.read` | C→S | 消息已读 | `{ session_id, message_ids: [] }` |
| `typing` | C→S | 正在输入 | `{ session_id, is_typing: boolean }` |
### 错误事件
@@ -374,8 +577,9 @@ GET /api/stats/agents - Agent 统计
| `error` | S→C | 通用错误 | `{ code, message, details? }` |
| `session_error` | S→C | 会话错误 | `{ session_id, code, message }` |
| `message_error` | S→C | 消息错误 | `{ message_id, code, message }` |
| `🆕 chat_error` | S→C | 聊天错误 | `{ session_id?, code, message }` |
### 消息格式 (与 PIT Channel 兼容) ⭐ 新增
### 消息格式 (与 PIT Channel 兼容)
```json
{
@@ -398,7 +602,7 @@ GET /api/stats/agents - Agent 统计
---
## Agent 调度策略 ⭐ 新增
## Agent 调度策略
### 调度算法
@@ -430,7 +634,7 @@ scheduler:
---
## 消息可靠性机制 ⭐ 新增
## 消息可靠性机制
### ACK 确认流程
@@ -474,6 +678,7 @@ MESSAGE_RETENTION = {
| HTTP API | JWT Bearer Token | Authorization: Bearer <token> |
| WebSocket | JWT Query Param | ws://host/ws?token=<jwt> |
| Gateway | Token + IP 白名单 | 双重验证 |
| 🆕 Chat UI | Session + JWT | 登录后访问 |
### Token 策略
@@ -500,7 +705,7 @@ MESSAGE_RETENTION = {
## 部署架构
### Docker Compose ⭐ 完善
### Docker Compose
```yaml
version: '3.8'
@@ -585,32 +790,75 @@ volumes:
---
## 开发计划
## 开发进度
| 阶段 | 状态 | 内容 |
|------|------|------|
| **Phase 1** | ✅ 完成 | 核心功能（数据模型、HTTP API、WebSocket） |
| **Phase 2** | ✅ 完成 | 服务层（调度器、消息队列、会话/消息/Agent 服务） |
| **Phase 3** | ✅ 完成 | 工具层（验证器、安全工具、辅助函数） |
| **Phase 4** | ⚠️ 部分 | 测试部署（单元测试 80%，集成/性能/部署未完成） |
| **Phase 5** | ⏳ 待开始 | 运维工具（Nginx + SSL、日志、监控） |
### ✅ 已完成功能
### 详细进度
#### 核心功能 (Phase 1-3)
- ✅ 数据模型（6个）- 100%
- ✅ HTTP API（6组）- 100%
- ✅ WebSocket 事件 - 100%
- ✅ 调度器（5种策略）- 100%
- ✅ 消息队列（ACK）- 100%
- ✅ 业务服务层 - 100%
- ✅ 工具函数 - 100%
- ✅ Docker 配置 - 100%
- ⚠️ 单元测试 - 24/31 通过 (80%)
- ⏳ 集成测试 - 待完成
- ⏳ 性能测试 - 待完成
- ⏳ Nginx + SSL - 待完成
- ⏳ 日志系统 - 待完成
- ⏳ 监控告警 - 待完成
| 模块 | 功能 | 完成度 | 完成日期 |
|------|------|--------|----------|
| **数据模型** | User, Session, Agent, Gateway, Message, Connection | 100% | 2026-03-14 |
| **HTTP API** | 认证、会话、Agent、Gateway、消息、统计 | 100% | 2026-03-14 |
| **WebSocket** | 认证、心跳、会话、消息事件 | 100% | 2026-03-14 |
| **调度器** | 5 种调度策略 | 100% | 2026-03-14 |
| **消息队列** | ACK 机制、重试 | 100% | 2026-03-14 |
| **业务服务** | 会话、消息、Agent 服务 | 100% | 2026-03-14 |
| **工具函数** | 验证、安全、辅助 | 100% | 2026-03-14 |
| **Docker** | Dockerfile + docker-compose | 100% | 2026-03-14 |
| **Web UI** | 登录页、频道配置、会话管理 | 100% | 2026-03-15 |
| **自动部署** | Webhook + 脚本 | 100% | 2026-03-15 |
#### 智队机器人功能设计 (Phase 6)
| 模块 | 功能 | 完成度 | 完成日期 |
|------|------|--------|----------|
| **Bot 模型设计** | 数据模型设计 | 100% | 2026-03-15 |
| **机器人 API 设计** | REST API 设计 | 100% | 2026-03-15 |
| **聊天 API 设计** | REST API 设计 | 100% | 2026-03-15 |
| **聊天事件设计** | WebSocket 事件设计 | 100% | 2026-03-15 |
| **聊天界面设计** | UI/UX 设计 | 100% | 2026-03-15 |
### ⏳ 待完成功能
#### 智队机器人开发 (Phase 6)
| 模块 | 功能 | 预计时间 | 优先级 |
|------|------|----------|--------|
| **Bot 模型实现** | 创建 bot.py 数据模型 | 0.5 天 | 🔴 高 |
| **机器人 API 实现** | 实现 bots.py 路由 | 1 天 | 🔴 高 |
| **聊天 API 实现** | 实现 chat.py 路由 | 0.5 天 | 🔴 高 |
| **聊天事件实现** | 实现 chat_handlers.py | 1 天 | 🔴 高 |
| **聊天界面实现** | 聊天 UI 页面开发 | 2 天 | 🔴 高 |
| **机器人服务** | 实现 bot_service.py | 0.5 天 | 🟡 中 |
| **机器人绑定** | Agent 绑定逻辑 | 0.5 天 | 🟡 中 |
| **状态同步** | 机器人状态监控 | 0.5 天 | 🟡 中 |
**预计总工期**：6.5 天
#### 测试与运维 (Phase 4-5)
| 模块 | 功能 | 预计时间 | 优先级 |
|------|------|----------|--------|
| **单元测试** | 补充测试用例 | 1 天 | 🟡 中 |
| **集成测试** | 端到端测试 | 1 天 | 🟡 中 |
| **性能测试** | 压力测试 | 0.5 天 | 🟢 低 |
| **Nginx + SSL** | HTTPS 配置 | 0.5 天 | 🟢 低 |
| **日志系统** | 结构化日志 | 0.5 天 | 🟢 低 |
| **监控告警** | Prometheus + Grafana | 1 天 | 🟢 低 |
**预计总工期**：4.5 天
### 总体进度
| 阶段 | 状态 | 内容 | 完成度 |
|------|------|------|--------|
| **Phase 1** | ✅ 完成 | 核心功能（数据模型、HTTP API、WebSocket） | 100% |
| **Phase 2** | ✅ 完成 | 服务层（调度器、消息队列、会话/消息/Agent 服务） | 100% |
| **Phase 3** | ✅ 完成 | 工具层（验证器、安全工具、辅助函数） | 100% |
| **Phase 4** | ⚠️ 部分 | 测试部署（单元测试 80%，集成/性能/部署未完成） | 80% |
| **Phase 5** | ⏳ 待开始 | 运维工具（Nginx + SSL、日志、监控） | 0% |
| **Phase 6** | 🚧 进行中 | 智队机器人（设计完成，开发中） | 20% |
**总进度**: 约 85%
@@ -651,109 +899,31 @@ volumes:
---
## 自动部署 🔄
## 自动部署
> Gitea 仓库提交后自动更新 Docker 容器
### 方案对比
| 方案 | 复杂度 | 说明 |
|------|--------|------|
| **方案 1: Webhook + 脚本** | ⭐ 简单 | 推荐，实现快、依赖少 |
| **方案 2: Gitea Actions** | ⭐⭐⭐ 中等 | 功能强大，需要配置 Runner |
| **方案 3: Watchtower** | ⭐⭐ 简单 | 自动监控镜像更新 |
### 推荐方案：Webhook + 脚本
#### 架构流程
### 架构流程
```
开发者推送代码 → Gitea 触发 Webhook → 更新脚本执行
→ 拉取代码 → 构建镜像 → 重启容器 → 健康检查
```
#### 1. 更新脚本
```bash
#!/bin/bash
# /www/wwwroot/pit-router/auto-update.sh
set -e
cd /www/wwwroot/pit-router
# 拉取最新代码
git fetch origin && git reset --hard origin/main
# 重建并启动
docker-compose down
docker-compose build --no-cache
docker-compose up -d
# 健康检查
sleep 10
curl -sf http://localhost:1999/health && echo "✅ 更新成功"
```
#### 2. Webhook 服务
```python
# /www/wwwroot/pit-router/webhook-server.py
from flask import Flask, request, jsonify
import hmac, hashlib, subprocess
app = Flask(__name__)
SECRET = 'your-webhook-secret'
@app.route('/webhook/pit-router', methods=['POST'])
def handle():
# 验证签名
sig = request.headers.get('X-Gitea-Signature', '')
expected = 'sha256=' + hmac.new(SECRET.encode(), request.data, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, expected):
return {'error': 'Invalid signature'}, 401
# 执行更新
result = subprocess.run(['/www/wwwroot/pit-router/auto-update.sh'], capture_output=True)
return {'status': 'success' if result.returncode == 0 else 'error'}
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5001)
```
#### 3. 配置 Gitea Webhook
```bash
curl -X POST "http://localhost:3000/api/v1/repos/yunxiafei/pit-router/hooks" \
-H "Authorization: token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "gitea",
"config": {
"url": "http://localhost:5001/webhook/pit-router",
"content_type": "json",
"secret": "your-webhook-secret"
},
"events": ["push"],
"active": true
}'
```
### 实施清单
- [ ] 创建 `auto-update.sh` 脚本
- [ ] 创建 `webhook-server.py` 服务
- [ ] 配置 systemd 服务
- [ ] 配置 Gitea Webhook
- [ ] 测试自动更新
**预计时间**：30 分钟
- [x] 创建 `auto-update.sh` 脚本
- [x] 创建 `webhook-server.py` 服务
- [x] 配置 systemd 服务
- [x] 配置 Gitea Webhook
- [x] 测试自动更新
---
## 相关项目
- [PIT Channel 插件](http://1.14.58.157:3000/yunxiafei/PIT_Channel) - OpenClaw Channel 插件（智队中枢客户端）
- [PIT Channel 插件](http://localhost:3000/yunxiafei/PIT_Channel) - OpenClaw Channel 插件（智队中枢客户端）
- [PIT Client](http://localhost:3000/yunxiafei/pit-client) - 用户交互层应用
---
@@ -763,15 +933,4 @@ MIT License
---
*创建时间: 2026-03-14 | 更新: 2026-03-14 | 作者: 小白 🐶*
# Test webhook
*创建时间: 2026-03-14 | 更新: 2026-03-15 | 作者: 小白 🐶*