# 发送消息与任务系统（后台运行 + 轮询）

本节覆盖：

- 创建对话（可选）：`POST /api/v1/conversations`
- 发送消息（创建后台任务）：`POST /api/v1/messages`
- 轮询事件：`GET /api/v1/tasks/<task_id>`
- 停止任务：`POST /api/v1/tasks/<task_id>/cancel`

## 1) 创建对话

### POST `/api/v1/conversations`

创建一个新的对话，并返回 `conversation_id`。

请求：

- Headers：`Authorization: Bearer <TOKEN>`
- Body：无

响应（200）：

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

可能错误：

- `401`：缺少或无效 token
- `503`：系统未初始化（资源繁忙/容器不可用等）
- `500`：创建失败

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

### POST `/api/v1/messages`

创建一个后台任务执行智能体流程，并立即返回 `task_id`。

#### 请求

Headers：

- `Authorization: Bearer <TOKEN>`
- `Content-Type: application/json`

Body(JSON)：

| 字段 | 类型 | 必填 | 说明 |
|---|---:|---:|---|
| `message` | string | 是（或 images） | 用户消息文本；`message` 与 `images` 至少其一不为空 |
| `conversation_id` | string | 否 | 不传则自动新建对话；建议显式传入以便客户端管理会话 |
| `model_key` | string/null | 否 | 指定模型 key（可选）；具体可用值取决于服务端配置 |
| `run_mode` | string/null | 否 | 运行模式：`"fast"` \| `"thinking"` \| `"deep"`；若传入则优先使用 |
| `thinking_mode` | boolean/null | 否 | 兼容字段：true=thinking，false=fast；当 `run_mode` 为空时才使用 |
| `max_iterations` | integer/null | 否 | 最大迭代次数，默认服务端配置为 **100**（`config.MAX_ITERATIONS_PER_TASK`）；传入可覆盖 | 
| `images` | string[] | 否 | 图片路径列表（服务端可访问的路径）；一般配合特定模型使用 |

优先级：`run_mode` > `thinking_mode` > 终端当前配置。`run_mode="deep"` 将启用深度思考模式（若模型与配置允许）。

#### 响应

成功（202）：

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

字段说明：

- `task_id`：任务唯一 ID（用于轮询/停止）
- `conversation_id`：本次任务归属对话
- `status`：初始为 `running`
- `created_at`：UNIX 时间戳（秒，float）

可能错误：

- `400`：`message/images` 都为空；或 `conversation_id` 无法加载
- `401`：缺少或无效 token
- `409`：该 API 用户已有运行中的任务（禁止并发）
- `503`：系统未初始化/资源繁忙

并发冲突示例（409）：

```json
{ "success": false, "error": "已有运行中的任务，请稍后再试。" }
```

## 3) 轮询任务事件（增量）

### GET `/api/v1/tasks/<task_id>?from=<offset>`

用于以 **HTTP 轮询**方式获取任务执行过程中的流式事件（与 WebSocket 同粒度）。

#### 请求

- Headers：`Authorization: Bearer <TOKEN>`
- Query：
  - `from`：起始 offset（默认 0）

#### 响应（200）

```json
{
  "success": true,
  "data": {
    "task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
    "status": "running",
    "created_at": 1769182965.30,
    "updated_at": 1769182968.15,
    "error": null,
    "events": [
      { "idx": 0, "type": "ai_message_start", "data": {}, "ts": 1769182965.30 },
      { "idx": 1, "type": "text_start", "data": {}, "ts": 1769182968.09 },
      { "idx": 2, "type": "text_chunk", "data": { "content": "我来", "index": 1, "elapsed": 0.0 }, "ts": 1769182968.15 }
    ],
    "next_offset": 3
  }
}
```

字段说明：

- `status`：任务状态，常见值：
  - `running`：执行中
  - `cancel_requested`：已请求停止，等待实际停下
  - `canceled`：已停止
  - `succeeded`：成功结束
  - `failed`：失败结束（`error` 会给出原因）
- `events`：从 `idx>=from` 的事件列表（按 idx 升序）
- `next_offset`：建议下一次轮询的 `from` 值

可能错误：

- `401`：缺少或无效 token
- `404`：任务不存在（或不属于该 API 用户）

#### 推荐轮询策略

- 轮询间隔：`0.5s ~ 2s`（任务越密集越推荐更快）
- 客户端必须：
  1) 保存 `next_offset`
  2) 追加处理 events
  3) 当 `status != running` 时停止轮询

> 重要：服务端事件缓冲是 `deque(maxlen=1000)`，轮询过慢会丢失早期事件；客户端应自行落盘你需要的内容。

## 4) 停止任务

### POST `/api/v1/tasks/<task_id>/cancel`

请求停止某个任务。

请求：

- Headers：`Authorization: Bearer <TOKEN>`
- Body：无

成功（200）：

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

说明：

- 该接口是“请求停止”，任务可能不会立刻停下；
- 停止后的最终状态在轮询里体现：`status` 变为 `canceled` 或 `failed/succeeded`（极少数情况下已接近结束）。

可能错误：

- `401`：缺少或无效 token
- `404`：任务不存在