149 lines
5.7 KiB
Markdown
149 lines
5.7 KiB
Markdown
# API v1 接入文档（多工作区 + 后台任务 + 轮询进度）
|
||
|
||
本目录面向**第三方/多端**（Web、Flutter、脚本、其它服务）对接，目标是：
|
||
|
||
- API 调用不依赖 WebSocket：网页刷新/断网/关闭不会影响后台任务运行；
|
||
- 客户端使用 **HTTP 轮询**获取与网页端一致的细粒度进度（token 输出、工具块、工具结果等）；
|
||
- API 账号与网页账号隔离：避免互相抢占任务/文件/对话状态。
|
||
- **多工作区并行**：同一个 API 用户可以创建多个 `workspace`，每个 workspace 有独立容器/项目目录/对话数据；并发限制以 workspace 为粒度（同一 workspace 禁止并发）。
|
||
|
||
## 基本信息
|
||
|
||
- API 版本：v1
|
||
- 默认后端地址（生产示例）：`https://agent.cyjai.com`
|
||
（本地开发仍可用 `http://localhost:8091`，按需替换）
|
||
- 鉴权方式：`Authorization: Bearer <token>`
|
||
- API 前缀：`/api/v1`
|
||
- 数据落盘：对话与文件落盘到 API 用户独立目录（见 `auth.md`）
|
||
- 任务与事件：**仅内存**保存（进程重启后任务/事件不可恢复）
|
||
- 默认最大迭代次数 `max_iterations`：**100**（可在调用 `/api/v1/workspaces/{workspace_id}/messages` 时覆盖）
|
||
|
||
## 接口一览（建议按 workspace 使用）
|
||
|
||
1. 工具列表：`GET /api/v1/tools`
|
||
2. 工作区管理：`GET/POST /api/v1/workspaces`、`GET/DELETE /api/v1/workspaces/{workspace_id}`
|
||
3. 对话（工作区内）：`POST/GET /api/v1/workspaces/{workspace_id}/conversations`、`GET/DELETE /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}`
|
||
4. 发送消息/启动后台任务（工作区内）：`POST /api/v1/workspaces/{workspace_id}/messages`
|
||
5. 轮询任务事件：`GET /api/v1/tasks/{task_id}?from=<offset>`
|
||
6. 停止任务：`POST /api/v1/tasks/{task_id}/cancel`
|
||
7. 文件（工作区内，仅 user_upload）：`POST /api/v1/workspaces/{workspace_id}/files/upload`、`GET /api/v1/workspaces/{workspace_id}/files`、`GET /api/v1/workspaces/{workspace_id}/files/download`
|
||
8. Prompt 管理（用户级共享）：`GET/POST /api/v1/prompts`、`GET /api/v1/prompts/{name}`
|
||
9. 个性化管理（用户级共享）：`GET/POST /api/v1/personalizations`、`GET /api/v1/personalizations/{name}`
|
||
10. 模型列表与健康检查：`GET /api/v1/models`、`GET /api/v1/health`
|
||
|
||
详细参数与返回请看：
|
||
|
||
- `auth.md`：API 用户与 Token、目录结构、安全注意事项
|
||
- `workspaces.md`：工作区概念、创建/删除/查询
|
||
- `messages_tasks.md`：发送消息/轮询/停止（工作区内发消息）
|
||
- `conversations.md`：对话列表/详情/删除（工作区内）
|
||
- `events.md`：事件流格式与事件类型说明（与 WebSocket 同源）
|
||
- `files.md`：上传/列目录/下载（工作区内）
|
||
- `tools.md`：工具分类/工具名列表返回格式
|
||
- `prompts_personalization.md`：Prompt 与个性化管理
|
||
- `errors.md`：HTTP 错误码与常见排查
|
||
- `examples.md`：curl/Python/JS/Flutter 示例
|
||
- `openapi.yaml`：OpenAPI 3.0 规范（可导入 Postman/Swagger）
|
||
|
||
## 快速开始（curl）
|
||
|
||
> 将 `<TOKEN>` 替换为你的 Bearer Token。
|
||
> 默认后端：`https://agent.cyjai.com`，本地调试请改为 `http://localhost:8091`。
|
||
|
||
### 0）创建工作区
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{ "workspace_id": "ws1" }' \
|
||
https://agent.cyjai.com/api/v1/workspaces
|
||
```
|
||
|
||
### 1）创建对话（指定工作区）
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
https://agent.cyjai.com/api/v1/workspaces/ws1/conversations
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{ "success": true, "workspace_id": "ws1", "conversation_id": "conv_20260123_234245_036" }
|
||
```
|
||
|
||
### 2）发送消息（创建后台任务，指定工作区）
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"conversation_id": "conv_20260123_234245_036",
|
||
"message": "请用中文简要介绍《明日方舟：终末地》",
|
||
"run_mode": "fast", # 可选：fast / thinking / deep
|
||
"model_key": null,
|
||
"max_iterations": 100 # 默认 100，示例显式填写便于对齐
|
||
}' \
|
||
https://agent.cyjai.com/api/v1/workspaces/ws1/messages
|
||
```
|
||
|
||
返回示例（202）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
|
||
"conversation_id": "conv_20260123_234245_036",
|
||
"workspace_id": "ws1",
|
||
"status": "running",
|
||
"created_at": 1769182965.30
|
||
}
|
||
```
|
||
|
||
### 2）轮询进度（按 offset 增量拉取）
|
||
|
||
首次从 `from=0` 开始，之后使用返回中的 `next_offset`。
|
||
|
||
```bash
|
||
curl -sS \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"https://agent.cyjai.com/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47?from=0"
|
||
```
|
||
|
||
### 3）停止任务（可选）
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
https://agent.cyjai.com/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47/cancel
|
||
```
|
||
|
||
## 统一约定：响应结构与错误处理
|
||
|
||
### 成功响应
|
||
|
||
大部分接口返回：
|
||
|
||
```json
|
||
{ "success": true, ... }
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
大部分失败返回：
|
||
|
||
```json
|
||
{ "success": false, "error": "原因说明" }
|
||
```
|
||
|
||
并使用合适的 HTTP 状态码（如 400/401/404/409/503）。
|
||
|
||
## 重要限制（务必阅读）
|
||
|
||
- **单工作区禁止并发任务**：同一个 API 用户的同一个 `workspace_id` 同一时间只允许一个 `running/pending` 任务。重复调用该 workspace 的 `/messages` 会返回 `409`；不同 workspace 之间可并行。
|
||
- **事件缓冲为内存队列（maxlen=1000）**：任务特别长或轮询太慢会导致早期事件被丢弃；请按推荐频率轮询并在客户端持久化你需要的内容。
|
||
- **进程重启不可恢复**：重启后任务/事件会消失，但对话/文件已落盘的不受影响。
|