Skip to main content

事件与恢复

千问办公企业旗舰版开发者文档:事件与恢复。

事件、历史与断线恢复

认证方式见APP开发者文档 → 认证接入。

HTTP 历史与 SSE

GET /sessions/{session_id}/events 读取当前公开接口组装后的事件历史;GET /sessions/{session_id}/events/stream 订阅同一事件面。查询与 SSE 共享 seq_id 游标空间,不按数据库月分区切换客户端。 事件信封中的具体字段和分页字段见接口参考。Session 和 Turn 可以跨月分区,通过事件游标分页读取历史。

SSE 恢复

首次订阅不传 cursor 表示从现在开始,传 0 表示从会话开头补流。使用 fetch 时没有自动重连或游标维护;客户端仅在成功处理 session_event 后保存该帧显式 id,重连时自行携带 Last-Event-ID,或传 cursor。两者同传必须一致,否则 422;推荐只选择一种,不在重连 URL 中保留过时 cursor。状态帧、订阅错误的 resume_from 和 HTTP 分页游标不能覆盖已确认的安全恢复点。
// sessionId 和 lastEventId 来自当前会话及上次实际收到的事件。
const headers = { Accept: 'text/event-stream' };
if (lastEventId) headers['Last-Event-ID'] = lastEventId;
const response = await appRequest(
  `/api/openapi/app/v1/sessions/${encodeURIComponent(sessionId)}/events/stream`,
  {  headers },
);
if (!response.ok) throw new Error(`订阅失败:${response.status}`);
// 按 SSE 格式解析 response.body,保存事件 id,并在断线后重连。
事件连接结束与会话完成不是同一个状态。重新查询会话状态、补充历史后再继续跟随;不能把空事件或断线直接标记为执行失败。对恢复中重复事件使用稳定事件标识去重,不重复执行业务副作用。

Turn 与交互

Turn 标识一次执行回合,session_id 标识会话。初始回合完成后还可以继续普通对话。pending_action 表示需要用户处理的交互;取消、问答、队列撤回各有独立语义,不能互相替代。

WebSocket

Web 会话连接使用 /api/openapi/app/v1/sessions/chat-ws,列表通知连接使用 /api/openapi/app/v1/sessions/notify-ws。加入会话时校验资源归属。 WebSocket 消费方使用会话 SDK 的 join、replay、live 与控制消息。HTTP 消费方使用对应的 prompt、cancel、question-response 接口及 SSE 订阅;两种方式不要重复发送同一业务操作。 两条 WS 的独立接口页分别为“会话 WebSocket”和“用户通知 WebSocket”,包含握手、消息信封、字段、心跳和恢复语义。APP2 保持 HTTP + SSE,另接 notify-ws;两种通道的游标与消息信封不能混用。SSE 仅在成功处理 session_event 后保存该帧显式 id,不按连续 seq_id 推算,也不以 HTTP next_cursor 或 error.resume_from 覆盖安全恢复点。session_status、交互请求和回合结束事件触发会话状态查询;content_blocked 撤回对应内容;done/session_terminated 停止重连。