315 lines
5.8 KiB
Markdown
315 lines
5.8 KiB
Markdown
# Web UI API 文档（非 `/api/v1`）
|
||
|
||
> 本文档描述**网页端使用的 Session/CSRF 接口**，不包含 `/api/v1`。
|
||
> 适合在**不启动前端**的情况下，用脚本/服务调用同样的网页端 API。
|
||
|
||
---
|
||
|
||
## 1. 基本信息
|
||
|
||
- 默认地址：`http://localhost:8091`
|
||
- 鉴权方式：**Session Cookie**
|
||
- CSRF：除 GET/HEAD/OPTIONS/TRACE 外，`/api/*` 需要 **`X-CSRF-Token` + Cookie**
|
||
|
||
> 说明：CSRF 由 `attach_security_hooks` 统一拦截；`/api/csrf-token` 会写入 Session 并返回 token。
|
||
|
||
---
|
||
|
||
## 2. CSRF 获取
|
||
|
||
### `GET /api/csrf-token`
|
||
|
||
**用途**：获取 CSRF Token（同时写入 Session Cookie）。
|
||
|
||
**响应示例**
|
||
```json
|
||
{ "success": true, "token": "xxx" }
|
||
```
|
||
|
||
**后续请求需要**：
|
||
```
|
||
X-CSRF-Token: <token>
|
||
Cookie: <session cookie>
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 登录（Docker 模式）
|
||
|
||
### `POST /login`
|
||
|
||
**用途**：使用邮箱 + 密码登录（Docker 模式）。
|
||
|
||
**请求头**
|
||
```
|
||
Content-Type: application/json
|
||
X-CSRF-Token: <token>
|
||
```
|
||
|
||
**请求体**
|
||
```json
|
||
{
|
||
"email": "jojo@local",
|
||
"password": "******"
|
||
}
|
||
```
|
||
|
||
**成功响应**
|
||
```json
|
||
{ "success": true }
|
||
```
|
||
|
||
**失败响应（示例）**
|
||
```json
|
||
{ "success": false, "error": "账号或密码错误" }
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 宿主机模式登录
|
||
|
||
### `GET /api/host-mode-enabled`
|
||
|
||
**用途**：确认是否允许宿主机模式。
|
||
|
||
**响应示例**
|
||
```json
|
||
{ "success": true, "enabled": true }
|
||
```
|
||
|
||
### `POST /host-login`
|
||
|
||
**用途**：宿主机一键登录（仅当 `TERMINAL_SANDBOX_MODE=host` 时可用）。
|
||
|
||
**请求头**
|
||
```
|
||
X-CSRF-Token: <token>
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{ "success": true }
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 对话管理
|
||
|
||
### 5.1 创建对话
|
||
`POST /api/conversations`
|
||
|
||
**请求体（可选）**
|
||
```json
|
||
{
|
||
"preserve_mode": false,
|
||
"mode": "fast",
|
||
"thinking_mode": false
|
||
}
|
||
```
|
||
|
||
- `preserve_mode=true` 时才会使用 `mode/thinking_mode`；否则回到默认配置。
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"conversation_id": "conv_20260315_162256_599",
|
||
"message": "已创建新对话: conv_20260315_162256_599"
|
||
}
|
||
```
|
||
|
||
### 5.2 列表查询
|
||
`GET /api/conversations?limit=20&offset=0`
|
||
|
||
### 5.3 获取对话信息
|
||
`GET /api/conversations/<conversation_id>`
|
||
|
||
### 5.4 加载/切换对话
|
||
`PUT /api/conversations/<conversation_id>/load`
|
||
|
||
### 5.5 获取对话消息
|
||
`GET /api/conversations/<conversation_id>/messages?limit=50`
|
||
|
||
### 5.6 删除对话
|
||
`DELETE /api/conversations/<conversation_id>`
|
||
|
||
---
|
||
|
||
## 6. 模型与思考模式
|
||
|
||
### 6.1 切换模型
|
||
`POST /api/model`
|
||
|
||
**请求体**
|
||
```json
|
||
{ "model_key": "qwen3-vl-plus" }
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"model_key": "qwen3-vl-plus",
|
||
"run_mode": "fast",
|
||
"thinking_mode": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 切换思考模式
|
||
`POST /api/thinking-mode`
|
||
|
||
**请求体（两种写法）**
|
||
```json
|
||
{ "mode": "thinking" }
|
||
```
|
||
或
|
||
```json
|
||
{ "thinking_mode": true }
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { "thinking_mode": true, "mode": "thinking" }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 图片/视频上传（用于多模态消息）
|
||
|
||
### 7.1 上传文件
|
||
`POST /api/upload`
|
||
|
||
**用途**：上传图片/视频，返回相对路径（通常为 `user_upload/<filename>`），之后将该路径放到 `POST /api/tasks` 的 `images` 或 `videos` 里。
|
||
|
||
**请求类型**
|
||
```
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
**表单字段**
|
||
- `file`: 文件本体
|
||
- `filename`: 原始文件名（可选）
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"path": "user_upload/1.jpg",
|
||
"filename": "1.jpg",
|
||
"folder": "user_upload",
|
||
"scan": { "status": "skipped" },
|
||
"sha256": "....",
|
||
"size": 118897
|
||
}
|
||
```
|
||
|
||
**注意事项**
|
||
- 上传功能可能被管理员策略禁用（返回 403）。
|
||
- 文件过大时返回 413（单文件大小受 `MAX_UPLOAD_SIZE` 限制）。
|
||
|
||
### 7.2 多模态模型要求
|
||
当前网页端逻辑限制：
|
||
**仅以下模型支持图片/视频**
|
||
- `qwen3-vl-plus`
|
||
- `kimi-k2.5`
|
||
|
||
在发送图片/视频前，请先 `POST /api/model` 切换到上述模型，否则会报错。
|
||
|
||
---
|
||
|
||
## 8. 发送消息（任务式 / 轮询）
|
||
|
||
### 8.1 创建任务（发送消息）
|
||
`POST /api/tasks`
|
||
|
||
**请求体**
|
||
```json
|
||
{
|
||
"message": "今天英伟达的股价是多少？",
|
||
"conversation_id": "conv_20260315_162256_599",
|
||
"images": ["user_upload/1.jpg"],
|
||
"videos": [],
|
||
"model_key": null,
|
||
"thinking_mode": null,
|
||
"run_mode": null,
|
||
"max_iterations": 100
|
||
}
|
||
```
|
||
|
||
**响应示例（202）**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"task_id": "5aae14a2-cd12-4644-b5eb-c394b83f4045",
|
||
"status": "running",
|
||
"created_at": 1773562976.607287,
|
||
"conversation_id": "conv_20260315_162256_599"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 轮询任务事件
|
||
`GET /api/tasks/<task_id>?from=0`
|
||
|
||
**响应要点**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"status": "succeeded",
|
||
"events": [
|
||
{ "type": "text_chunk", "data": { "content": "..." } },
|
||
{ "type": "text_end", "data": { "full_content": "..." } }
|
||
],
|
||
"next_offset": 437
|
||
}
|
||
}
|
||
```
|
||
|
||
> `text_end.data.full_content` 是最终整段回复；`next_offset` 用于增量轮询。
|
||
|
||
### 8.3 查询任务列表
|
||
`GET /api/tasks`
|
||
|
||
### 8.4 取消任务
|
||
`POST /api/tasks/<task_id>/cancel`
|
||
|
||
---
|
||
|
||
## 9. 可选：WebSocket Token（如果需要实时推送）
|
||
|
||
### `GET /api/socket-token`
|
||
|
||
返回 `{ success: true, token: "...", expires_at: ... }`
|
||
Socket.IO 连接时将 token 放到 `auth` 字段中：
|
||
|
||
```js
|
||
io('/', { auth: { socket_token: '<token>' } })
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 最小调用流程（示例）
|
||
|
||
1) `GET /api/csrf-token`
|
||
2) `POST /login`（或 `POST /host-login`）
|
||
3) `GET /api/csrf-token`（刷新 token）
|
||
4) `POST /api/conversations`
|
||
5) `POST /api/tasks`
|
||
6) `GET /api/tasks/<task_id>?from=0` 轮询直到 `status=succeeded`
|
||
|
||
---
|
||
|
||
## 11. 常见错误码
|
||
|
||
- `401 Unauthorized`：未登录或 Session 失效
|
||
- `403 CSRF validation failed`：缺少/错误的 `X-CSRF-Token`
|
||
- `409`：同一用户同一工作区已有运行中任务（任务互斥）
|
||
- `503`：资源繁忙 / 宿主机模式不可用
|