[Defense] 路由覆写后来源 reasoningEffort 跨模型滞留：建议在 provider/model 切换边界重校验档位

[skyloader2474]

English summary: When a route-override layer (e.g. a preset/controller plugin that rewrites provider/model in the agent/request waterfall) omits reasoningEffort, an effort inherited from the session's model selection — valid on the source model — survives into the request for the target model. If the target is a hand-declared model without reasoningEfforts, DSH's client-side precheck rejects the whole turn with UNSUPPORTED_REASONING_EFFORT before any HTTP call. Suggested defense: revalidate/clear effort at the provider/model switch boundary.

环境 / Environment

• DeepSeek Harness Desktop 3.4.0（runtime 0.1.5-rc.1·Windows 10/11 x64）
• Preset：value-mode（第三方插件 @linxin666/dsh-value-mode 0.1.0），expert 路由未钉死 ⇒ 顶层请求由插件覆写为 agent-default-model 路由
• 涉及模型两类：
  • 来源模型（选择器带档·各档在其自身完全合法）：xai/grok-4.6（medium）、deepseek-official/deepseek-flash（high）、xiaomi-token-plan/mimo-v2.6-flash（high）
  • 目标模型（settings 手写 models 声明·无 reasoningEfforts·随包目录无底本）：stepfun/step-5-preview、step-3.7-flash、qwen-token-plan-cn/qwen3.8-flash

现象 / Actual

单个早晨 05:28–07:24（本地）内 10 次客户端预检拒绝、跨 6 个会话：

UNSUPPORTED_REASONING_EFFORT: provider "stepfun" model "step-5-preview" does not support reasoning effort "high"

报错发生在任何 HTTP 请求之前；同会话把模型切回已声明档位的模型（mimo）立即恢复。

证据链（三环·每环有锚）

1. 载体＝官方设计：providers 指南「推理等级」节明载「在选择器中选定某个等级后，它会与模型一起保存为新会话的默认值」——会话 model/selection 因此携带 reasoningEffort（本机会话事件实录：{"provider":"xai","model":"grok-4.6","reasoningEffort":"medium"} 等）。
2. 泄漏点＝覆写层不清档：value-mode 的 agent/request 拦截器覆写 provider/model 后，其自身路由未显式携带档位时只 spread 路由字段、不删除内层已注入的 reasoningEffort 键（插件源码 packages/dsh-value-mode 中该 spread 为 ...route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {} 形态，无 else 清除分支）。
3. 引爆点＝手写模型无能力声明：dsh-llm 的 resolveCallWithInfo 对 reasoning === undefined 且请求带档的组合直接 throw（发前拒绝）；手写模型未声明 reasoningEfforts 时能力按「无」解析（dsh-llm-pi-ai 的 resolveModelReasoning：base?.reasoning ?? false）。

绑定质量：10 次报错逐一绑定到会话真身的 turn/error 级事件，时刻与错误日志毫秒级对齐；每次报错前该会话的 model/selection 事件恰好携带一个外来档位；零反例。行为侧写：同一会话 step5→step3.7→qwen 连切全炸、切回 mimo 即恢复。

期望行为 / Expected（建议的路由边界三判据）

情况	处理
provider/model 未改变	保留当前合法 effort
provider/model 改变，目标路由无显式 effort	清除来源 effort，按目标模型自身默认规则决定
目标路由显式指定 effort	验证其属于目标模型声明集合，不属则明确拒绝

原则：隐式继承→清除；显式请求不兼容→报错；不做静默忽略（静默退化会让用户以为获得了更高推理强度）。

我方已做的消费方止血

已给两个手写模型补全 8 档 reasoningEfforts 声明并逐档 API 实测（HTTP 200），受影响会话已恢复。但止血不等于路由边界正确：只要还有手写模型未声明、或未来再有覆写型插件，同款泄漏会以别的模型名复现。

关联讨论 / Related

• Reasoning intensity is not selectable for third-party models.第三方模型无法选择推理强度 #122 第三方模型无法选择推理强度（手写模型须逐模型声明——本问题的能力面已知）
• deepseek-official 适配器不支持 `reasoning_effort: "low"` #1861 deepseek-official 适配器不支持 reasoning_effort "low"（同款客户端预检拒绝·他环境实报）
• dsh --profile headless 可以支持 reasoningEfforts 项吗？ #3493 headless 可以支持 reasoningEfforts 吗（reasoningEfforts vs reasoning 字段语义）
• Custom provider model discovery ignores reasoningEfforts from GET /v1/models #3566 Custom provider model discovery ignores reasoningEfforts（相邻但不同层：发现/采纳层丢字段；本报告是请求路由层参数滞留——补声明可缓解两者，但都不治「边界重校验」）

最小复现 / Repro

