1115 lines
21 KiB
Markdown
1115 lines
21 KiB
Markdown
# API 接口文档
|
||
|
||
## 认证 `/api/auth`
|
||
|
||
### POST /api/auth/register
|
||
用户注册
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"email": "user@example.com",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Registration successful",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/auth/login
|
||
用户登录
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Login successful",
|
||
"data": {
|
||
"access_token": "eyJ...",
|
||
"token_type": "bearer",
|
||
"user": {
|
||
"id": 1,
|
||
"username": "string",
|
||
"email": "user@example.com",
|
||
"role": "user",
|
||
"permission_level": 1,
|
||
"workspace_path": null,
|
||
"is_active": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**用户权限级别：**
|
||
| 级别 | 名称 | 说明 |
|
||
|------|------|------|
|
||
| 1 | READ_ONLY | 只读权限 |
|
||
| 2 | WRITE | 写入权限 |
|
||
| 3 | EXECUTE | 执行权限 |
|
||
| 4 | ADMIN | 管理员权限 |
|
||
|
||
### POST /api/auth/logout
|
||
用户登出
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Logout successful"
|
||
}
|
||
```
|
||
|
||
### GET /api/auth/me
|
||
获取当前用户信息
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 1,
|
||
"username": "string",
|
||
"email": "user@example.com",
|
||
"role": "user",
|
||
"permission_level": 1,
|
||
"workspace_path": null,
|
||
"is_active": true,
|
||
"created_at": "2024-01-01T00:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### GET /api/auth/users
|
||
获取所有用户（管理员专用）
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"users": [...]
|
||
}
|
||
}
|
||
```
|
||
|
||
### PUT /api/auth/users/{user_id}
|
||
更新用户权限（管理员专用）
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"permission_level": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 会话 `/api/conversations`
|
||
|
||
### GET /api/conversations/
|
||
获取会话列表
|
||
|
||
**查询参数：**
|
||
- `project_id` (可选): 项目ID
|
||
- `page` (可选): 页码，默认1
|
||
- `page_size` (可选): 每页数量，默认20
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/conversations/
|
||
创建会话
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"project_id": "string (可选)",
|
||
"title": "新会话",
|
||
"model": "deepseek-chat",
|
||
"provider_id": 1,
|
||
"system_prompt": "You are a helpful assistant. (可选)",
|
||
"temperature": 0.7,
|
||
"max_tokens": 2000,
|
||
"thinking_enabled": false
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "会话创建成功",
|
||
"data": {
|
||
"id": "conv_xxx",
|
||
"user_id": 1,
|
||
"provider_id": 1,
|
||
"title": "新会话",
|
||
"model": "deepseek-chat",
|
||
"system_prompt": "You are a helpful assistant.",
|
||
"temperature": 0.7,
|
||
"max_tokens": 2000,
|
||
"thinking_enabled": false,
|
||
"created_at": "2024-01-01T00:00:00",
|
||
"updated_at": "2024-01-01T00:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### GET /api/conversations/{id}
|
||
获取会话详情
|
||
|
||
**路径参数：** `id`: 会话ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
### PUT /api/conversations/{id}
|
||
更新会话
|
||
|
||
**路径参数：** `id`: 会话ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"title": "新标题",
|
||
"model": "gpt-4",
|
||
"provider_id": 1,
|
||
"system_prompt": "You are...",
|
||
"temperature": 0.8,
|
||
"max_tokens": 4000,
|
||
"thinking_enabled": true
|
||
}
|
||
```
|
||
|
||
### DELETE /api/conversations/{id}
|
||
删除会话
|
||
|
||
**路径参数：** `id`: 会话ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
---
|
||
|
||
## 消息 `/api/messages`
|
||
|
||
### GET /api/messages/
|
||
获取消息列表
|
||
|
||
**查询参数：**
|
||
- `conversation_id`: 会话ID（必需）
|
||
- `limit` (可选): 返回数量，默认100
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"messages": [
|
||
{
|
||
"id": "msg_xxx",
|
||
"conversation_id": "conv_xxx",
|
||
"role": "user",
|
||
"content": "用户消息",
|
||
"text": "用户消息",
|
||
"attachments": [],
|
||
"process_steps": [],
|
||
"token_count": 10,
|
||
"usage": null,
|
||
"created_at": "2024-01-01T00:00:00"
|
||
},
|
||
{
|
||
"id": "msg_yyy",
|
||
"conversation_id": "conv_xxx",
|
||
"role": "assistant",
|
||
"content": "AI 回复文本内容",
|
||
"text": "AI 回复文本内容",
|
||
"attachments": [],
|
||
"process_steps": [
|
||
{"id": "step-0", "index": 0, "type": "thinking", "content": "让我思考..."},
|
||
{"id": "step-1", "index": 1, "type": "text", "content": "根据搜索结果..."},
|
||
{"id": "step-2", "index": 2, "type": "tool_call", "id_ref": "call_xxx", "name": "web_search", "arguments": "..."},
|
||
{"id": "step-3", "index": 3, "type": "tool_result", "id_ref": "call_xxx", "name": "web_search", "content": "...", "success": true}
|
||
],
|
||
"token_count": 100,
|
||
"usage": {"prompt_tokens": 50, "completion_tokens": 50, "total_tokens": 100},
|
||
"created_at": "2024-01-01T00:00:01"
|
||
}
|
||
],
|
||
"title": "会话标题",
|
||
"first_message": "用户的第一条消息..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/messages/
|
||
发送消息（非流式）
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"conversation_id": "conv_xxx",
|
||
"content": "用户消息",
|
||
"thinking_enabled": false
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user_message": {...},
|
||
"assistant_message": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/messages/stream
|
||
发送消息（流式响应 - SSE）
|
||
|
||
使用 Server-Sent Events (SSE) 返回流式响应。
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"conversation_id": "conv_xxx",
|
||
"content": "用户消息",
|
||
"thinking_enabled": true,
|
||
"enabled_tools": ["web_search", "file_read", "python_execute"]
|
||
}
|
||
```
|
||
|
||
**SSE 事件类型：**
|
||
|
||
#### process_step
|
||
结构化步骤事件（渲染顺序的唯一数据源）
|
||
|
||
```json
|
||
event: process_step
|
||
data: {"step": {"id": "step-0", "index": 0, "type": "thinking", "content": "让我思考一下..."}}
|
||
|
||
event: process_step
|
||
data: {"step": {"id": "step-1", "index": 1, "type": "text", "content": "以下是搜索结果："}}
|
||
|
||
event: process_step
|
||
data: {"step": {"id": "step-2", "index": 2, "type": "tool_call", "id_ref": "call_abc", "name": "web_search", "arguments": "{\"query\": \"...\"}"}}
|
||
|
||
event: process_step
|
||
data: {"step": {"id": "step-3", "index": 3, "type": "tool_result", "id_ref": "call_abc", "name": "web_search", "content": "{...}", "success": true}}
|
||
```
|
||
|
||
**步骤类型说明：**
|
||
|
||
| type | 说明 | 额外字段 |
|
||
|------|------|---------|
|
||
| `thinking` | 模型思考过程 | `content` |
|
||
| `text` | 文本回复 | `content` |
|
||
| `tool_call` | 工具调用 | `id_ref`, `name`, `arguments` |
|
||
| `tool_result` | 工具执行结果 | `id_ref`, `name`, `content`, `success` |
|
||
|
||
#### done
|
||
响应完成
|
||
|
||
```json
|
||
event: done
|
||
data: {"message_id": "msg_xxx", "token_count": 150, "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150}}
|
||
```
|
||
|
||
#### error
|
||
错误信息
|
||
|
||
```json
|
||
event: error
|
||
data: {"content": "错误信息描述"}
|
||
```
|
||
|
||
### DELETE /api/messages/{message_id}
|
||
删除消息
|
||
|
||
**路径参数：** `message_id`: 消息ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
---
|
||
|
||
## LLM 提供商 `/api/providers`
|
||
|
||
### GET /api/providers/
|
||
获取用户的 LLM 提供商列表
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"providers": [
|
||
{
|
||
"id": 1,
|
||
"user_id": 1,
|
||
"name": "DeepSeek",
|
||
"provider_type": "openai",
|
||
"base_url": "https://api.deepseek.com/v1",
|
||
"default_model": "deepseek-chat",
|
||
"max_tokens": 8192,
|
||
"is_default": true,
|
||
"enabled": true,
|
||
"created_at": "2024-01-01T00:00:00",
|
||
"updated_at": "2024-01-01T00:00:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/providers/
|
||
创建 LLM 提供商
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"name": "DeepSeek",
|
||
"provider_type": "openai",
|
||
"base_url": "https://api.deepseek.com/v1",
|
||
"api_key": "sk-xxxx",
|
||
"default_model": "deepseek-chat",
|
||
"is_default": true
|
||
}
|
||
```
|
||
|
||
**provider_type 可选值：**
|
||
- `openai` - OpenAI/DeepSeek/GLM 兼容 API
|
||
- `anthropic` - Anthropic Claude API
|
||
|
||
### GET /api/providers/{provider_id}
|
||
获取提供商详情
|
||
|
||
**路径参数：** `provider_id`: 提供商ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
### PUT /api/providers/{provider_id}
|
||
更新提供商
|
||
|
||
**路径参数：** `provider_id`: 提供商ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"name": "新名称",
|
||
"base_url": "https://api.example.com/v1",
|
||
"api_key": "sk-yyyy",
|
||
"default_model": "gpt-4",
|
||
"max_tokens": 16384,
|
||
"is_default": false,
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
### DELETE /api/providers/{provider_id}
|
||
删除提供商
|
||
|
||
**路径参数：** `provider_id`: 提供商ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
### POST /api/providers/{provider_id}/test
|
||
测试提供商连接
|
||
|
||
**路径参数：** `provider_id`: 提供商ID
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "HTTP 200: ...",
|
||
"data": {
|
||
"status_code": 200,
|
||
"success": true,
|
||
"response_body": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 工具 `/api/tools`
|
||
|
||
### GET /api/tools/
|
||
获取可用工具列表
|
||
|
||
**查询参数：**
|
||
- `category` (可选): 工具分类（code/file/shell/crawler/data）
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"tools": [
|
||
{
|
||
"name": "python_execute",
|
||
"description": "Execute Python code",
|
||
"category": "code",
|
||
"parameters": {...}
|
||
},
|
||
...
|
||
],
|
||
"categorized": {
|
||
"code": [...],
|
||
"file": [...],
|
||
"shell": [...],
|
||
"crawler": [...],
|
||
"data": [...]
|
||
},
|
||
"total": 11
|
||
}
|
||
}
|
||
```
|
||
|
||
### GET /api/tools/{name}
|
||
获取工具详情
|
||
|
||
**路径参数：** `name`: 工具名称
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "web_search",
|
||
"description": "Search the web using DuckDuckGo",
|
||
"category": "crawler",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"query": {
|
||
"type": "string",
|
||
"description": "Search query"
|
||
}
|
||
},
|
||
"required": ["query"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### POST /api/tools/{name}/execute
|
||
手动执行工具
|
||
|
||
**路径参数：** `name`: 工具名称
|
||
|
||
**请求头：** `Authorization: Bearer <token>`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"arg1": "value1",
|
||
"arg2": "value2"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"result": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 公共端点
|
||
|
||
### GET /api/health
|
||
健康检查
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"message": "Luxx API is running"
|
||
}
|
||
```
|
||
|
||
### GET /api/
|
||
服务信息
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"name": "Luxx",
|
||
"version": "1.0.0",
|
||
"description": "AI Chat API"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 工具说明
|
||
|
||
### 内置工具
|
||
|
||
#### 代码执行 (code)
|
||
| 工具 | 功能 | 权限 |
|
||
|------|------|------|
|
||
| `python_execute` | 执行 Python 代码 | EXECUTE |
|
||
| `python_eval` | 计算表达式 | EXECUTE |
|
||
|
||
#### 文件操作 (file)
|
||
| 工具 | 功能 | 权限 |
|
||
|------|------|------|
|
||
| `file_read` | 读取文件内容 | READ_ONLY |
|
||
| `file_write` | 写入文件内容 | WRITE |
|
||
| `file_list` | 列出目录内容 | READ_ONLY |
|
||
| `file_exists` | 检查文件是否存在 | READ_ONLY |
|
||
| `file_grep` | 正则搜索文件 | READ_ONLY |
|
||
|
||
#### Shell 命令 (shell)
|
||
| 工具 | 功能 | 权限 |
|
||
|------|------|------|
|
||
| `shell_execute` | 执行 Shell 命令 | EXECUTE |
|
||
|
||
#### 网页爬虫 (crawler)
|
||
| 工具 | 功能 | 权限 |
|
||
|------|------|------|
|
||
| `web_search` | DuckDuckGo 搜索 | READ_ONLY |
|
||
| `web_fetch` | 网页抓取 | READ_ONLY |
|
||
| `batch_fetch` | 批量并发抓取 | READ_ONLY |
|
||
|
||
#### 数据处理 (data)
|
||
| 工具 | 功能 | 权限 |
|
||
|------|------|------|
|
||
| `process_data` | JSON 转换、格式化 | READ_ONLY |
|
||
|
||
### 权限检查
|
||
|
||
工具执行时自动检查用户权限：
|
||
|
||
```
|
||
工具要求的权限 <= 用户拥有的权限 → 允许执行
|
||
工具要求的权限 > 用户拥有的权限 → 返回错误
|
||
```
|
||
|
||
用户通过 `/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 | 发言顺序 |
|