docs: 更新文档

assets/API.md

@@ -651,3 +651,464 @@ data: {"content": "错误信息描述"}
 ```
 
 用户通过 `/api/auth/users/{user_id}` 接口设置权限级别。
+
+---
+
+## Agent 管理 `/api/agents`
+
+Agent 是独立的可复用 AI 助手模板，可在聊天室中使用。
+
+### GET /api/agents/
+获取用户的所有 Agent
+
+**请求头：** `Authorization: Bearer <token>`
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "user_id": 1,
+      "name": "代码助手",
+      "role": "专注于 Python 和 JavaScript 开发",
+      "provider_id": 1,
+      "model": "deepseek-chat",
+      "system_prompt": "You are a helpful coding assistant...",
+      "color": "#10b981",
+      "created_at": "2024-01-01T00:00:00",
+      "updated_at": "2024-01-01T00:00:00"
+    }
+  ]
+}
+```
+
+### POST /api/agents/
+创建 Agent
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "name": "代码助手",
+  "role": "专注于 Python 和 JavaScript 开发",
+  "provider_id": 1,
+  "model": "deepseek-chat",
+  "system_prompt": "You are a helpful coding assistant.",
+  "color": "#10b981"
+}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "message": "Agent created",
+  "data": {
+    "id": 1,
+    "name": "代码助手",
+    ...
+  }
+}
+```
+
+### GET /api/agents/{agent_id}
+获取 Agent 详情
+
+**路径参数：** `agent_id`: Agent ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+### PUT /api/agents/{agent_id}
+更新 Agent
+
+**路径参数：** `agent_id`: Agent ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "name": "新名称",
+  "role": "新的角色描述",
+  "system_prompt": "新的系统提示...",
+  "color": "#ff6b6b"
+}
+```
+
+### DELETE /api/agents/{agent_id}
+删除 Agent
+
+**路径参数：** `agent_id`: Agent ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+---
+
+## 聊天室 `/api/chat-rooms`
+
+聊天室允许多个 Agent 同时参与讨论，协作完成复杂任务。
+
+### GET /api/chat-rooms/
+获取聊天室列表
+
+**查询参数：**
+- `page` (可选): 页码，默认1
+- `page_size` (可选): 每页数量，默认20
+
+**请求头：** `Authorization: Bearer <token>`
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "id": "room_xxx",
+        "user_id": 1,
+        "title": "项目讨论",
+        "task": "讨论新功能的实现方案",
+        "status": "idle",
+        "max_rounds": 5,
+        "current_round": 0,
+        "agents": [...],
+        "created_at": "2024-01-01T00:00:00",
+        "updated_at": "2024-01-01T00:00:00"
+      }
+    ],
+    "total": 10,
+    "page": 1,
+    "page_size": 20
+  }
+}
+```
+
+### POST /api/chat-rooms/
+创建聊天室
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "title": "项目讨论",
+  "task": "讨论新功能的实现方案",
+  "max_rounds": 5,
+  "agents": [
+    {
+      "agent_id": 1,
+      "name": "代码助手",
+      "role": "后端开发"
+    },
+    {
+      "name": "测试助手",
+      "role": "QA 工程师",
+      "provider_id": 1,
+      "model": "deepseek-chat",
+      "system_prompt": "你是一个测试工程师...",
+      "color": "#f59e0b"
+    }
+  ]
+}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "message": "Room created",
+  "data": {
+    "id": "room_xxx",
+    "title": "项目讨论",
+    ...
+  }
+}
+```
+
+### GET /api/chat-rooms/{room_id}
+获取聊天室详情
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "room_xxx",
+    "title": "项目讨论",
+    "task": "讨论新功能的实现方案",
+    "status": "idle",
+    "max_rounds": 5,
+    "current_round": 0,
+    "message_count": 10,
+    "agents": [
+      {
+        "id": 1,
+        "name": "代码助手",
+        "role": "后端开发",
+        "turn_order": 0,
+        ...
+      }
+    ]
+  }
+}
+```
+
+### PUT /api/chat-rooms/{room_id}
+更新聊天室
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "title": "新标题",
+  "task": "新的任务描述",
+  "max_rounds": 10,
+  "status": "idle"
+}
+```
+
+### DELETE /api/chat-rooms/{room_id}
+删除聊天室
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+### POST /api/chat-rooms/{room_id}/start
+启动聊天室（流式响应 - SSE）
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**SSE 事件类型：**
+
+#### room_started
+聊天室启动
+```json
+event: room_started
+data: {"type": "room_started", "room_id": "room_xxx", "task": "讨论新功能..."}
+```
+
+#### round_start
+回合开始
+```json
+event: round_start
+data: {"type": "round_start", "round": 1, "max_rounds": 5}
+```
+
+#### message_start
+消息开始
+```json
+event: message_start
+data: {"type": "message_start", "id": "msg_xxx", "room_id": "room_xxx", "role": "assistant", "sender_name": "代码助手", "sender_color": "#10b981", "round_number": 1}
+```
+
+#### message_chunk
+消息内容增量
+```json
+event: message_chunk
+data: {"type": "message_chunk", "id": "msg_xxx", "content": "我", "accumulated": "我认为..."}
+```
+
+#### message_end
+消息结束
+```json
+event: message_end
+data: {"type": "message_end", "id": "msg_xxx", "content": "完整的回复内容...", "token_count": 150}
+```
+
+#### message
+完整消息（存储用）
+```json
+event: message
+data: {"type": "message", "id": "msg_xxx", "conversation_id": null, "room_id": "room_xxx", "role": "assistant", "content": "...", "text": "...", "sender_name": "代码助手", "sender_color": "#10b981", "round_number": 1}
+```
+
+#### round_end
+回合结束
+```json
+event: round_end
+data: {"type": "round_end", "round": 1}
+```
+
+#### room_completed
+聊天室完成
+```json
+event: room_completed
+data: {"type": "room_completed", "room_id": "room_xxx", "total_rounds": 5}
+```
+
+#### room_paused
+聊天室暂停
+```json
+event: room_paused
+data: {"type": "room_paused", "room_id": "room_xxx", "round": 3}
+```
+
+#### agent_error
+Agent 错误
+```json
+event: agent_error
+data: {"type": "agent_error", "agent": "代码助手", "error": "错误描述"}
+```
+
+#### error
+通用错误
+```json
+event: error
+data: {"type": "error", "content": "错误信息"}
+```
+
+### POST /api/chat-rooms/{room_id}/stop
+停止运行中的聊天室
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+### POST /api/chat-rooms/{room_id}/reset
+重置聊天室（清除所有消息）
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+### GET /api/chat-rooms/{room_id}/messages
+获取聊天室消息
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**响应：**
+```json
+{
+  "success": true,
+  "data": {
+    "messages": [
+      {
+        "id": "msg_xxx",
+        "room_id": "room_xxx",
+        "role": "user",
+        "text": "讨论新功能...",
+        "sender_name": "用户",
+        "sender_color": "#10b981",
+        "round_number": 0,
+        "created_at": "2024-01-01T00:00:00"
+      },
+      {
+        "id": "msg_yyy",
+        "room_id": "room_xxx",
+        "role": "assistant",
+        "text": "我认为应该...",
+        "process_steps": [...],
+        "sender_name": "代码助手",
+        "sender_color": "#2563eb",
+        "round_number": 1,
+        "created_at": "2024-01-01T00:00:01"
+      }
+    ],
+    "room": {...}
+  }
+}
+```
+
+### POST /api/chat-rooms/{room_id}/agents
+向聊天室添加 Agent
+
+**路径参数：** `room_id`: 聊天室 ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "agent_id": 1,
+  "name": "自定义名称（可选）",
+  "role": "自定义角色（可选）"
+}
+```
+
+### PUT /api/chat-rooms/{room_id}/agents/{agent_id}
+更新聊天室中的 Agent
+
+**路径参数：**
+- `room_id`: 聊天室 ID
+- `agent_id`: RoomAgent ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+**请求体：**
+```json
+{
+  "name": "新名称",
+  "role": "新角色",
+  "turn_order": 2
+}
+```
+
+### DELETE /api/chat-rooms/{room_id}/agents/{agent_id}
+从聊天室移除 Agent
+
+**路径参数：**
+- `room_id`: 聊天室 ID
+- `agent_id`: RoomAgent ID
+
+**请求头：** `Authorization: Bearer <token>`
+
+---
+
+## 聊天室状态
+
+| 状态 | 说明 |
+|------|------|
+| `idle` | 空闲，未开始 |
+| `running` | 运行中 |
+| `paused` | 已暂停 |
+| `completed` | 已完成 |
+| `error` | 错误 |
+
+---
+
+## Agent 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | Agent 唯一标识 |
+| `user_id` | int | 所属用户 ID |
+| `name` | string | Agent 名称 |
+| `role` | string | Agent 角色描述 |
+| `provider_id` | int | LLM 提供商 ID（可选） |
+| `model` | string | 模型名称 |
+| `system_prompt` | string | 系统提示词 |
+| `color` | string | 颜色代码（用于前端显示） |
+| `created_at` | datetime | 创建时间 |
+| `updated_at` | datetime | 更新时间 |
+
+---
+
+## 聊天室 Agent 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | RoomAgent 唯一标识 |
+| `room_id` | string | 聊天室 ID |
+| `agent_id` | int | 关联的 Agent 模板 ID（可选） |
+| `name` | string | Agent 名称 |
+| `role` | string | Agent 角色描述 |
+| `provider_id` | int | LLM 提供商 ID（可选） |
+| `model` | string | 模型名称 |
+| `system_prompt` | string | 系统提示词 |
+| `color` | string | 颜色代码 |
+| `turn_order` | int | 发言顺序 |

assets/ARCHITECTURE.md

@@ -24,17 +24,21 @@ luxx/
 ├── routes/                  # API 路由层
 │   ├── __init__.py         # 路由聚合
 │   ├── auth.py             # 认证 (登录/注册)
+│   ├── agents.py          # Agent 模板管理 (CRUD)
+│   ├── chat_rooms.py      # 聊天室管理 (多 Agent 协作)
 │   ├── conversations.py    # 会话管理 (CRUD)
 │   ├── messages.py         # 消息处理 (流式/同步)
 │   ├── providers.py        # LLM 提供商管理
+│   ├── agents.py          # Agent 模板管理 (CRUD)
 │   └── tools.py            # 工具管理
 ├── services/               # 服务层
 │   ├── __init__.py        # 服务导出
 │   ├── chat.py            # 聊天服务门面
+│   ├── chat_room.py       # 多 Agent 聊天室编排器
 │   ├── agentic_loop.py    # Agentic Loop 执行器
 │   ├── stream_context.py  # 流式状态管理
+│   ├── events.py          # SSE 事件工具
 │   ├── llm_response.py     # LLM 响应数据类
-│   ├── process_result.py   # [已移除]
 │   ├── task.py            # 任务系统 (Task/TaskGraph/TaskService)
 │   ├── llm_client.py      # LLM 客户端
 │   └── llm_adapters/      # LLM API 适配器
@@ -141,6 +145,18 @@ erDiagram
         datetime created_at
     }
 
+    USER_SETTINGS {
+        int id PK
+        int user_id FK UK
+        int default_provider_id FK "optional"
+        float temperature
+        int max_tokens
+        boolean thinking_enabled
+        text system_prompt
+        datetime created_at
+        datetime updated_at
+    }
+
     PROJECT {
         string id PK
         int user_id FK
@@ -167,11 +183,15 @@ erDiagram
 
     MESSAGE {
         string id PK
-        string conversation_id FK
+        string conversation_id FK "optional"
+        string room_id FK "optional"
         string role
         longtext content "JSON 格式"
         int token_count
         text usage "JSON 格式"
+        string sender_name "聊天室: 发送者名称"
+        string sender_color "聊天室: 发送者颜色"
+        int round_number "聊天室: 轮次编号"
         datetime created_at
     }
 
@@ -190,12 +210,58 @@ erDiagram
         datetime updated_at
     }
 
+    AGENT {
+        int id PK
+        int user_id FK
+        string name
+        string role
+        int provider_id FK "optional"
+        string model
+        text system_prompt
+        string color
+        datetime created_at
+        datetime updated_at
+    }
+
+    CHAT_ROOM {
+        string id PK
+        int user_id FK
+        string title
+        text task
+        string status "idle/running/paused/completed/error"
+        int max_rounds
+        int current_round
+        datetime created_at
+        datetime updated_at
+    }
+
+    ROOM_AGENT {
+        int id PK
+        string room_id FK
+        int agent_id FK "optional"
+        string name
+        string role
+        int provider_id FK "optional"
+        string model
+        text system_prompt
+        string color
+        int turn_order
+    }
+
+    USER ||--|| USER_SETTINGS : "has"
     USER ||--o{ PROJECT : "has"
     USER ||--o{ CONVERSATION : "has"
     USER ||--o{ LLM_PROVIDER : "configures"
+    USER ||--o{ AGENT : "creates"
+    USER ||--o{ CHAT_ROOM : "creates"
     PROJECT ||--o{ CONVERSATION : "contains"
     LLM_PROVIDER ||--o{ CONVERSATION : "uses"
+    LLM_PROVIDER ||--o{ AGENT : "used_by"
+    LLM_PROVIDER ||--o{ ROOM_AGENT : "used_by"
     CONVERSATION ||--o{ MESSAGE : "has"
+    CHAT_ROOM ||--o{ MESSAGE : "has"
+    CHAT_ROOM ||--o{ ROOM_AGENT : "contains"
+    AGENT ||--o{ ROOM_AGENT : "linked_to"
 ```
 
 **用户权限级别 (permission_level)：**
