diff --git a/assets/API.md b/assets/API.md index 24aec97..d2b7b77 100644 --- a/assets/API.md +++ b/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 ` + +**响应：** +```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 ` + +**请求体：** +```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 ` + +### PUT /api/agents/{agent_id} +更新 Agent + +**路径参数：** `agent_id`: Agent ID + +**请求头：** `Authorization: Bearer ` + +**请求体：** +```json +{ + "name": "新名称", + "role": "新的角色描述", + "system_prompt": "新的系统提示...", + "color": "#ff6b6b" +} +``` + +### DELETE /api/agents/{agent_id} +删除 Agent + +**路径参数：** `agent_id`: Agent ID + +**请求头：** `Authorization: Bearer ` + +--- + +## 聊天室 `/api/chat-rooms` + +聊天室允许多个 Agent 同时参与讨论，协作完成复杂任务。 + +### GET /api/chat-rooms/ +获取聊天室列表 + +**查询参数：** +- `page` (可选): 页码，默认1 +- `page_size` (可选): 每页数量，默认20 + +**请求头：** `Authorization: Bearer ` + +**响应：** +```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 ` + +**请求体：** +```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 ` + +**响应：** +```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 ` + +**请求体：** +```json +{ + "title": "新标题", + "task": "新的任务描述", + "max_rounds": 10, + "status": "idle" +} +``` + +### DELETE /api/chat-rooms/{room_id} +删除聊天室 + +**路径参数：** `room_id`: 聊天室 ID + +**请求头：** `Authorization: Bearer ` + +### POST /api/chat-rooms/{room_id}/start +启动聊天室（流式响应 - SSE） + +**路径参数：** `room_id`: 聊天室 ID + +**请求头：** `Authorization: Bearer ` + +**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 ` + +### POST /api/chat-rooms/{room_id}/reset +重置聊天室（清除所有消息） + +**路径参数：** `room_id`: 聊天室 ID + +**请求头：** `Authorization: Bearer ` + +### GET /api/chat-rooms/{room_id}/messages +获取聊天室消息 + +**路径参数：** `room_id`: 聊天室 ID + +**请求头：** `Authorization: Bearer ` + +**响应：** +```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 ` + +**请求体：** +```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 ` + +**请求体：** +```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 ` + +--- + +## 聊天室状态 + +| 状态 | 说明 | +|------|------| +| `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 | 发言顺序 | diff --git a/assets/ARCHITECTURE.md b/assets/ARCHITECTURE.md index ba55a5b..34586f3 100644 --- a/assets/ARCHITECTURE.md +++ b/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