Operit DeepSeek Responses 思考模式工具延续修复:commentary 推理文本的捕获、持久化与重放

原创2026-09-27 22:48:191,848 阅读
文章标签:人工智能AI AgentAI 应用移动开发工具调用GUI 自动化本地部署插件系统Agent 工作流

Operit DeepSeek Responses 思考模式工具延续修复:commentary 推理文本的捕获、持久化与重放

本文基于 docs/TODO/deepseek_responses_reasoning_replay_20260907/ 系列文档,剖析 Operit(Android 端 AI Agent)在 DeepSeek Responses API 思考模式(thinking mode)下的工具延续(tool continuation)问题:服务端同时通过 reasoning item 与 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 的 reasoning item,置于相关 function_call 之前;
  • 用户可见的思考仍只来自原始 reasoning item。

这一设计避免了两个副作用:界面重复展示思考、以及把 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 消息依次执行:

  1. appendReasoningItemsFromAssistantMessage(L1083-L1104):从 <meta provider="openai:responses_reasoning"> 解码出原始 reasoning item(含 reasoning_id 与 content),恢复为 input 中的 reasoning item——这是用户可见 <think> 的来源;
  2. appendOutputItemsFromAssistantMessage(L1106-L1127):从 <meta provider="openai:responses_output_item"> 解码出 web_search_call 或 commentary message 项;
  3. 调用 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(回归用例)查阅。

登录后查看全文
Operit