@@ -591,12 +657,128 @@ classDiagram
 - Bcrypt 密码哈希
 - 用户注册/登录
 
-### 8. API 路由
+### 8. Agent 系统 (`routes/agents.py`, `models.py`)
+
+Agent 是独立的可复用 AI 助手模板，可以在聊天室中使用：
+
+```mermaid
+classDiagram
+    class Agent {
+        +int id
+        +int user_id
+        +str name
+        +str role
+        +int provider_id
+        +str model
+        +str system_prompt
+        +str color
+        +to_dict() dict
+    }
+
+    class LLMProvider {
+        +int id
+        +str name
+        +str api_key
+        +str default_model
+    }
+
+    Agent --> LLMProvider : uses
+```
+
+**Agent 字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int | Agent 唯一标识 |
+| `user_id` | int | 所属用户 ID |
+| `name` | string | Agent 显示名称 |
+| `role` | string | Agent 角色描述（如"后端开发"） |
+| `provider_id` | int | 使用的 LLM 提供商 |
+| `model` | string | 模型名称 |
+| `system_prompt` | string | 系统提示词 |
+| `color` | string | 显示颜色（Hex） |
+
+### 9. 聊天室系统 (`routes/chat_rooms.py`, `services/chat_room.py`)
+
+聊天室支持多个 Agent 同时参与讨论，协作完成复杂任务：
+
+```mermaid
+classDiagram
+    class ChatRoom {
+        +str id
+        +int user_id
+        +str title
+        +str task
+        +str status
+        +int max_rounds
+        +int current_round
+        +List~RoomAgent~ agents
+    }
+
+    class RoomAgent {
+        +int id
+        +str room_id
+        +int agent_id
+        +str name
+        +str role
+        +str model
+        +str system_prompt
+        +str color
+        +int turn_order
+    }
+
+    class ChatRoomOrchestrator {
+        -Dict~str, Task~ _running_rooms
+        +is_running(room_id) bool
+        +cancel(room_id) void
+        +run_room(room_id) AsyncGenerator
+    }
+
+    ChatRoom "1" o-- "*" RoomAgent : contains
+    ChatRoomOrchestrator ..> ChatRoom : orchestrates
+    ChatRoomOrchestrator ..> RoomAgent : executes
+```
+
+**聊天室状态：**
+
+| 状态 | 说明 |
+|------|------|
+| `idle` | 空闲，未开始 |
+| `running` | 运行中 |
+| `paused` | 已暂停（被手动停止） |
+| `completed` | 已完成（达到最大轮次） |
+| `error` | 错误（执行出错） |
+
+**聊天室执行流程：**
+
+```
+1. 用户调用 /chat-rooms/{id}/start
+2. ChatRoomOrchestrator.run_room() 被调用
+3. 按 turn_order 顺序执行每个 Agent 的发言轮次
+4. 每个 Agent 根据历史消息和系统提示生成回复
+5. SSE 流式推送消息块 (message_chunk)
+6. 消息结束时推送 message_end
+7. 一轮结束后推送 round_end
+8. 达到 max_rounds 或被停止时结束
+```
+
+**SSE 事件流：**
+
+```
+room_started → round_start → (message_start → message_chunk* → message_end → message) × N_agents
+           → round_end → (重复下一轮) → room_completed
+```
+
+### 10. API 路由
 
 | 路由 | 方法 | 说明 |
 |------|------|------|
 | `/auth/register` | POST | 用户注册 |
 | `/auth/login` | POST | 用户登录 |
