# 事件流说明（轮询返回 events）

`GET /api/v1/tasks/<task_id>` 返回的 `events` 字段，是一个按时间顺序（`idx` 递增）的**事件流**。

本项目的目标是：**与网页端 WebSocket 事件保持同一粒度**。因此你会看到：

- token 级别的 `text_chunk`/`thinking_chunk`
- 工具调用生命周期事件（准备/意图/开始/状态更新）
- 工具执行结果的状态更新与系统消息

> 提示：客户端应只依赖 `type` 字符串与 `data` 字段，并对未知事件类型保持兼容（忽略或记录）。

## 1. 事件统一包裹格式（envelope）

每个事件的结构：

```json
{
  "idx": 12,
  "type": "text_chunk",
  "data": { "content": "你好", "index": 5, "elapsed": 0.003 },
  "ts": 1769182968.154797
}
```

字段含义：

- `idx`：事件序号（从 0 开始递增），用于轮询 offset 与去重
- `type`：事件类型（字符串）
- `data`：事件载荷（不同 type 不同结构）
- `ts`：服务端记录的 UNIX 时间戳（秒，float）

## 2. offset 与去重

轮询接口支持 `from` 参数：

- `GET /api/v1/tasks/<task_id>?from=0`：从头拉取
- `GET /api/v1/tasks/<task_id>?from=next_offset`：增量拉取

正确做法：

1. 客户端本地保存 `offset`（初始 0）
2. 轮询请求带上 `from=offset`
3. 处理返回 `events`
4. 将 `offset` 更新为返回的 `next_offset`

## 3. 常见事件类型与载荷

以下为**常见**事件类型（实际可能随版本增加更多 type）。

### 3.1 AI 消息生命周期

#### `ai_message_start`

AI 新一轮回复开始（一次用户消息可能触发多次迭代，但 UI 通常以此作为“助手消息开始”的信号）。

```json
{ "type": "ai_message_start", "data": {} }
```

### 3.2 思考（reasoning）

#### `thinking_start`

```json
{ "type": "thinking_start", "data": {} }
```

#### `thinking_chunk`

逐段思考内容（细粒度流式）。

```json
{ "type": "thinking_chunk", "data": { "content": "..." } }
```

#### `thinking_end`

思考结束（带完整思考文本）。

```json
{ "type": "thinking_end", "data": { "full_content": "..." } }
```

建议客户端处理方式：

- 若你想还原“实时思考流”，就持续 append `thinking_chunk.data.content`；
- 若你只想最终值，可忽略 chunk，只在 `thinking_end` 读取 `full_content`。

### 3.3 正文输出（token 级）

#### `text_start`

```json
{ "type": "text_start", "data": {} }
```

#### `text_chunk`

逐 token/子串输出。字段：

- `content`：本次增量内容
- `index`：从 1 开始的 chunk 序号（仅用于调试/对齐）
- `elapsed`：与上一 chunk 的时间间隔（秒）

```json
{
  "type": "text_chunk",
  "data": { "content": "你好", "index": 5, "elapsed": 0.003 }
}
```

#### `text_end`

正文结束，包含 `full_content`（完整文本）。

```json
{ "type": "text_end", "data": { "full_content": "..." } }
```

建议客户端处理方式：

- 实时显示：append `text_chunk.data.content`
- 最终落盘：以 `text_end.data.full_content` 为准（如果你做了实时 append，最终可用 full_content 校验/纠偏）

> 注意：若模型在工具调用后没有再次输出总结文本，则可能出现“最后一轮事件是工具相关，没有 text_end”的情况；这属于模型行为/迭代次数限制导致，并不代表任务异常。

### 3.4 工具调用（tool）相关

工具链路通常会出现如下事件：

1) `tool_hint`（可选，提前猜测意图）  
2) `tool_preparing`（模型开始输出 tool_calls 时）  
3) `tool_intent`（从增量 arguments 中抽取 intent 字段）  
4) `tool_start`（真正执行工具时）  
5) `update_action`（执行进度与结果状态更新）  

#### `tool_hint`（可选）

```json
{
  "type": "tool_hint",
  "data": {
    "id": "early_web_search_...",
    "name": "web_search",
    "message": "检测到可能需要调用 web_search...",
    "confidence": "low",
    "conversation_id": "conv_..."
  }
}
```

#### `tool_preparing`

```json
{
  "type": "tool_preparing",
  "data": {
    "id": "web_search:0",
    "name": "web_search",
    "message": "准备调用 web_search...",
    "intent": "搜索明日方舟终末地游戏信息",
    "conversation_id": "conv_..."
  }
}
```

#### `tool_intent`

```json
{
  "type": "tool_intent",
  "data": {
    "id": "web_search:0",
    "name": "web_search",
    "intent": "搜索明日方舟终末地游戏信息",
    "conversation_id": "conv_..."
  }
}
```

#### `tool_start`

```json
{
  "type": "tool_start",
  "data": {
    "id": "tool_0_web_search_...",
    "name": "web_search",
    "arguments": { "...": "..." },
    "preparing_id": "web_search:0",
    "monitor_snapshot": null,
    "conversation_id": "conv_..."
  }
}
```

说明：

- `preparing_id` 用于把“模型输出的 tool_call”与“真实执行的工具卡片”关联起来
- `arguments` 为工具参数（通常是 JSON 对象）

#### `update_action`

该事件用于更新工具卡片（或其他 action）的状态。字段随工具不同可能略有差异，但通常包含：

- `id`：与 `tool_start.data.id` 对应
- `status`：`running/completed/failed/...`
- `message`：可读描述
- 可能还带 `result/summary/monitor_snapshot/...`

客户端建议：

- 把 `update_action` 当作通用的“状态更新”事件处理；
- 对未知字段保持兼容（直接展示或忽略）。

### 3.5 系统消息与错误

#### `system_message`

```json
{ "type": "system_message", "data": { "content": "..." } }
```

#### `error`

任务内错误（不同于 HTTP 层错误）。出现后通常任务会进入 `failed`。

```json
{ "type": "error", "data": { "message": "..." } }
```

### 3.6 任务结束

#### `task_complete`

```json
{
  "type": "task_complete",
  "data": {
    "total_iterations": 2,
    "total_tool_calls": 1,
    "auto_fix_attempts": 0
  }
}
```

> 结束条件以轮询返回的 `status != running` 为准；`task_complete` 是一个“完成事件”，但客户端仍应读取 `status`。

## 4. 事件缓冲与性能建议

- 服务端每个任务保存最近 **1000** 条事件（队列会丢弃更早的数据）
- 建议轮询间隔 `0.5s ~ 2s`
- 长任务建议客户端把 `text_chunk` 与关键工具事件持久化到本地，避免错过