docs: 完善智队机器人技术方案 (v0.9.1)
- 完善新建智队机器人技术方案 - 完善机器人绑定 Agent 流程 - 添加创建聊天会话流程说明 - 添加完整使用流程说明 - 添加前端新建机器人功能说明
This commit is contained in:
小白
341
README.md
341
README.md
@@ -5,12 +5,19 @@
|
||||
**中文名**：智队中枢
|
||||
**英文名**：PIT Router
|
||||
|
||||
**当前版本**：v0.9.0
|
||||
**当前版本**：v0.9.1
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v0.9.1 (2026-03-15) 📝 技术方案完善
|
||||
- ✅ 完善新建智队机器人技术方案
|
||||
- ✅ 完善机器人绑定 Agent 流程
|
||||
- ✅ 添加创建聊天会话流程说明
|
||||
- ✅ 添加完整使用流程说明
|
||||
- ✅ 添加前端新建机器人功能
|
||||
|
||||
### v0.9.0 (2026-03-15) 🎉 智队机器人功能完成
|
||||
- ✅ Bot 数据模型实现 (app/models/bot.py)
|
||||
- ✅ 机器人管理 API 实现 (app/routes/bots.py)
|
||||
@@ -163,6 +170,338 @@ QQ 用户 → QQ 客户端 → QQ Bot（Channel 插件）→ OpenClaw Agent
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 新建智队机器人技术方案
|
||||
|
||||
#### 功能入口
|
||||
|
||||
**前端位置**：首页右上角「➕ 新建机器人」按钮
|
||||
|
||||
**触发条件**：用户已登录
|
||||
|
||||
#### 新建机器人流程
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ 用户点击 │
|
||||
│ "新建机器人" │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 弹出创建表单 │
|
||||
│ - 名称（必填）│
|
||||
│ - 显示名称 │
|
||||
│ - 头像选择 │
|
||||
│ - 描述 │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 前端验证 │
|
||||
│ 名称不为空 │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ POST /api/bots│
|
||||
│ 创建机器人 │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 后端处理 │
|
||||
│ - 生成 Token │
|
||||
│ - 创建 Bot │
|
||||
│ - 返回结果 │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 前端更新列表 │
|
||||
│ 显示新机器人 │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
#### 创建机器人 API
|
||||
|
||||
**请求**：
|
||||
```http
|
||||
POST /api/bots/
|
||||
Authorization: Bearer <jwt_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "xiaobai",
|
||||
"display_name": "小白",
|
||||
"avatar": "🐶",
|
||||
"description": "忠诚的AI助手小狗"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"bot": {
|
||||
"id": "uuid",
|
||||
"name": "xiaobai",
|
||||
"display_name": "小白",
|
||||
"avatar": "🐶",
|
||||
"description": "忠诚的AI助手小狗",
|
||||
"status": "offline",
|
||||
"agent_id": null,
|
||||
"capabilities": ["chat"],
|
||||
"config": { ... },
|
||||
"created_at": "2026-03-15T03:00:00Z"
|
||||
},
|
||||
"token": "bot_xxx..." // 只返回一次，用于 API 调用
|
||||
}
|
||||
```
|
||||
|
||||
#### 前端实现
|
||||
|
||||
**组件**：`frontend/src/views/HomeView.vue`
|
||||
|
||||
**功能**：
|
||||
- 模态框表单
|
||||
- 头像选择器（12 个预设头像）
|
||||
- 表单验证
|
||||
- 创建成功后自动刷新列表
|
||||
|
||||
**Store 方法**：
|
||||
```typescript
|
||||
// stores/chat.ts
|
||||
async function createBot(data: {
|
||||
name: string;
|
||||
display_name?: string;
|
||||
avatar?: string;
|
||||
description?: string;
|
||||
}) {
|
||||
const response = await botApi.create(data);
|
||||
const bot = response.data.bot;
|
||||
bots.value.push(bot);
|
||||
return bot;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 机器人绑定 Agent 流程
|
||||
|
||||
#### 绑定流程图
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 机器人绑定 Agent 流程 │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────┐
|
||||
│ 1. 创建机器人 │
|
||||
│ (无 Agent) │
|
||||
│ status: │
|
||||
│ offline │
|
||||
└──────┬───────┘
|
||||
│
|
||||
│ 用户选择 Agent
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 2. 绑定 Agent │
|
||||
│ POST /api/bots/:id/bind
|
||||
│ { agent_id } │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 3. 后端验证 │
|
||||
│ - Agent 存在 │
|
||||
│ - Agent 在线 │
|
||||
│ - 权限检查 │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 4. 更新 Bot │
|
||||
│ agent_id = x │
|
||||
│ status = │
|
||||
│ agent.status│
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 5. Bot 可用 │
|
||||
│ 用户可以开始 │
|
||||
│ 聊天会话 │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
#### 绑定 Agent API
|
||||
|
||||
**请求**：
|
||||
```http
|
||||
POST /api/bots/{bot_id}/bind
|
||||
Authorization: Bearer <jwt_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"agent_id": "agent-001"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"bot": {
|
||||
"id": "bot-uuid",
|
||||
"name": "xiaobai",
|
||||
"agent_id": "agent-001",
|
||||
"status": "online"
|
||||
},
|
||||
"message": "Bot bound to agent xiaobai-agent"
|
||||
}
|
||||
```
|
||||
|
||||
#### 解绑 Agent API
|
||||
|
||||
**请求**：
|
||||
```http
|
||||
POST /api/bots/{bot_id}/unbind
|
||||
Authorization: Bearer <jwt_token>
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"bot": {
|
||||
"id": "bot-uuid",
|
||||
"agent_id": null,
|
||||
"status": "offline"
|
||||
},
|
||||
"message": "Bot unbound from agent"
|
||||
}
|
||||
```
|
||||
|
||||
#### 状态同步机制
|
||||
|
||||
**Agent 状态变化时**：
|
||||
```
|
||||
Agent 状态变化 → Gateway 心跳 → 更新 Agent.status
|
||||
↓
|
||||
同步到绑定该 Agent 的所有 Bot
|
||||
↓
|
||||
更新 Bot.status
|
||||
```
|
||||
|
||||
**代码实现**：
|
||||
```python
|
||||
# app/services/bot_service.py
|
||||
@staticmethod
|
||||
def sync_agent_status(bot: Bot) -> Bot:
|
||||
"""同步 Agent 状态到 Bot"""
|
||||
if bot.agent_id:
|
||||
agent = Agent.query.get(bot.agent_id)
|
||||
if agent:
|
||||
bot.status = agent.status
|
||||
else:
|
||||
bot.status = 'offline'
|
||||
else:
|
||||
bot.status = 'offline'
|
||||
|
||||
bot.last_active_at = datetime.utcnow()
|
||||
db.session.commit()
|
||||
return bot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 创建聊天会话流程
|
||||
|
||||
#### 前置条件检查
|
||||
|
||||
```
|
||||
用户选择机器人 → 检查 Bot.agent_id
|
||||
│
|
||||
├── 有 Agent → 创建会话成功
|
||||
│
|
||||
└── 无 Agent → 提示"机器人未绑定 Agent"
|
||||
```
|
||||
|
||||
#### 创建会话 API
|
||||
|
||||
**请求**：
|
||||
```http
|
||||
POST /api/chat/sessions
|
||||
Authorization: Bearer <jwt_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"bot_id": "bot-uuid",
|
||||
"title": "与小白的对话"
|
||||
}
|
||||
```
|
||||
|
||||
**后端处理**：
|
||||
```python
|
||||
# 1. 验证 Bot 存在
|
||||
bot = BotService.get_bot_by_id(bot_id)
|
||||
|
||||
# 2. 检查权限
|
||||
if not BotService.check_permission(user, bot, 'use'):
|
||||
return error('Permission denied')
|
||||
|
||||
# 3. 检查 Agent 绑定
|
||||
if not bot.agent_id:
|
||||
return error('Bot has no agent bound')
|
||||
|
||||
# 4. 获取 Agent
|
||||
agent = Agent.query.get(bot.agent_id)
|
||||
|
||||
# 5. 创建会话
|
||||
session = Session(
|
||||
user_id=user_id,
|
||||
bot_id=bot.id,
|
||||
primary_agent_id=agent.id,
|
||||
title=title,
|
||||
channel_type='pit-bot',
|
||||
status='active'
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 完整使用流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 用户使用流程 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
1. 登录智队中枢
|
||||
└── POST /api/auth/login → 获取 JWT Token
|
||||
|
||||
2. 查看机器人列表
|
||||
└── GET /api/bots/ → 返回可用机器人
|
||||
|
||||
3. 【可选】新建机器人
|
||||
└── POST /api/bots/ → 创建机器人（status: offline）
|
||||
|
||||
4. 【可选】绑定 Agent
|
||||
└── POST /api/bots/:id/bind → 绑定后 status 变为 online
|
||||
|
||||
5. 选择机器人开始聊天
|
||||
└── POST /api/chat/sessions → 创建会话
|
||||
|
||||
6. 发送消息
|
||||
└── POST /api/chat/sessions/:id/messages
|
||||
└── 或 WebSocket: chat.send.message
|
||||
|
||||
7. 接收 Agent 响应
|
||||
└── WebSocket: chat.message 事件
|
||||
|
||||
8. 继续对话或关闭会话
|
||||
└── DELETE /api/chat/sessions/:id → 关闭会话
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 与 QQ Bot 的对比
|
||||
|
||||
| 特性 | QQ Bot | 智队机器人 |
|
||||
|
||||
Reference in New Issue
Block a user