+| `/auth/logout` | POST | 用户登出 |
+| `/auth/me` | GET | 当前用户信息 |
+| `/auth/users` | GET | 用户列表（管理员） |
+| `/auth/users/{user_id}` | PUT | 更新用户权限 |
 | `/conversations` | GET | 会话列表（分页） |
 | `/conversations` | POST | 创建会话 |
 | `/conversations/{id}` | GET | 会话详情 |
@@ -612,7 +794,26 @@ classDiagram
 | `/providers/{id}` | PUT | 更新提供商 |
 | `/providers/{id}` | DELETE | 删除提供商 |
 | `/providers/{id}/test` | POST | 测试提供商连接 |
+| `/agents` | GET | Agent 列表 |
+| `/agents` | POST | 创建 Agent |
+| `/agents/{id}` | GET | Agent 详情 |
+| `/agents/{id}` | PUT | 更新 Agent |
+| `/agents/{id}` | DELETE | 删除 Agent |
+| `/chat-rooms` | GET | 聊天室列表 |
+| `/chat-rooms` | POST | 创建聊天室 |
+| `/chat-rooms/{id}` | GET | 聊天室详情 |
+| `/chat-rooms/{id}` | PUT | 更新聊天室 |
+| `/chat-rooms/{id}` | DELETE | 删除聊天室 |
+| `/chat-rooms/{id}/start` | POST | 启动聊天室 |
+| `/chat-rooms/{id}/stop` | POST | 停止聊天室 |
+| `/chat-rooms/{id}/reset` | POST | 重置聊天室 |
+| `/chat-rooms/{id}/messages` | GET | 聊天室消息 |
+| `/chat-rooms/{id}/agents` | POST | 添加 Agent |
+| `/chat-rooms/{id}/agents/{agent_id}` | PUT | 更新 Agent |
+| `/chat-rooms/{id}/agents/{agent_id}` | DELETE | 移除 Agent |
 | `/tools` | GET | 可用工具列表 |
