From cb2bb5ec35a9e739c5c55b53e0f9dd7471d91296 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E7=99=BD?= Date: Sun, 15 Mar 2026 11:44:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=99=BA=E9=98=9F?= =?UTF-8?q?=E6=9C=BA=E5=99=A8=E4=BA=BA=E6=8A=80=E6=9C=AF=E6=96=B9=E6=A1=88?= =?UTF-8?q?=20(v0.9.1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 完善新建智队机器人技术方案 - 完善机器人绑定 Agent 流程 - 添加创建聊天会话流程说明 - 添加完整使用流程说明 - 添加前端新建机器人功能说明 --- README.md | 341 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 340 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3c77563..9a36b4b 100644 --- a/README.md +++ b/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 +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 +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 +``` + +**响应**： +```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 +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 | 智队机器人 |