> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 对话 API：WebSocket 流式传输与线程管理

通过 WebSocket 与专家对话，实时流式接收回复，并管理对话线程。

## WebSocket 端点

```text
WS /api/agents/{id}/chat/ws?token=<jwt>
```

由于浏览器 WebSocket API 不支持自定义头，令牌需作为查询参数传递，而不是 `Authorization` 头。

## 消息帧

向专家发送一轮对话：

```json
{"type": "user_turn", "content": "你好！", "thread_id": "abc123"}
```

服务器以流式块回应：

```json
{"type": "chunk", "content": "你好！我能"}
```

回复完成时发送：

```json
{"type": "done"}
```

若发生错误：

```json
{"type": "error", "message": "模型请求超时"}
```

为保持连接存活，可发送 ping/pong 帧：

```json
{"type": "ping"}
```

```json
{"type": "pong"}
```

断线本身**不会**取消正在进行的回合。重连后发送 `subscribe` 可挂接到仍在流式输出的线程；服务器以 `turn_status` 回应：

```json
{"type": "subscribe", "thread_id": "abc123"}
```

```json
{"type": "turn_status", "thread_id": "abc123", "active": true}
```

显式停止当前回合：

```json
{"type": "cancel", "thread_id": "abc123"}
```


> **说明**
> 
> `thread_id` 在整个对话中保持不变。若需在断开后恢复会话，请使用创建线程时返回的 `session_key`。页面刷新后先拉 history，根据 `turn_active` 再决定是否 `subscribe`。
> 


## 线程管理

| 方法     | 路径                                                              | 描述                                                           |
| ------ | --------------------------------------------------------------- | ------------------------------------------------------------ |
| GET    | `/agents/{id}/threads`                                          | 列出对话线程                                                       |
| POST   | `/agents/{id}/threads`                                          | 创建新线程                                                        |
| PATCH  | `/agents/{id}/threads/{thread_id}`                              | 重命名或固定线程                                                     |
| DELETE | `/agents/{id}/threads/{thread_id}`                              | 删除线程                                                         |
| GET    | `/agents/{id}/threads/{thread_id}/history`                      | 获取线程历史记录（含 `turn_active`）                                    |
| GET    | `/agents/{id}/history-migration/status`                         | 查看仍需历史投影的旧对话                                                 |
| POST   | `/agents/{id}/history-migration/start`                          | 后台排队处理旧对话历史投影                                                |
| GET    | `/agents/{id}/threads/{thread_id}/context-usage`                | 按片段返回上下文窗口占用                                                 |
| POST   | `/agents/{id}/threads/{thread_id}/read`                         | 将线程标记为已读                                                     |
| POST   | `/agents/{id}/threads/{thread_id}/fork`                         | 从某条专家回复分叉线程                                                  |
| GET    | `/agents/{id}/threads/{thread_id}/trajectory`                   | 分页运行轨迹摘要，用 `before_seq` 取更早记录                                |
| GET    | `/agents/{id}/threads/{thread_id}/trajectory/events/{event_id}` | 单条事件完整载荷                                                     |
| GET    | `/agents/{id}/threads/{thread_id}/trajectory/metrics`           | 回合、耗时与 token 汇总                                              |
| GET    | `/agents/{id}/threads/{thread_id}/trajectory/stream`            | 实时 SSE，用 `after_seq` 或 `Last-Event-ID` 续传                    |
| GET    | `/agents/{id}/threads/{thread_id}/trajectory/export`            | 导出账本，默认 JSONL，也可 JSON                                        |
| GET    | `/agents/{id}/chat/welcome`                                     | 欢迎语、快捷提示与 `task_examples`；工作区没有该字段时 `task_examples` 为 `null` |
| POST   | `/agents/{id}/chat/hitl/resume`                                 | 恢复暂停的人机确认请求                                                  |

## 创建线程

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/threads \
  -H 'Authorization: Bearer <token>'