+| `/tools/{name}` | GET | 工具详情 |
+| `/tools/{name}/execute` | POST | 执行工具 |
 | `/health` | GET | 健康检查 |
 | `/` | GET | 服务信息 |
 
@@ -656,12 +857,30 @@ sequenceDiagram
 
 ## SSE 事件
 
+### 普通会话 SSE 事件
+
 | 事件 | 说明 |
 |------|------|
 | `process_step` | 结构化步骤（thinking/text/tool_call/tool_result），携带 `id`、`index` 确保渲染顺序 |
 | `done` | 响应完成，携带 message_id、token_count、usage |
 | `error` | 错误信息 |
 
+### 聊天室 SSE 事件
+
+| 事件 | 说明 |
+|------|------|
+| `room_started` | 聊天室启动，携带 room_id 和 task |
+| `round_start` | 回合开始，携带 round 和 max_rounds |
+| `message_start` | 消息开始，携带 msg_id、sender_name、sender_color、round_number |
+| `message_chunk` | 消息内容增量，携带 content 和 accumulated |
+| `message_end` | 消息结束，携带 msg_id、content、token_count |
+| `message` | 完整消息（用于存储和显示） |
+| `round_end` | 回合结束 |
+| `room_completed` | 聊天室完成 |
+| `room_paused` | 聊天室暂停 |
+| `agent_error` | Agent 执行错误 |
+| `error` | 通用错误 |
+
 ### process_step 事件格式
 
 ```json