JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
agent-Specialization/api_doc/web_api.md

5.8 KiB
Raw Permalink Blame History

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）。

响应示例

{ "success": true, "token": "xxx" }

后续请求需要：

X-CSRF-Token: <token>
Cookie: <session cookie>

3. 登录（Docker 模式）

POST /login

用途：使用邮箱 + 密码登录（Docker 模式）。

请求头

Content-Type: application/json
X-CSRF-Token: <token>

请求体

{
  "email": "jojo@local",
  "password": "******"
}

成功响应

{ "success": true }

失败响应（示例）

{ "success": false, "error": "账号或密码错误" }

4. 宿主机模式登录

GET /api/host-mode-enabled

用途：确认是否允许宿主机模式。

响应示例

{ "success": true, "enabled": true }

POST /host-login

用途：宿主机一键登录（仅当 TERMINAL_SANDBOX_MODE=host 时可用）。

请求头

X-CSRF-Token: <token>

响应示例

{ "success": true }

5. 对话管理

5.1 创建对话

POST /api/conversations

请求体（可选）

{
  "preserve_mode": false,
  "mode": "fast",
  "thinking_mode": false
}
  • preserve_mode=true 时才会使用 mode/thinking_mode；否则回到默认配置。

响应示例

{
  "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

请求体

{ "model_key": "qwen3-vl-plus" }

响应示例

{
  "success": true,
  "data": {
    "model_key": "qwen3-vl-plus",
    "run_mode": "fast",
    "thinking_mode": false
  }
}

6.2 切换思考模式

POST /api/thinking-mode

请求体（两种写法）

{ "mode": "thinking" }

或

{ "thinking_mode": true }

响应示例

{
  "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: 原始文件名（可选）

响应示例

{
  "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

请求体

{
  "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）

{
  "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

响应要点

{
  "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 字段中：

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：资源繁忙 / 宿主机模式不可用