fix(litellm): 保留 DeepSeek 兜底 thinking 参数

Author: mudssky

.trellis/spec/infra/litellm-gateway.md

@@ -36,14 +36,13 @@
   - `DEEPSEEK_API_KEY`: DeepSeek 密钥。
   - `LITELLM_MASTER_KEY`: LiteLLM 对外鉴权密钥。
 - Fallback-only parameter policy:
-  - DeepSeek 兜底别名必须显式丢弃 `thinking` 与 `reasoning_effort`，用于覆盖普通 Chat/Responses 参数转换路径；原生 Anthropic messages 路径不要把当前请求的 top-level `thinking` 改成 disabled。
+  - `claude-code-deepseek-*` 是 Claude Code Anthropic messages 专用兜底入口，必须保留当前请求的 top-level `thinking`、`reasoning_effort` 与 `output_config.effort`；不得再通过 `additional_drop_params` 丢弃 `thinking` / `reasoning_effort`。
   - Claude `/v1/messages` 原生路径必须启用 `callbacks.deepseek_thinking_sanitizer.proxy_handler_instance`，因为该路径会把历史 `messages[].content[]` 直接传给上游，`additional_drop_params` 不能移除 `content[].thinking` / `redacted_thinking` 内容块。
   - DeepSeek 官方 Claude Code 直连配置推荐 `CLAUDE_CODE_EFFORT_LEVEL=max`；在 Anthropic 兼容接口里，DeepSeek 的 effort 语义对应 `output_config.effort`，不是 OpenAI 兼容接口里的 `reasoning_effort`。
   - 原生 Anthropic messages fallback 的核心问题是历史 assistant thinking 内容块有两类语义：带 `signature` 的 `thinking` 与带 `data` 的 `redacted_thinking` 是上游要求完整回传的不透明块；缺少签名/不透明数据的 thinking 块通常来自跨供应商或中间层转换，DeepSeek 无法校验。sanitizer 应保留可回传块，只清理不兼容块与 `thinking_blocks` 辅助字段。
-  - 不得把 `output_config` 或 `output_config.effort` 加入 DeepSeek 兜底别名的 `additional_drop_params`；DeepSeek Anthropic 兼容接口使用它承接 effort。
-  - 普通 Chat/Responses 路径丢弃 `thinking` 会让 DeepSeek 兜底不再显式请求 extended thinking；原生 Anthropic messages 路径由 sanitizer 只清历史块，不禁用当前请求 thinking。
-  - 丢弃范围只绑定到 DeepSeek 兜底别名；不得在 GLM 主路由上全局禁用 Claude Code thinking。
-  - 如果 `claude-code-deepseek-*` 被直接调用，也会应用同一丢弃策略；因此该别名应被视为 fallback/兼容专用入口。
+  - 不得把 `thinking`、`reasoning_effort`、`output_config` 或 `output_config.effort` 加入 DeepSeek Claude Code 兜底别名的 `additional_drop_params`；DeepSeek Anthropic 兼容接口使用 top-level thinking 与 `output_config.effort` 承接 Claude Code effort。
+  - 如果未来需要面向 Chat/Responses 的保守 DeepSeek 兼容入口，应新增独立 safe 路由，而不是让 `claude-code-deepseek-*` 牺牲 Claude Code thinking 能力。
+  - 不得在 GLM 主路由上全局禁用 Claude Code thinking。
 - LiteLLM settings:
   - `drop_params: true` 用于丢弃上游不识别的普通参数。
   - `modify_params: true` 用于允许 LiteLLM 修正 Anthropic tool/thinking 历史块兼容问题。
@@ -65,7 +64,7 @@
 | GLM 正常可用 | `cc-glmplan-*` 直接走 GLM，保留 Claude Code thinking 语义 |
 | GLM 返回 429 / `RateLimitError` | LiteLLM 先按 retry policy 短重试 |
 | GLM 短重试耗尽 | Router fallback 到对应 `claude-code-deepseek-*` |
