fix(llm): 修复 thinking mode 的 reasoning_content 协议 400，默认关闭深度思考

线上现象：用户发消息后助手回
「大模型错误：The `reasoning_content` in the thinking mode must be passed back to the API.」

根因：DeepSeek V4 系列（含 deepseek-flash）默认开启 thinking mode。官方协议规定，
只要请求带 tools 参数，历史里所有 assistant 消息的 reasoning_content 都必须原样回传，
否则接口直接回 HTTP 400。而 ChatMessage.toJson() 只输出 role/content/tool_calls/tool_call_id，
把该字段整个丢掉 —— 于是「第一轮模型调工具成功、第二轮请求必炸」。

改动：
- ChatMessage 增加 reasoningContent 字段并在 toJson 里输出（非空才输出）；ChatResult 同步解析响应字段。
- AgentOrchestrator 新增 assistantOf()，把模型每次返回的思维链写回对应的 assistant 消息
  （带 tool_calls 的那条与最终回复那条都要带）。
- DeepSeekClient：
  * 新增 agent.llm.thinking（auto/enabled/disabled），按配置显式发送 thinking 字段；
  * 命中 reasoning_content 协议错误时自动关闭 thinking 重试一次（自愈，线上无需等改配置即可恢复）；
  * humanizeApiError 增加该错误的中文话术，避免原样抛出英文协议报错。
- AgentSettings.Llm.thinking 由 boolean 改为三态字符串，默认 disabled：
  本工程属工具密集编排，几乎每轮都带 tools，CoT 收益有限却显著增加延迟与 token，
  且 thinking 模式下 temperature 会被忽略。
- application.yml 补 agent.llm.thinking: disabled 与说明。

新增 ThinkingModeTest（7 例）：字段序列化/省略、disabled 与 auto 的请求体、响应解析、
命中协议错误时的自愈重试、以及非协议错误不被误重试。

src/main/java/com/yunhai/agent/config/AgentSettings.java

@@ -129,8 +129,25 @@ public class AgentSettings {
         /** 单次 HTTP 超时（毫秒）。⚠️ 实际出站超时已由平台统一客户端接管，见 {@code yh.http.read-timeout-ms}；本字段保留仅作文档参考 */
         private int timeout = 60000;
 
-        /** 是否开启深度思考（旧的 deepseek-reasoner 独立模型已下线；V4 系列改为在请求里带 effort 档位，本开关暂未接线） */
-        private boolean thinking = false;
+        /**
+         * 深度思考（thinking mode）开关，三态：{@code auto} / {@code enabled} / {@code disabled}。
+         *
+         * <p><b>★ 2026-10-12 必读</b>：DeepSeek V4 系列（含 {@code deepseek-flash}）<b>默认开启</b> thinking mode。
+         * 官方协议规定：<b>只要请求带 {@code tools} 参数，历史里所有 assistant 消息的
+         * {@code reasoning_content} 都必须原样回传</b>，否则接口直接回
+         * HTTP 400 {@code The `reasoning_content` in the thinking mode must be passed back to the API}
+         * —— 表现为「第一轮模型调工具成功、第二轮就报错」，非常容易误判成鉴权/网络问题。
+         *
+         * <p>本工程是<b>工具密集型</b>编排（几乎每轮都带 tools），CoT 收益有限，却要付出
+         * 更高的延迟与 token 成本；且 thinking mode 下 {@code temperature} 被忽略。
+         * 因此默认 {@code disabled}（请求体显式带 {@code {"thinking":{"type":"disabled"}}}）。
+         *
+         * <p>{@code auto} = 不发送该字段、由服务端决定（当前服务端默认 = enabled，不推荐）；
+         * {@code enabled} = 显式开启（此时 {@link com.yunhai.agent.llm.dto.ChatMessage#getReasoningContent()}
+         * 会随 assistant 消息原样回传）。<b>注意</b>：会话消息落库未保存该字段，
+         * 若开启 thinking，请在同一次请求内完成多轮工具循环（浏览器代执行续跑会另起请求，可能不适用）。
+         */
+        private String thinking = "disabled";
     }
 
     @Data

src/main/java/com/yunhai/agent/llm/DeepSeekClient.java

@@ -44,6 +44,12 @@ public class DeepSeekClient implements LlmClient {
 
     private static final String TOOL_CHOICE_AUTO = "auto";
 
+    /** thinking mode 显式开启 */
+    private static final String THINKING_ENABLED = "enabled";
+
+    /** thinking mode 显式关闭 */
+    private static final String THINKING_DISABLED = "disabled";
+
     private final RestTemplate restTemplate;
     private final AgentSettings settings;
 
@@ -88,32 +94,32 @@ public class DeepSeekClient implements LlmClient {
                     "未配置大模型 api-key（agent.llm.api-key）");
         }
 
