# API v1 接入文档（后台任务 + 轮询进度 + 文件）

本目录面向**第三方/多端**（Web、Flutter、脚本、其它服务）对接，目标是：

- API 调用不依赖 WebSocket：网页刷新/断网/关闭不会影响后台任务运行；
- 客户端使用 **HTTP 轮询**获取与网页端一致的细粒度进度（token 输出、工具块、工具结果等）；
- API 账号与网页账号隔离：避免互相抢占任务/文件/对话状态。

## 基本信息

- API 版本：v1
- 默认后端地址（本地）：`http://localhost:8091`
- 鉴权方式：`Authorization: Bearer <token>`
- API 前缀：`/api/v1`
- 数据落盘：对话与文件落盘到 API 用户独立目录（见 `auth.md`）
- 任务与事件：**仅内存**保存（进程重启后任务/事件不可恢复）
- 默认最大迭代次数 `max_iterations`：**100**（可在调用 `/api/v1/messages` 时覆盖）

## 只保留的接口（共 6 组能力）

1. 创建对话：`POST /api/v1/conversations`
2. 发送消息/启动后台任务：`POST /api/v1/messages`
3. 轮询任务事件：`GET /api/v1/tasks/<task_id>?from=<offset>`
4. 停止任务：`POST /api/v1/tasks/<task_id>/cancel`
5. 文件上传（仅 user_upload）：`POST /api/v1/files/upload`
6. 文件浏览/下载：`GET /api/v1/files`、`GET /api/v1/files/download`

详细参数与返回请看：

- `auth.md`：API 用户与 Token、目录结构、安全注意事项
- `messages_tasks.md`：发送消息/轮询/停止
- `events.md`：事件流格式与事件类型说明（与 WebSocket 同源）
- `files.md`：上传/列目录/下载
- `errors.md`：HTTP 错误码与常见排查
- `examples.md`：curl/Python/JS/Flutter 示例
- `openapi.yaml`：OpenAPI 3.0 规范（可导入 Postman/Swagger）

## 快速开始（curl）

> 将 `<TOKEN>` 替换为你的 Bearer Token。  
> 默认后端：`http://localhost:8091`，如不同请修改。

### 0）创建对话

```bash
curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  http://localhost:8091/api/v1/conversations
```

返回示例：

```json
{ "success": true, "conversation_id": "conv_20260123_234245_036" }
```

### 1）发送消息（创建后台任务）

```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，示例显式填写便于对齐
  }' \
  http://localhost:8091/api/v1/messages
```

返回示例（202）：

```json
{
  "success": true,
  "task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
  "conversation_id": "conv_20260123_234245_036",
  "status": "running",
  "created_at": 1769182965.30
}
```

### 2）轮询进度（按 offset 增量拉取）

首次从 `from=0` 开始，之后使用返回中的 `next_offset`。

```bash
curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47?from=0"
```

### 3）停止任务（可选）

```bash
curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  http://localhost:8091/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47/cancel
```

## 统一约定：响应结构与错误处理

### 成功响应

大部分接口返回：

```json
{ "success": true, ... }
```

### 失败响应

大部分失败返回：

```json
{ "success": false, "error": "原因说明" }
```

并使用合适的 HTTP 状态码（如 400/401/404/409/503）。

## 重要限制（务必阅读）

- **单用户禁止并发任务**：同一个 API 用户同一时间只允许一个 `running/pending` 任务。重复发送消息会返回 `409`。
- **事件缓冲为内存队列（maxlen=1000）**：任务特别长或轮询太慢会导致早期事件被丢弃；请按推荐频率轮询并在客户端持久化你需要的内容。
- **进程重启不可恢复**：重启后任务/事件会消失，但对话/文件已落盘的不受影响。