Chat 订阅与提交

本文是常用 API中 Chat 能力的展开说明，重点讲三件事：

• chat/submit 的完整请求参数、返回字段和路由结果。
• chat/conversations/{conversationId}/stream 的订阅参数、SSE 帧格式和事件结构。
• AI 通过 AskUserQuestion 提问时，如何把 ask_question 事件渲染成问题卡片，并把用户答案提交回去。

如果你只需要“发一条消息并接收文字输出”，看完「一次完整对话的调用顺序」即可；需要接入问题卡片时，再看「AskUserQuestion 问题卡片」。

小提示：Chat 能力还在持续打磨，文中的参数和事件结构后续可能还会有些调整。新增字段或事件类型一般不会影响已有对接，按 eventIndex 消费事件、忽略不认识的内容就能平滑跟进；如果将来确实需要做不兼容的调整，也会提前通过变更说明告知。

一次完整对话的调用顺序

一轮对话中，responseId 标识一轮 AI 回复。每次提交或回答问题后，按返回的 observationDisposition 决定是否使用最新 activeResponseId 重新订阅，避免把上一轮的事件当成新一轮。

提交消息

请求参数

任务绑定、执行环境选择、问题诊断等平台内部字段不在本文展开，门户对接通常不需要使用。

返回字段

接口遵循常用 API的统一响应格式，下面展示的是其中 data 字段的内容；错误时外层 code 为对应错误码。

route 取值：

observationDisposition 取值：

常见错误

订阅实时输出

订阅参数

路径参数：

查询参数：

请求头：

SSE 帧格式

普通事件使用默认的 message 事件，事件类型在 JSON 的 type 字段中：

心跳事件：

id 就是 eventIndex。断线重连时可用它作为 Last-Event-ID，或换算成 fromIndex。心跳约每 15 秒一次，不带业务含义，只用于保持连接和判断连接是否存活。

通用事件字段

事件类型

stream_end.status 取值：

收到 stream_end 或 error 后，本轮订阅即结束，不要继续等待更多事件。

快照事件 response_snapshot

当客户端订阅时本轮输出已经在进行，或断线期间的事件缓存已经无法补齐，服务端可能先下发一条 response_snapshot：

处理规则：

• 用快照替换本地 responseId 相同的未完成回复，不要和已有文本重复拼接。
• 下一次重连使用 fromIndex = snapshotEventIndex + 1。
• status 取值为 active、paused、completed、failed、interrupted；不是 active 就说明本轮已结束，关闭订阅，不必等待后续 stream_end。注意快照的失败终态是 failed 而不是 error。
• 快照里的 tool_use 块同样可以恢复未回答的问题卡片。

AskUserQuestion 问题卡片

当 AI 需要用户做选择、确认方案或补充信息时，会调用 AskUserQuestion。对门户来说，这就是“问题卡片”的数据来源。

事件顺序

一轮提问通常会依次收到三条事件：

1. tool_call：工具调用开始，toolName 为 AskUserQuestion。
2. ask_question：问题内容，用于渲染卡片。
3. stream_end：status 为 paused，表示本轮暂停等待用户回答。

示例：

渲染卡片时应同时保存：

• requestId：回答时必填，用于定位当前待处理交互。
• toolUseId：回答时建议带上，用于关联工具调用。
• questions：完整问题列表。
• responseId：本轮回复 ID，用于判断卡片是否仍然有效。

ask_question 事件结构

字段说明：

questions[] 元素：

不同运行时对问题字段的补全程度不同，id、isSecret 等字段可能缺失，渲染时按可选字段处理。

options[] 元素：

渲染成问题卡片

参考 Knodo 的交互，建议按以下规则渲染：

• 一题一卡：questions 只有一个元素时直接展示；多个元素时用 tab、步骤条或分页，不要把所有问题堆在一起。
• 标题：优先使用 header，为空时显示“问题 N”。
• 问题正文：使用 Markdown 渲染，保留换行和列表。
• 单选 / 多选：multiSelect=false 用单选控件，true 用复选控件。
• 选项：展示 label；有 description 时作为副标题展示。
• 自定义输入：在选项末尾追加“其他 / Other”，选中后展示输入框。用户输入的自定义文本直接作为答案。
• 提交条件：每个问题都必须有答案。单选至少选一项，多选至少选一项，选择“其他”时必须填写输入框。
• 敏感问题：isSecret=true 时使用密码输入或提交后不回显答案。
• 可操作性：只有收到 ask_question 且本轮状态仍为暂停时才允许提交；提交后立即把卡片置为“已提交”或“已取消”，防止重复点击。
• 不要自动回答：即使用户之前回答过类似问题，也不要复用旧答案代替用户确认。

