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

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

#WebSocket 端点

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

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

#消息帧

向专家发送一轮对话：

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

服务器以流式块回应：

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

回复完成时发送：

{"type": "done"}

若发生错误：

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

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

{"type": "ping"}

{"type": "pong"}

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

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

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

显式停止当前回合：

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

#线程管理

#创建线程

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

响应：

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

#获取历史记录

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

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

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

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

#重命名或固定线程

curl -X PATCH http://127.0.0.1:8088/api/agents/1/chat/sessions/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 带同一字段。

#润饰端点

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

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": "帮我写个邮件"}'

响应：

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

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

#人机确认恢复

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

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 和导出。需要审计回合与工具调用时用这些接口，不必刮页面。