-| DeepSeek 收到顶层 `thinking` / `reasoning_effort` | 普通 Chat/Responses 路径由兜底别名的 `additional_drop_params` 处理；原生 Anthropic messages 路径应保留 top-level `thinking`，只清历史 thinking 块 |
+| DeepSeek 收到顶层 `thinking` / `reasoning_effort` | Claude Code DeepSeek 兜底路由应保留这些当前请求参数；sanitizer 只处理历史 content thinking 块 |
 | DeepSeek 收到带签名/不透明数据的历史 `content[].thinking` / `redacted_thinking` | sanitizer 必须原样保留这些块；DeepSeek thinking mode 需要它们维持工具调用回合的推理连续性 |
 | DeepSeek 收到无签名/不完整的历史 `content[].thinking` / `redacted_thinking` | sanitizer 必须在 deployment pre-call 阶段移除这些不兼容块，否则 DeepSeek 可能返回 thinking 历史校验错误 |
 | DeepSeek 返回 `thinking options type cannot be disabled when reasoning_effort is set` | 优先检查 sanitizer 是否错误设置了 `top_level_thinking_after: disabled`；正确策略是保留 top-level thinking，而不是 disabled + effort 共存 |
@@ -80,20 +79,20 @@
 
 - Good: GLM 429 后切到 DeepSeek，原生 Anthropic `/v1/messages` fallback 保留当前 top-level `thinking`，同时只移除无签名/不完整的历史 thinking content 块。
 - Good: sanitizer 原地修改 `messages` 列表并递归清理嵌套 content；日志显示 `top_level_thinking_before: enabled/adaptive`、`top_level_thinking_after: enabled/adaptive`、`remaining_thinking_paths: []`，同时 `preserved_thinking_blocks_after` 可大于 0。
-- Good: DeepSeek 兜底别名不丢弃 `output_config.effort`；如果 Claude Code / LiteLLM 以 DeepSeek Anthropic 官方字段表达 effort，`CLAUDE_CODE_EFFORT_LEVEL=max` 仍有机会透传。
+- Good: DeepSeek 兜底别名不丢弃 `thinking`、`reasoning_effort` 或 `output_config.effort`；如果 Claude Code / LiteLLM 以 DeepSeek Anthropic 官方字段表达 effort，`CLAUDE_CODE_EFFORT_LEVEL=max` 仍有机会透传。
 - Base: GLM 正常响应时不触发 fallback，不改变 Claude Code 对 GLM 主路由的 thinking 使用方式。
 - Bad: 全局丢弃 `thinking`，导致 GLM 主路由也失去 Claude Code extended thinking 能力。
 - Bad: sanitizer 为了绕过历史校验而设置 `thinking: disabled`，导致 DeepSeek 报 `thinking options type cannot be disabled when reasoning_effort is set`。
 - Bad: sanitizer 删除所有 `content[].thinking`，导致 DeepSeek 在带工具调用历史的 thinking mode 中报 `content[].thinking in the thinking mode must be passed back`。
 - Bad: sanitizer 诊断函数直接用 `value.get("type") in THINKING_BLOCK_TYPES`，真实请求里 `type` 是 dict 时会在 LiteLLM logging pre-call 阶段抛异常，反而遮蔽 fallback 的真实错误。
-- Bad: 看到 DeepSeek 官方推荐 `CLAUDE_CODE_EFFORT_LEVEL=max` 后，把 fallback 别名改成保留 `thinking`；直连 DeepSeek 与跨供应商 fallback 的历史消息完整性不同，不能混为一谈。
+- Bad: 为了兼容 Chat/Responses，把 `claude-code-deepseek-*` 继续配置成丢弃 `thinking` / `reasoning_effort`，导致 Claude Code 兜底链路失去 DeepSeek thinking / effort 能力。
 
 ### 6. Tests Required
 
 - Config parse: YAML 必须能被项目现有解析方式读取。
 - Config sync: 如果 `newapi.yaml` 与 `litellm.local.yaml` 应保持一致，修改后需要确认两者没有非预期差异。
 - Route contract: 检查 `router_settings.fallbacks` 仍指向专用 DeepSeek 兜底别名。
