Operit DeepSeek Responses 思考模式工具延续修复:commentary 推理文本的捕获、持久化与重放
Operit DeepSeek Responses 思考模式工具延续修复:commentary 推理文本的捕获、持久化与重放
本文基于 docs/TODO/deepseek_responses_reasoning_replay_20260907/ 系列文档,剖析 Operit(Android 端 AI Agent)在 DeepSeek Responses API 思考模式(thinking mode)下的工具延续(tool continuation)问题:服务端同时通过
reasoningitem 与message.phase=commentary两种结构输出思考文本,而旧版适配器只保留前者,导致后续携带工具调用历史的请求触发HTTP 400。文章将结合 DeepseekProvider.kt、OpenAIProvider.kt、ChatMarkupRegex.kt 的源码级实现与 DeepseekResponsesPayloadAdapterTest.kt 的回归用例,完整还原「捕获—隐藏持久化—按序重放」的修复链路。读完本文,你将掌握 DeepSeek Responses 思考文本的两种表示形态、隐藏元数据标记的编码/解码协议、provider 扩展钩子的接入方式,以及如何通过回归测试锁定请求顺序与元数据清理行为。
一、问题背景:思考模式下的工具延续触发 HTTP 400
1.1 故障现象与错误信息
在 Operit 的 DeepSeek Responses 调用链中,当模型处于思考模式并发生客户端函数调用时,携带历史继续发起下一轮请求,服务端可能返回如下错误:
The reasoning_text in the thinking mode must be passed back to the API.
这是 HTTP 400 错误。其含义是:DeepSeek Responses 思考模式要求发起工具延续(即下一轮携带 function_call 与 function_call_output 的请求)时,必须把上一轮产生的思考文本以 reasoning_text 形式回传;缺失即拒绝。
1.2 根因:两种思考表示,只保留了一种
从源码 DeepseekProvider.kt 与协议文档 deepseek_responses_web_search.md 可以确认,DeepSeek Responses 流式输出中思考文本存在两种官方表示:
| 表示形态 | 输出项类型 | 用户可见性 | 旧版适配器处理 |
|---|---|---|---|
| 思考项 | reasoning(含 content[].reasoning_text) |
可见,作为 <think> 思考块 |
✅ 已保留并重放 |
| 评注消息 | message + phase: commentary(含 output_text) |
旧版被渲染成第二个思考块 | ❌ 未保留,工具延续时丢失 |
原有 DeepSeek 适配器虽然保存了 reasoning 输出项的隐藏元数据,却把 message.phase=commentary 当作普通正文处理——流式渲染时它会被显示为紧挨着 reasoning item 的第二个可见思考块,而后续工具延续请求中完全没有这一份思考文本的表示。由于思考模式下 function_call 前面必须存在 reasoning_text,缺失即触发上述 400。
1.3 修复目标
本次变更的核心诉求(记录于 index.md):
- DeepSeek 专属的请求转换必须同时保留并重放两种受支持的思考表示,且都在对应工具调用之前;
- OpenAI Responses 的加密 reasoning 契约保持不变(
encrypted_content格式),不得被 DeepSeek 的处理逻辑破坏; - 变更范围严格限定在四个文件:
DeepseekProvider.kt(元数据捕获与重放)、OpenAIProvider.kt(provider 扩展钩子)、DeepseekResponsesPayloadAdapterTest.kt(回归覆盖)、deepseek_responses_web_search.md(协议归属与重放行为)。
二、捕获(Capture):把 commentary 思考写入隐藏元数据
2.1 设计原则:隐藏持久化,不做第二个思考块
按 01_capture_commentary_reasoning.md 的设计:
- 完成的 commentary 消息只作为 DeepSeek Responses 隐藏元数据保存;
- 绝不将其作为
<think>输出到界面(避免出现第二个思考块); - 重建下一个
input时,把它恢复为带reasoning_text的reasoningitem,置于相关function_call之前; - 用户可见的思考仍只来自原始
reasoningitem。
这一设计避免了两个副作用:界面重复展示思考、以及把 commentary 原样当正文回传导致服务端 400。
2.2 非流式响应的识别与编码
非流式解析入口是 DeepseekProvider.kt 中的 DeepseekResponsesPayloadAdapter.parseNonStreamingResponse(L617-L706)。它对 output[] 数组逐项分派:
message且phase == "commentary":调用createCommentaryMetadataTag生成 output item 元数据,加入outputItemMetadataTags,并标记reasoningObserved = true,然后continue——不进入正文/reasoning 文本收集,因此不会污染可见输出;reasoning:收集reasoning_text到可见思考,同时生成 reasoning 元数据;function_call:转换为聊天风格 tool call;web_search_call:生成 output item 元数据(供后续恢复搜索调用历史)。
createCommentaryMetadataTag(L728-L753)把原始 item 打包成 Base64 payload 并写入协议标记:
{
"type": "message",
"role": "assistant",
"id": "msg_commentary_1",
"content": [
{"type": "output_text", "text": "I need to activate the package before calling its tool."}
]
}
标记格式由 ChatMarkupRegex.kt(L246-L248)生成,隐藏元数据使用独立 provider 命名空间:
<meta provider="openai:responses_output_item">BASE64_PAYLOAD</meta>
对应地,reasoning item 的元数据标记为 <meta provider="openai:responses_reasoning">...(L242-L244,常量定义于 L7-L9)。
2.3 流式场景:缓冲到 item 完成再落盘
流式场景更复杂——commentary 的 output_text.delta 是逐段到达的,而元数据必须在消息项完成时才能整体编码。为此 DeepseekResponsesProvider(L1263 起)做了三处覆盖:
override val useResponsesApi: Boolean = true
override val bufferResponsesOutputTextUntilItemDone: Boolean = true
override fun isResponsesCommentaryMessage(item: JSONObject): Boolean =
item.optString("phase", "").trim().equals("commentary", ignoreCase = true)
bufferResponsesOutputTextUntilItemDone = true:正文 delta 先进入缓冲区,不实时上屏;isResponsesCommentaryMessage:区分 commentary 与普通正文。
对应地,OpenAIProvider.kt 的默认实现是 bufferResponsesOutputTextUntilItemDone = false、isResponsesCommentaryMessage = false(L2103-L2105),即只有 DeepSeek 子 provider 开启该行为。
在事件处理层,emitLiveResponsesOutputText(L2990-L3005)与 emitBufferedResponsesMessageItemContent(L3007-L3030)都先调用 isResponsesCommentaryMessage 做分流:commentary 文本不调用 processResponsesRegularContentDelta 上屏,仅把 reasoningObserved 置为 true(表示本轮存在思考,但展示仍以 reasoning item 为准)。
真正的落盘发生在 response.output_item.done 事件边界(L2681-L2705):
val bufferedText = state.responsesOutputTextBuffers[outputIndex]?.toString().orEmpty()
if (bufferResponsesOutputTextUntilItemDone) {
if (outputIndex in state.responsesLiveEmittedOutputIndexes) {
state.responsesOutputTextBuffers.remove(outputIndex)
} else {
emitBufferedResponsesMessageItemContent(item, outputIndex, state, emitter)
}
}
// 完成的消息 item 可能携带不透明续传状态,
// 编码与重放均由 provider 专属钩子负责:
createResponsesMessageMetadataTag(item, bufferedText)?.let { metadataTag ->
emitter.emitMetadataTag(metadataTag)
}
该钩子正是本变更在 OpenAIProvider.kt(L224-L227)引入的扩展点:默认返回 null(OpenAI 不产生此类标记),DeepSeek 覆盖为 DeepseekResponsesPayloadAdapter.createStreamingCommentaryMetadataTag。其实现(L755-L781)在完成项自身没有 content 时也能从缓冲区兜底文本构造 payload:
{
"type": "message",
"role": "assistant",
"content": [{"type": "output_text", "text": "缓冲的思考文本"}]
}
三、重放(Replay):恢复为 reasoning item 并置于 function_call 之前
3.1 解码与按序恢复
下一轮构造请求时,聊天历史中的隐藏元数据标记需要被解码并还原为官方 input item。入口在 DeepseekProvider.kt 的 convertMessagesToResponsesInput(L839-L937),对每条 assistant 消息依次执行:
appendReasoningItemsFromAssistantMessage(L1083-L1104):从<meta provider="openai:responses_reasoning">解码出原始reasoningitem(含reasoning_id与content),恢复为input中的reasoningitem——这是用户可见<think>的来源;appendOutputItemsFromAssistantMessage(L1106-L1127):从<meta provider="openai:responses_output_item">解码出web_search_call或 commentary message 项;- 调用
convertMessageContentForResponses(removeThinkingContent = 两者任一为 true)(L939-L1033):把<think>与隐藏元数据从可见正文中剥离,避免 UI 展示文本被交回模型。
appendOutputItemFromMetadata(L1170-L1206)对 type == "message" 的 payload 执行关键转换:调用 convertCommentaryContentToReasoningContent(L1220-L1238),把 output_text / text / reasoning_text 内容统一改写为 reasoning_text,然后作为一个 reasoning item 写入 input。
源码中对此有一处决定性注释(L1188-L1189):
// Thinking-mode function calls require reasoning_text. Commentary is that thought
// in a message envelope; replaying it as output_text makes DeepSeek return 400.
这解释了为什么必须把 commentary 消息转写为 reasoning item 而非原样回传 output_text 消息:思考模式下 function_call 前面必须有 reasoning_text,原样回传将再次触发 400。
3.2 重放后的请求顺序
一次典型的工具延续请求,input 数组的最终顺序为:
index 0 type=reasoning (来自原始 reasoning item 或转写的 commentary 文本)
index 1 type=message (assistant 可见正文,已剥离思考与元数据)
index 2 type=function_call (带 call_id)
index 3 type=function_call_output(同一 call_id 的工具结果)
协议文档 deepseek_responses_web_search.md 同时强调:function_call_output 必须紧跟在对应 function_call 之后,不能被另一条 message 隔开;call_id 用于绑定调用与结果,不依赖并行任务的完成顺序。
3.3 可见性边界:元数据不出现在任何用户可见内容
为满足「commentary 文本缺席于用户可见消息、隐藏元数据缺席于用户可见请求内容」的期望结果,重放链路配套了两层清理:
sanitizeResponsesMessageText(L1035-L1042):removeThinkingContent剥离<think>,stripOpenAiResponsesProtocolMarkup剥离所有openai:responses_*隐藏标记;- 关闭思考模式时,DeepseekResponsesProvider.createRequestBody(L1324-L1329)还会调用
ChatUtils.stripOpenAiResponsesReasoningMetaTurns整体移除携带 reasoning 元数据的轮次。
四、扩展点设计:OpenAIProvider 的 provider 专属钩子
本修复没有把 DeepSeek 的逻辑硬编码进通用 OpenAI Responses 适配器,而是在 OpenAIProvider.kt 中提供了三个受保护的可覆盖成员,构成清晰的扩展契约:
| 钩子 | 默认实现 | DeepSeek 覆盖 |
|---|---|---|
createResponsesReasoningMetadataTag(item) |
调用 OpenAIResponsesPayloadAdapter.createReasoningMetadataTag |
复用默认,但支持纯文本 reasoning_text |
createResponsesMessageMetadataTag(item, bufferedText) |
返回 null(OpenAI 不产生) |
编码 commentary 为 output item 元数据 |
isResponsesCommentaryMessage(item) / bufferResponsesOutputTextUntilItemDone |
false / false |
true / true |
这种设计保证了协议归属清晰:reasoning_text 的保存与恢复由 DeepseekResponsesProvider + DeepseekResponsesPayloadAdapter 负责,而通用 OpenAI Responses 适配器只维护 OpenAI 的加密 reasoning 历史(encrypted_content 格式)。DeepSeek 的 createReasoningMetadataTag(L708-L726)要求 content 中存在非空 reasoning_text 才生成标记,天然排除了 OpenAI 风格的加密项。
五、回归测试:锁定重放顺序与隐藏元数据清理
DeepseekResponsesPayloadAdapterTest.kt 按 02_regression_coverage.md 的意图,从旧的「仅验证独立 reasoning item」扩展为覆盖 commentary 形态。四个用例完整锁定失败条件:
5.1 纯文本 reasoning 保留并重放
plaintext reasoning is preserved and replayed before function calls(L12-L57)构造一个 reasoning item,经 parseNonStreamingResponse 生成元数据标记,拼入 assistant 消息后转换请求,断言 input 前四项依次为 reasoning(id=rs_plain_1,content 完整保留)→ message → function_call → function_call_output,且 reasoning item 不含 encrypted_content 与 summary 字段。
5.2 加密 reasoning 不生成 DeepSeek 元数据
encrypted reasoning is not emitted as deepseek reasoning metadata(L60-L74)验证协议边界:包含 encrypted_content 的 OpenAI 加密 reasoning item 解析后 reasoningMetadataTags 为空——加密契约原样保留,不被 DeepSeek 的纯文本机制误处理。
5.3 commentary 思考保留在相关调用之前
commentary thinking is preserved before the related function call(L77-L121)是本次修复的核心回归:构造 message + phase=commentary + output_text 项,断言解析后 reasoningChunks 与 textChunks 均为空(不上屏),生成唯一的 outputItemMetadataTags 标记;转换请求后断言 input 共 3 项——reasoning(id 沿用 msg_commentary_1,content 为 reasoning_text)→ function_call → function_call_output,文本内容与原始 commentary 完全一致。
5.4 完成项无内容时缓冲文本兜底
buffered commentary thinking is preserved when the completed item has no content(L124-L154)覆盖流式边界:commentary item 自身无 content 时,createStreamingCommentaryMetadataTag(item, bufferedText) 仍能生成标记,重放后 reasoning_text 文本与缓冲区一致。
按文档所述,测试在以下任一情形下失败:commentary 思考被渲染为可见思考;未持久化为隐藏元数据;或重放顺序把 function call 与其 output 分离。
六、边界与配套约定
6.1 端点路由与协议归属
DeepSeek provider 内部按端点后缀决定协议(DeepseekProvider.kt L563-L578):端点以 /responses 结尾走 DeepseekResponsesProvider(Responses),否则走 Chat Completions(沿用 reasoning_content 参数机制,见 buildMessagesWithReasoning L219-L536)。该判断不扩散到 AIServiceFactory 之外,也不建立新的 provider 身份——模型价格、Token 统计与既有配置归属保持不变。
6.2 与 Web Search 的共存
同一 openai:responses_output_item 元数据机制同时承载 web_search_call 的恢复:服务端返回的完整 web_search_call output item 编码进标记,下一轮 adapter 解码后原样写回 input(L1171-L1177)。web_search_call 与客户端函数工具严格分离,不进入 AITool / ToolInvocation / 工具授权链路,<search> 展示块在构造请求文本时移除。
6.3 已知边界
<search>块当前仅保存搜索查询与来源列表;若服务端最终文本包含行内引用,仍作为普通响应文本展示,协议中未定义额外的行内 citation 组件;- 旧聊天记录没有
call_id时,按已发布版本的位置关系读取调用与结果绑定。
七、总结
本次修复以「隐藏持久化 + 按序重放」为原则,解决了 DeepSeek Responses 思考模式工具延续的 400 故障:commentary 思考文本不再作为第二个可见思考块渲染,而是编码进 <meta provider="openai:responses_output_item"> 隐藏标记,在下一轮请求中转写为带 reasoning_text 的 reasoning item 并置于 function_call 之前;同时通过 OpenAIProvider 的扩展钩子保持通用适配器与 OpenAI 加密 reasoning 契约完全隔离。四个回归用例把「重放顺序」「隐藏元数据清理」「加密项隔离」「缓冲兜底」全部锁定为可执行断言,后续任何破坏该行为的改动都会在测试层被拦截。相关设计与实现可继续深入 deepseek_responses_web_search.md(协议全貌)、DeepseekProvider.kt(适配器实现)与 DeepseekResponsesPayloadAdapterTest.kt(回归用例)查阅。