1. 配置一个手写模型（settings llm-pi-ai.providers.<route>.models，不写 reasoningEfforts）；
2. 新会话选择一个声明了档位的模型并选定档位（如 grok + medium）；
3. 经由任一覆写 provider/model 但不带 reasoningEffort 的层（本例 value-mode 未钉 expert、回落默认模型）把请求路由到步骤 1 的模型；
4. 发送消息 ⇒ 客户端预检 UNSUPPORTED_REASONING_EFFORT，无 HTTP 请求。

附注

• 同期观察到一处待核现象：dsh-settings-file 默认 watch: true＋100ms debounce，但本机两次外部修改 settings.yaml 后运行态未即时跟进（另有三项诊断在做，属独立问题，不并入本报告）。
• 本报告不含凭据、账号或本机路径信息。

[argszero]

This gap now has a plugin form: @argszero/dsh-effort-route-guard@0.1.0

First, a note on where the defect actually is, because it changes where the fix belongs. Core already implements the rule this thread asks for: installModelSelection (packages/core/agent/src/model-selection.ts) strips every inherited effort and re-applies the selected one, under the documented rule "An absent selected effort clears any inherited effort, restoring the selected model's provider/default behavior." What breaks it is the order of the waterfall — a value-mode override layer mounted outside that listener rewrites provider/model and spreads the config it received, with no else clearing the effort. So it runs after core has settled the effort, and a value that was correct for the old route travels to a route that never accepted it. That is why "re-validate at the provider/model switch boundary" lands naturally at the outermost agent/request boundary rather than inside the selection logic.

The other half is a design decision worth making deliberately. "Unsupported ⇒ clear" cannot tell an effort inherited from another route apart from one the user asked for on this route, and the two have opposite correct answers — the first is residue, and clearing it restores the target's own default; the second is a configuration error that must be reported, since a silent downgrade leaves the user believing they received a higher reasoning level (the reporter's point, translated from the original).

So the plugin clears only what it can prove is a leftover: the same effort, on record right now, against a different route, where the target route declares no support for it. Provenance is read from the two places a process states it — agent.options and the last durable request/header (a header is written only after prepareCall accepted that exact route and effort, so it is a route that has already carried it). An effort neither statement owns is left alone and counted unattributed, because clearing on a guess is a worse failure than the one being repaired.

• npm: https://www.npmjs.com/package/@argszero/dsh-effort-route-guard
• source: https://github.com/argszero/dsh-effort-route-guard

npm install @argszero/dsh-effort-route-guard@0.1.0

- insert:
    - id: effort-route-guard
      name: '@argszero/dsh-effort-route-guard'

Mounted directly, with the same config:

ctx.plugin(guard, { mode: 'observe' })   // measure before you repair

mode: 'repair' (default) clears a proven-inherited effort; observe counts the same decisions and returns every request unchanged, which is how you can measure how often this happens in your deployment before trusting the repair; off installs no listener at all. ctx.get('effortRouteGuard').snapshot() returns the counters broken down by rule, the recent decisions — each naming the route the effort actually came from — and the plugin's own declared blind spots.

Two boundaries worth stating up front, because they are the plugin's limits rather than the defect's:

• It covers layers mounted below it. A listener that registers with prepend after this plugin sits outside it, and the guard sees the request before that layer rewrites the route. In a deployment with several override layers, mount this one last.
• Only reasoningEffort is judged. temperature, maxTokens and stop can be stranded across a route change the same way; unlike an effort they do not fail pre-flight, and they are out of scope here.

There is no runtime dependency at all: it subscribes to a dispatched event and asks the public ctx.llm.resolveModelInfo for a route's capability, and only when the request carries an effort that no owner states for this route. Verified against the 0.1.7-rc.2 and 0.2.0-rc.2 lines, each pinned as a whole and the suite re-run against it.

[skyloader2474]

补充一条判据细节（供维护者与后来者参考，也当社区踩坑记录）：

在 argszero 指出的「继承档 vs 本路由明选档」区分之上，建议把 waterfall 覆写层的清理规则明确为「清继承档、保留本路由明选档」——判据取「继承 ⇒ clear」，而不是「Unsupported ⇒ clear」：

• 目标路由显式支持该档 ⇒ 保留（用户在本路由明选的意图应被尊重）；
• 目标路由无该档声明 ⇒ 清除继承档（而不是带着旧档发请求、再被发前校验拒绝）；
• 目标路由显式不支持 ⇒ 明确拒绝或降级提示（不静默带入）。

理由：「Unsupported ⇒ clear」无法区分「从别的模型继承来的档位」与「用户在本路由主动选择的档位」，会误伤后者；「继承 ⇒ clear」以档位来源为准，两种意图都能正确处理。

关联讨论：#122 / #1861 / #3493 / #3566。

本机实证（踩坑记录）：2026-10-08~09 多对话同族 UNSUPPORTED_REASONING_EFFORT 报错，10 个错误会话全部绑定到「跨模型档位滞留」同一根因；报错发生在发出任何 HTTP 请求之前（客户端预检层），同会话切回已声明档位的模型即恢复。