docs: 完善智队机器人技术方案 (v0.9.1)

- 完善新建智队机器人技术方案
- 完善机器人绑定 Agent 流程
- 添加创建聊天会话流程说明
- 添加完整使用流程说明
- 添加前端新建机器人功能说明

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 | 智队机器人 |