From 066ccf0d28b36d16d7702a887960d040e5425c63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E7=99=BD?= Date: Sun, 15 Mar 2026 09:47:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E6=99=BA=E9=98=9F?= =?UTF-8?q?=E6=9C=BA=E5=99=A8=E4=BA=BA=E5=8A=9F=E8=83=BD=E8=AF=A6=E7=BB=86?= =?UTF-8?q?=E6=8A=80=E6=9C=AF=E6=96=B9=E6=A1=88=20(v0.8.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增智队机器人功能模块设计 - 新增 Bot 数据模型设计 - 新增机器人管理 API 设计 - 新增聊天界面设计 - 新增聊天 WebSocket 事件设计 - 更新已完成工作列表 - 更新待完成工作列表 - 更新项目版本至 v0.8.0 --- README.md | 471 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 315 insertions(+), 156 deletions(-) diff --git a/README.md b/README.md index a592c4a..e8922d5 100644 --- a/README.md +++ b/README.md @@ -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 | | WebSocket | JWT Query Param | ws://host/ws?token= | | 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 | 作者: 小白 🐶*