多题卡片可以在顶部显示“已完成 1/2”的进度，并在用户切换问题时校验当前问题，这些只是展示层增强，不影响提交协议。

提交回答

用户完成选择后，再次调用 chat/submit，并在 pendingResponse 中带回交互信息。

pendingResponse 字段：

answers 的 key 和 value 规则：

• key 优先使用问题的 question 文本；如果问题带有 id，建议同时写入一份 id key，兼容不同运行时。
• 单选：value 为选中的 label，或用户填写的自定义文本。
• 多选：多个 label 用换行符 \n 连接。
• 自定义输入：value 直接使用用户填写的文本。
• 同一个问题使用 id 和 question 两个 key 时，value 必须相同。

示例：单选、多选、自定义输入混用。

message 用于在会话中保存一条用户可见的回答摘要。Knodo 会把各题答案用换行拼接后作为 message，你也可以自定义更易读的摘要。clientMessageId 必须使用新的值；如果因为网络问题重试同一个回答，则保持同一个 clientMessageId 和相同的请求体。

成功响应：

随后使用新的 activeResponseId 重新订阅 stream，继续接收 AI 的后续输出：

用户取消或拒绝回答

有两种处理方式：

1. 取消本轮执行：调用 POST /api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}/interrupt。服务端会结束暂停中的本轮执行，问题卡片可以关闭。
2. 通过回答通道拒绝：提交 pendingResponse，把 response.behavior 设为 deny，并在 response.message 中说明原因。注意 deny 不会终止本轮执行，AI 会收到拒绝说明后继续运行；如果要直接停止执行，应使用方式 1 的 interrupt。例如：

回答失败与重试

重试时请使用完全相同的 requestId、toolUseId、response 和 clientMessageId。如果 requestId 已经过期，不要用旧答案强行提交，应重新查询会话历史。

刷新页面后恢复未回答问题

用户刷新页面或重新进入会话时，问题卡片可能还没有回答。可以通过两种方式恢复：

方式一：订阅流时收到 response_snapshot

快照 status 为 paused，blocks 中存在：

方式二：查询会话历史

调用 GET /api/v1/workspaces/{workspaceId}/chat/conversations/{conversationId}/messages，在返回的消息中查找：

• blockType 为 tool_use
• toolName 为 AskUserQuestion
• toolResult 为空
• toolInput.questions 存在
• toolInput.__knodoPendingRequest 存在

对应字段：

同时可通过会话详情或状态接口确认 conversationStatus 为 paused。如果会话已经结束或继续运行，未回答的旧问题不应再提供提交入口。

权限确认与问题的区别

非问答类工具（例如执行命令、写文件）需要授权时，事件类型是 permission_request，不是 ask_question：

权限确认同样通过 chat/submit 的 pendingResponse 回答，response.behavior 传 allow 或 deny；需要调整工具入参时使用 response.updatedInput，allow 时还可在 response.permissionMode 中指定后续权限模式。问题卡片渲染只需要关注 ask_question。

断线重连

订阅连接可能因平台升级、网络波动或服务端恢复而中断，但会话本身会继续执行。客户端重新订阅即可接上，不需要重新提交消息。

关键规则：

• 记录最后一个已处理事件的 eventIndex，重连时传 fromIndex = eventIndex + 1。
• 未传 fromIndex 时，服务端兼容标准 SSE 客户端的 Last-Event-ID 请求头，从该序号的下一条开始续传。
• 按 responseId + eventIndex 去重，SSE 重放可能重复投递相同事件。
• 收到 stream_end 或 error 后本轮结束，不要继续重连。
• 超过约 45 秒既没有事件也没有心跳时，可视为连接失效，主动断开后重连。
• 503、429 会返回 Retry-After 响应头，客户端等待时间不应短于该值。
• 409 表示续传位置已无法补齐，应先查询会话详情获取已持久化内容，再从 fromIndex=0 重新订阅。
• 浏览器原生 EventSource 无法读取状态码和 Retry-After，需要精细重试时建议使用基于 fetch 的 SSE 客户端。

重试节奏、状态码明细和更多断线处理规则见常用 API的「断线重连」章节。