-        JSONObject body = new JSONObject();
-        body.put("model", llm.getModel());
-        body.put("max_tokens", llm.getMaxTokens());
-
-        JSONArray msgArr = new JSONArray();
-        for (ChatMessage m : messages) {
-            msgArr.add(m.toJson());
-        }
-        body.put("messages", msgArr);
-
-        // 现役 V4 系列（deepseek-flash / deepseek-v4-pro）temperature 与 tools 都支持。
-        // 保留 isReasoner 判断只为兼容历史上"reasoner 不支持二者"的模型名，正常情况下恒为 false。
-        if (!isReasoner(llm.getModel())) {
-            body.put("temperature", llm.getTemperature());
-            if (tools != null && !tools.isEmpty()) {
-                body.put("tools", tools);
-                body.put("tool_choice", TOOL_CHOICE_AUTO);
-            }
-        }
-
         HttpHeaders headers = new HttpHeaders();
         headers.setContentType(MediaType.APPLICATION_JSON);
         headers.set("Authorization", "Bearer " + llm.getApiKey());
         headers.set("Accept", "application/json");
 
         String url = StringUtils.isNotBlank(llm.getHost()) ? llm.getHost() : llm.getFallbackHost();
+        String thinkingType = thinkingType(llm);
+
+        try {
+            return doChat(url, headers, llm, messages, tools, thinkingType);
+        } catch (BizException e) {
+            // ★ 自愈：命中 thinking mode 的 reasoning_content 协议错误（HTTP 400）。
+            //   根因是历史 assistant 消息缺 reasoning_content，最省事的确定解就是关掉 thinking 重来一次。
+            //   这样即便线上配置来不及改（默认 auto/enabled），用户侧也不会卡死。
+            if (isThinkingOn(thinkingType) && isReasoningContentError(e.getMessage())) {
+                log.warn("[大模型] 命中 reasoning_content 协议错误，自动关闭 thinking 重试一次：{}", e.getMessage());
+                return doChat(url, headers, llm, messages, tools, THINKING_DISABLED);
+            }
+            throw e;
+        }
+    }
+
+    /** 实际发起一次 chat/completions 并解析响应 */
+    private ChatResult doChat(String url, HttpHeaders headers, AgentSettings.Llm llm,
+                              List<ChatMessage> messages, JSONArray tools, String thinkingType) {
+        JSONObject body = buildBody(llm, messages, tools, thinkingType);
         String requestBody = JSON.toJSONString(body);
 
         long start = System.currentTimeMillis();
@@ -163,6 +169,13 @@ public class DeepSeekClient implements LlmClient {
             } else if (contentObj != null) {
                 result.setContent(JSON.toJSONString(contentObj));
             }
+            // ★ 思维链：thinking mode 下必须随 assistant 消息一起回传，否则下一次带 tools 的请求会 400
+            Object reasoningObj = message.get("reasoning_content");
+            if (reasoningObj instanceof String) {
+                result.setReasoningContent((String) reasoningObj);
+            } else if (reasoningObj != null) {
+                result.setReasoningContent(JSON.toJSONString(reasoningObj));
+            }
             JSONArray toolCalls = message.getJSONArray("tool_calls");
             if (toolCalls != null) {
                 List<ToolCall> list = new ArrayList<>();
@@ -190,12 +203,76 @@ public class DeepSeekClient implements LlmClient {
             result.setCompletionTokens(usage.getInteger("completion_tokens"));
         }
 
-        log.info("大模型调用完成 cost={}ms tools={} tokens={}/{}",
+        log.info("大模型调用完成 cost={}ms tools={} tokens={}/{} reasoningChars={}",
                 cost, result.getToolCalls().size(),
-                result.getPromptTokens(), result.getCompletionTokens());
+                result.getPromptTokens(), result.getCompletionTokens(),
+                StringUtils.length(result.getReasoningContent()));
         return result;
     }
 
+    /** 组装 chat/completions 请求体（thinkingType 为 null 时不发 thinking 字段，由服务端决定） */
+    private JSONObject buildBody(AgentSettings.Llm llm, List<ChatMessage> messages,
+                                 JSONArray tools, String thinkingType) {
+        JSONObject body = new JSONObject();
+        body.put("model", llm.getModel());
+        body.put("max_tokens", llm.getMaxTokens());
+
+        JSONArray msgArr = new JSONArray();
+        for (ChatMessage m : messages) {
+            msgArr.add(m.toJson());
+        }
+        body.put("messages", msgArr);
+
+        // 现役 V4 系列（deepseek-flash / deepseek-v4-pro）temperature 与 tools 都支持。
+        // 保留 isReasoner 判断只为兼容历史上"reasoner 不支持二者"的模型名，正常情况下恒为 false。
+        if (!isReasoner(llm.getModel())) {
+            body.put("temperature", llm.getTemperature());
+            if (tools != null && !tools.isEmpty()) {
+                body.put("tools", tools);
+                body.put("tool_choice", TOOL_CHOICE_AUTO);
+            }
+        }
+
+        // ★ thinking mode 显式开关（auto 时不发，交服务端默认）。
+        //   必须显式按配置发送：DeepSeek V4 系列默认 enabled，不发就会带上那套「reasoning_content 必须回传」的约束。
+        if (thinkingType != null) {
+            JSONObject thinking = new JSONObject();
+            thinking.put("type", thinkingType);
+            body.put("thinking", thinking);
+        }
+        return body;
+    }
+
+    /**
+     * 解析配置里的 thinking 开关：
+     * <ul>
+     *   <li>{@code enabled} → 显式开启</li>
+     *   <li>{@code disabled} → 显式关闭</li>
+     *   <li>其它（含 {@code auto}、空）→ 返回 null，请求里不发该字段，由服务端默认决定</li>
+     * </ul>
+     */
+    private static String thinkingType(AgentSettings.Llm llm) {
+        String t = llm.getThinking();
+        if (StringUtils.isBlank(t)) {
+            return null;
+        }
+        t = t.trim().toLowerCase();
+        if (THINKING_ENABLED.equals(t) || THINKING_DISABLED.equals(t)) {
+            return t;
+        }
+        return null;
+    }
+
+    /** 本次请求是否可能处于 thinking 开启态（enabled，或未指定而由服务端默认开启） */
+    private static boolean isThinkingOn(String thinkingType) {
+        return thinkingType == null || THINKING_ENABLED.equals(thinkingType);
+    }
+
+    /** 是否 thinking mode 的 reasoning_content 协议错误（HTTP 400，文案固定含该字段名） */
+    private static boolean isReasoningContentError(String message) {
+        return message != null && message.toLowerCase().contains("reasoning_content");
+    }
+
     /**
      * 把底层 HTTP 异常翻译成使用者能看懂的话。
      *
@@ -256,6 +333,12 @@ public class DeepSeekClient implements LlmClient {
         if (lower.contains("rate limit") || lower.contains("too many requests")) {
             return "大模型请求过于频繁（" + m + "），请稍后重试";
         }
+        // thinking mode 协议错误：只要请求带 tools，历史 assistant 消息的 reasoning_content 必须原样回传。
+        // 本工程已把它按 assistant 消息透传（见 ChatMessage#reasoningContent），并在命中该错误时自动关 thinking 重试。
+        if (lower.contains("reasoning_content")) {
+            return "大模型思考模式协议错误（" + m + "）：历史消息未回传 reasoning_content。"
+                    + "已自动降级重试；若仍失败请把 agent.llm.thinking 设为 disabled";
+        }
         if (lower.contains("model not exist") || lower.contains("model_not_found")
                 || lower.contains("invalid model") || lower.contains("does not exist")) {
             return "大模型模型标识无效（" + m + "）：请用官方实时清单 GET https://api.deepseek.com/models "

src/main/java/com/yunhai/agent/llm/dto/ChatMessage.java

@@ -39,6 +39,17 @@ public class ChatMessage {
     /** role=tool 时必填：对应哪一次工具调用 */
     private String toolCallId;
 
+    /**
+     * assistant 消息的思维链（DeepSeek thinking mode 特有字段，与 content 同级）。
+     *
+     * <p><b>★ 必须原样回传</b>：官方协议规定，只要请求带 {@code tools} 参数，
+     * 历史里<b>每一条</b> assistant 消息的 {@code reasoning_content} 都要带回（包括没调工具的那轮），
+     * 否则 HTTP 400 {@code The `reasoning_content` in the thinking mode must be passed back to the API}。
+     * 本字段由 {@link com.yunhai.agent.llm.DeepSeekClient} 从响应里解析，
+     * 由 {@code AgentOrchestrator} 写回对应 assistant 消息。
+     */
+    private String reasoningContent;
+
     public ChatMessage(String role, String content) {
         this.role = role;
         this.content = content;
@@ -78,6 +89,10 @@ public class ChatMessage {
         if (StringUtils.isNotBlank(toolCallId)) {
             o.put("tool_call_id", toolCallId);
         }
+        // ★ thinking mode 协议：assistant 的思维链必须原样回传，否则带 tools 的请求会 400
+        if (StringUtils.isNotBlank(reasoningContent)) {
+            o.put("reasoning_content", reasoningContent);
+        }
         return o;
     }
 }

src/main/java/com/yunhai/agent/llm/dto/ChatResult.java

@@ -14,6 +14,12 @@ public class ChatResult {
     /** 模型回答正文（可能为空：当它只想调工具时） */
     private String content;
 
+    /**
+     * 思维链（DeepSeek thinking mode）：与 {@link #content} 同级返回。
+     * <p><b>★ 必须原样回传到后续请求的 assistant 消息</b>，否则带 tools 的请求会 HTTP 400。
+     */
+    private String reasoningContent;
+
     /** 模型要调用的工具 */
     private List<ToolCall> toolCalls = new ArrayList<>();
 

src/main/java/com/yunhai/agent/service/AgentOrchestrator.java

@@ -166,14 +166,16 @@ public class AgentOrchestrator {
                 String reply = StringUtils.isNotBlank(result.getContent())
                         ? result.getContent()
                         : "（模型没有返回内容，请换个说法再试一次）";
-                messages.add(new ChatMessage(ChatMessage.ROLE_ASSISTANT, reply));
+                messages.add(assistantOf(reply, result.getReasoningContent()));
                 resp.setReply(reply);
                 finish(resp, session, totalPrompt, totalCompletion, out);
                 return resp;
             }
 
             // 记录 assistant 的 tool_calls（后续必须以 role=tool 逐条应答，否则上下文非法）
-            ChatMessage assistantMsg = new ChatMessage(ChatMessage.ROLE_ASSISTANT, result.getContent());
+            // ★ 同时带上 reasoning_content：thinking mode 下带 tools 的请求要求历史 assistant 原样回传该字段，
+            //   否则下一轮请求会被接口判 400（The reasoning_content ... must be passed back to the API）。
+            ChatMessage assistantMsg = assistantOf(result.getContent(), result.getReasoningContent());
             assistantMsg.setToolCalls(result.getToolCalls());
             messages.add(assistantMsg);
 
@@ -324,6 +326,8 @@ public class AgentOrchestrator {
         }
 
         String idPrefix = "br_" + System.currentTimeMillis() + "_";
+        // 注：这条 assistant 是「服务端补造」的（模型当轮的消息在挂起时已撤销），没有真实 reasoning_content。
+        // thinking mode 关闭时（agent.llm.thinking=disabled，默认）不需要该字段；若改为开启，此处可能被接口判 400。
         ChatMessage assistant = new ChatMessage(ChatMessage.ROLE_ASSISTANT, null);
         List<ToolCall> calls = new ArrayList<>();
         List<String> contents = new ArrayList<>();
@@ -512,6 +516,7 @@ public class AgentOrchestrator {
         fn.setName(def.getName());
         fn.setArguments(JSON.toJSONString(args));
         tc.setFunction(fn);
+        // 同上：服务端补造的 assistant（无真实 reasoning_content），thinking 关闭时无需该字段
         ChatMessage assistant = new ChatMessage(ChatMessage.ROLE_ASSISTANT, null);
         assistant.setToolCalls(Collections.singletonList(tc));
         messages.add(assistant);
@@ -797,6 +802,19 @@ public class AgentOrchestrator {
         return "「" + def.getTitle() + "」执行失败：" + (tr.getError() == null ? "未知原因" : tr.getError());
     }
 
+    /**
+     * 构造 assistant 消息，并统一挂上 thinking mode 的思维链。
+     *
+     * <p>★ DeepSeek V4 系列默认开启 thinking mode，官方协议要求：只要请求带 {@code tools}，
+     * 历史里所有 assistant 消息的 {@code reasoning_content} 必须原样回传，否则 HTTP 400。
+     * 因此模型每一次返回的思维链都要落进对应的 assistant 消息里。
+     */
+    private ChatMessage assistantOf(String content, String reasoningContent) {
+        ChatMessage m = new ChatMessage(ChatMessage.ROLE_ASSISTANT, content);
+        m.setReasoningContent(reasoningContent);
+        return m;
+    }
+
     private void finish(ChatResponse resp, SessionStore.SessionState session,
                         int promptTokens, int completionTokens, EventSink out) {
         resp.setPromptTokens(promptTokens);