```

响应：

```json
{"thread_id": "abc123", "session_key": "sk_..."}
```

## 获取历史记录

```bash
curl "http://127.0.0.1:8088/api/agents/1/threads/abc123/history?limit=50&offset=0" \
  -H 'Authorization: Bearer <token>'
```

支持 `limit` 和 `offset` 分页参数。响应还包含布尔字段 `turn_active`：为 `true` 时，请重新打开聊天 WebSocket 并发送 `{"type":"subscribe","thread_id":"..."}` 以恢复流式输出。

对于 v10 历史投影之前创建的旧线程，响应可能包含：

| 字段                       | 含义                                              |
| ------------------------ | ----------------------------------------------- |
| `history_loading`        | 投影后的消息行还没准备好                                    |
| `history_status`         | `pending`、`queued`、`running`、`failed` 或 `ready` |
| `history_retry_after_ms` | 建议再次轮询 history 的等待时间                            |

调用 `POST /agents/{id}/history-migration/start` 可在后台排队处理旧对话。Octop 会按专家逐个处理，新的对话仍可继续使用。

## 重命名或固定线程

```bash
curl -X PATCH http://127.0.0.1:8088/api/agents/1/threads/abc123 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "项目规划讨论", "pinned": true}'
```

## 欢迎语与任务示例

`GET /agents/{id}/chat/welcome` 返回专家欢迎语、快捷提示，以及工作区 `.octop/manifest.json` 里的 `task_examples`。`task_examples` 是 `{zh,en}` 字符串数组，展示时会规范成 3 或 6 条。需要定时任务空状态示例时优先用这个接口——它和 `GET /agents/{id}/cron/examples` 带同一字段。

## 文本辅助

`POST /text/assist` 用来润色或起草表单和对话里的文字。请求体是 `{kind, text?, context?, locale?, default_model?, agent_id?}`。表单类需要 `context.name`。`chat.prompt` 需要 `text`。模型默认走自动路由。响应是 `{text}`。

`POST /agents/{id}/chat/polish` 是 `kind=chat.prompt` 的兼容别名。请改用 `/text/assist`。

## 润饰端点

在实际发送之前优化用户输入的提示词文本：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/chat/polish \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "帮我写个邮件"}'
```

响应：

```json
{"text": "请帮我草拟一封专业的邮件，受信人是..."}
```

可选参数 `default_model` 可用于覆盖润饰时使用的模型。

## 人机确认恢复

当工具暂停等待批准，或通过 `ask_user_question` 向用户提问时，history 响应会带上 `hitl_pending`。用 SSE 请求恢复该回合：

```bash
curl -N -X POST http://127.0.0.1:8088/api/agents/1/chat/hitl/resume \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "thread_id": "abc123",
    "decisions": [{"type": "respond", "message": "使用预发数据库。"}]
  }'
```

支持的 decision 类型为 `approve`、`edit`、`reject` 与 `respond`。`ask_user_question` 使用 `respond`。一次最多提交 **16** 个 decision。`respond` 和 `reject` 的 `message` 必须是字符串，每条最多 **8000** 个字符。

## 分叉会话

`POST /api/agents/{id}/threads/{thread_id}/fork` 把一段对话复制成新线程，截止到指定的专家回复。原对话不变。传 `assistant_turns_from_end: 1` 可从最新一条回复分叉，或传入 `message_id`。专家需要处于运行中。

## 文件与知识库引用

线程列表和历史会带上专家生成的文件（例如写文件、桌面截图），以及回复用到知识库时的来源文档。页面里点击引用可在聊天中预览文档。

## 运行轨迹

`GET /agents/{id}/threads/{thread_id}/trajectory*` 对应聊天里的**运行轨迹**抽屉：分页事件摘要、单条完整事件、汇总指标、实时 SSE 和导出。需要审计回合与工具调用时用这些接口，不必刮页面。


> **提示**
> 
> 润饰端点很适合用于 UI 中的“润饰提示词”按钮——在实际发射前帮用户把输入润色为更清晰、更具体的提示词。
> 

