ViperEkura
/
Luxx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 更新文档

This commit is contained in:
ViperEkura 2026-04-25 20:42:57 +08:00
parent 6f7da3fbaf
commit ef78196b8c
2 changed files with 683 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

461
assets/API.md
View File

@ -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 | 发言顺序 |

225
assets/ARCHITECTURE.md
View File

@ -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