-- Parameter contract: 检查 `additional_drop_params` 只出现在 DeepSeek 兜底别名或其它明确的兼容专用路由上。
+- Parameter contract: 检查 `claude-code-deepseek-*` 不再配置 `additional_drop_params` 丢弃 `thinking` / `reasoning_effort`；如果出现 safe 兼容路由，其命名必须与 Claude Code 兜底路由区分。
 - Callback contract: 检查 `callbacks.deepseek_thinking_sanitizer.proxy_handler_instance` 能在 LiteLLM 镜像内导入，并实现 `async_pre_call_deployment_hook`，能在 `CallTypes.anthropic_messages` 且 deployment metadata 指向 DeepSeek 时原地清理请求参数。
 - Hook-stage contract: 离线测试必须直接调用 `async_pre_call_deployment_hook`，输入包含 `litellm_metadata.deployment` / `deployment_model_name` / `api_base`、顶层 `thinking` / `reasoning_effort`、历史 `content[].thinking` / `redacted_thinking`，断言清理发生在 provider 请求体构造前。
 - Reference contract: 离线测试必须断言原始 `messages` 列表对象 ID 不变，且清理后 `kwargs["messages"] is messages`；这是 Anthropic messages pass-through 位置参数链路的关键行为。
@@ -121,7 +120,7 @@ model_list:
       model: "anthropic/deepseek-v4-pro[1m]"
 ```
 
-问题：DeepSeek 兜底仍可能收到 Claude Code extended thinking 参数；跨供应商 fallback 时，历史消息缺少完整 `thinking_blocks` 会触发 `invalid_request_error`。
+问题：只配置 DeepSeek 路由而不挂载 sanitizer，会让跨供应商 fallback 的历史 thinking 内容块直接进入 DeepSeek；历史消息缺少完整签名或不透明数据时会触发 `invalid_request_error`。
 
 #### Correct
 
@@ -130,9 +129,6 @@ model_list:
   - model_name: "claude-code-deepseek-v4-pro"
     litellm_params:
       model: "anthropic/deepseek-v4-pro[1m]"
-      additional_drop_params:
-        - reasoning_effort
-        - thinking
 
 litellm_settings:
   drop_params: true
@@ -141,7 +137,7 @@ litellm_settings:
     - callbacks.deepseek_thinking_sanitizer.proxy_handler_instance
 ```
 
-理由：DeepSeek 兜底别名是降级链路专用入口，优先保证 GLM 429 后可用；主 GLM 路由仍保留 Claude Code extended thinking。`additional_drop_params` 处理普通参数，sanitizer 处理 Anthropic `/v1/messages` 历史内容块，两者不能互相替代。
+理由：DeepSeek 兜底别名是 Claude Code 降级链路专用入口，应保留当前请求的 thinking / effort 能力；sanitizer 只处理 Anthropic `/v1/messages` 历史 content thinking 块，两者不能互相替代。
 
 #### DeepSeek effort vs thinking
 
@@ -150,10 +146,8 @@ model_list:
   - model_name: "claude-code-deepseek-v4-pro"
     litellm_params:
       model: "anthropic/deepseek-v4-pro[1m]"
-      additional_drop_params:
-        - reasoning_effort
-        - thinking
-        # 不要加入 output_config 或 output_config.effort；DeepSeek Anthropic 兼容接口用它承接 effort。
+      # 不要在 Claude Code 兜底路由上丢弃 thinking / reasoning_effort / output_config.effort；
+      # DeepSeek Anthropic 兼容接口用它们承接 Claude Code thinking / effort。
 ```
 
 结论：`CLAUDE_CODE_EFFORT_LEVEL=max` 是 DeepSeek 官方 Claude Code 直连推荐配置；在 DeepSeek Anthropic 兼容接口里，effort 对应 `output_config.effort`。原生 Anthropic messages fallback 不应把当前请求降级为 `thinking: disabled`，否则会与 effort 冲突；正确做法是保留当前 thinking/effort，只清理历史 assistant thinking 块。
@@ -201,4 +195,4 @@ router_settings:
         - claude-code-deepseek-v4-pro-safe
 ```
 
-说明：可以先尝试完整 DeepSeek 路由，再 fallback 到只清理历史 thinking 块的 safe 路由，以尽量保留 DeepSeek 官方 thinking 能力。但 LiteLLM YAML 不能按 DeepSeek 返回的精确错误文本改写同一请求后重放；两级路由会增加配置复杂度和一次失败重试延迟。当前策略选择直接让 DeepSeek 兜底路由进入 safe 模式，优先保证 GLM 429 后 Claude Code 不被中断。
+说明：可以先尝试完整 DeepSeek 路由，再 fallback 到只清理历史 thinking 块的 safe 路由，以尽量保留 DeepSeek 官方 thinking 能力。但 LiteLLM YAML 不能按 DeepSeek 返回的精确错误文本改写同一请求后重放；两级路由会增加配置复杂度和一次失败重试延迟。当前策略选择让 `claude-code-deepseek-*` 保留当前 thinking / effort，并由 sanitizer 在单一路由内清理历史 thinking 块。

.trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/check.jsonl

@@ -0,0 +1,2 @@
+{"file": ".trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/prd.md", "reason": "验收标准与范围边界"}
+{"file": ".trellis/spec/infra/litellm-gateway.md", "reason": "检查 LiteLLM DeepSeek 兜底参数与 sanitizer 契约是否同步"}

.trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/implement.jsonl

@@ -0,0 +1,2 @@
+{"file": ".trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/prd.md", "reason": "实现范围、参数策略决策与验收标准"}
+{"file": ".trellis/spec/infra/litellm-gateway.md", "reason": "LiteLLM DeepSeek 兜底参数与 sanitizer 契约"}

.trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/prd.md

@@ -0,0 +1,97 @@
+# brainstorm: DeepSeek 兜底 thinking 参数策略
+
+## Goal
+
+厘清并收敛 `claude-code-deepseek-*` 兜底别名是否还需要在 `additional_drop_params` 中丢弃 `thinking` / `reasoning_effort`。目标是让 Claude Code 的 Anthropic `/v1/messages` fallback 保留 DeepSeek thinking 能力，同时避免 Chat/Responses 或 OpenAI 兼容路径把不兼容参数传给 DeepSeek。
+
+## What I already know
+
+* 用户质疑 `ai/gateway/litellm/litellm.local.yaml` 中 `claude-code-deepseek-v4-pro` 仍配置 `additional_drop_params: [reasoning_effort, thinking]`。
+* 当前 sanitizer 已不再禁用 top-level `thinking`，并且只清理无签名/不完整的历史 thinking block；带 `signature` 的 `thinking` 与带 `data` 的 `redacted_thinking` 会保留。
+* 运行态源码显示原生 Anthropic messages 路径只对 `additional_drop_params` 中的 dotted nested path 做删除；普通字段名 `thinking` / `reasoning_effort` 主要影响 Chat/Responses / OpenAI 兼容参数转换路径。
+* DeepSeek Anthropic 兼容接口可接受 top-level `thinking: {"type": "adaptive"}` 与 `output_config.effort`，真实 smoke 已验证 `/v1/messages` fallback 返回 200。
+* 用户已选择 Approach B：移除 `claude-code-deepseek-*` 的 `additional_drop_params`，把该别名定位为 Claude Code Anthropic messages 专用兜底入口。
+
+## Assumptions (temporary)
+
+* Claude Code 主路径是原生 Anthropic `/v1/messages?beta=true`，不是 OpenAI chat/completions。
+* `claude-code-deepseek-*` 不承担 Chat/Responses 保守兼容职责；如果未来需要，应新增独立 safe 路由。
+
+## Open Questions
+
+* 无。
+
+## Requirements (evolving)
+
+* 明确 `additional_drop_params` 在 Anthropic messages 与 Chat/Responses 路径中的真实影响范围。
+* 保持 GLM 429 fallback 到 DeepSeek 的 `/v1/messages` 链路可用。
+* 避免再次引入 `thinking: disabled` 与 effort 冲突。
+* 文档必须区分 “top-level current thinking 参数” 与 “历史 content thinking block”。
+* `claude-code-deepseek-*` 不得通过 `additional_drop_params` 丢弃 `thinking` / `reasoning_effort`。
+
+## Acceptance Criteria (evolving)
+
+* [x] 选定并记录 `claude-code-deepseek-*` 是否保留 `additional_drop_params` 的策略。
+* [x] 如果修改 YAML，`newapi.yaml` 与 `litellm.local.yaml` 保持预期一致。
+* [x] `/v1/messages?beta=true` fallback 仍返回 200。
+* [x] sanitizer 日志中 top-level `thinking` 不被降级，signed thinking 不被误删。
+* [x] 文档与 Trellis spec 同步记录最终策略。
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated (unit/integration where appropriate)
+* Lint / typecheck / CI green
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+
+## Out of Scope (explicit)
+
+* 不在本任务中重写 LiteLLM Router fallback 机制。
+* 不新增外部代理或替换 DeepSeek Anthropic 上游。
+* 不处理 `.codex/config.toml` 与 `.shrimp-data/` 这些已有未提交工作区改动。
+
+## Research Notes
+
+### Code inspection
+
+* `ai/gateway/litellm/litellm.local.yaml` 与 `ai/gateway/litellm/newapi.yaml` 的 DeepSeek 兜底别名仍配置 `additional_drop_params: [reasoning_effort, thinking]`。
+* LiteLLM 容器内 `llm_http_handler.py` 的 Anthropic messages path 只从 `additional_drop_params` 中取 dotted nested path 并对 `anthropic_messages_optional_request_params` 做删除，普通字段名不会删除原生 messages 的 top-level `thinking`。
+* LiteLLM `utils.py` 中 `_should_drop_param` 会让普通字段名 drop 作用于 OpenAI 兼容参数映射路径。
+
+### Feasible approaches
+
+**Approach A: 保守保留 drop（当前状态）**
+
+* How it works: 保留 `additional_drop_params: [reasoning_effort, thinking]`，原生 `/v1/messages` 依靠 sanitizer 保留 top-level thinking；Chat/Responses 继续丢弃这两个参数。
+* Pros: 对非 Claude Code 路径更保守，减少未知兼容风险。
+* Cons: 配置语义容易误导，名字叫 Claude Code 但 Responses 路径会失去 thinking。
+
+**Approach B: 移除 drop（推荐，如果该别名只给 Claude Code 用）**
+
+* How it works: 从 `claude-code-deepseek-*` 别名移除 `additional_drop_params`，让 DeepSeek Anthropic 兼容接口接收当前 thinking/effort；历史 content block 仍由 sanitizer 清理。
+* Pros: 语义最一致，DeepSeek thinking 能力不被配置层静默拿掉。
+* Cons: 如果有人直接用该别名走 Chat/Responses，可能重新暴露 provider 参数兼容问题。
+
+**Approach C: 拆路由**
+
+* How it works: `claude-code-deepseek-*` 移除 drop，新增 `deepseek-compat-safe-*` 之类路由给 Chat/Responses 保守 drop。
+* Pros: 能力与兼容边界最清晰。
+* Cons: 配置更复杂，fallback 规则和文档都要增加维护成本。
+
+## Technical Notes
+
+* 相关文件：
+  * `ai/gateway/litellm/litellm.local.yaml`
+  * `ai/gateway/litellm/newapi.yaml`
+  * `ai/gateway/litellm/callbacks/deepseek_thinking_sanitizer_core.py`
+  * `.trellis/spec/infra/litellm-gateway.md`
+  * `ai/gateway/litellm/litellm.md`
+* Context7 查询 LiteLLM 文档未直接返回 `additional_drop_params` 专门章节；以运行容器源码为准。
+
+## Decision (ADR-lite)
+
+**Context**: `claude-code-deepseek-*` 是 GLM 429 后的 Claude Code Anthropic messages 兜底入口。上轮保留 `additional_drop_params: [thinking, reasoning_effort]` 是为了 Chat/Responses 路径保守兼容，但会让配置语义变成“Claude Code 兜底仍静默丢弃 thinking/effort”。
+
+**Decision**: 采用 Approach B，移除 `claude-code-deepseek-*` 的 `additional_drop_params`。Claude Code 兜底路由保留当前 top-level `thinking`、`reasoning_effort` 与 `output_config.effort`；历史 content thinking 兼容仍由 sanitizer 处理。
+
+**Consequences**: Claude Code fallback 保留 DeepSeek thinking / effort 能力；如果未来要支持 Chat/Responses 的保守 DeepSeek 兼容，应新增独立 safe 路由，而不是复用 `claude-code-deepseek-*`。

.trellis/tasks/05-09-litellm-deepseek-thinking-param-policy/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "litellm-deepseek-thinking-param-policy",
+  "name": "litellm-deepseek-thinking-param-policy",
+  "title": "brainstorm: DeepSeek 兜底 thinking 参数策略",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "codex",
+  "assignee": "codex",
+  "createdAt": "2026-05-09",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}