workspace/dsh-thinking-effort-fix.md

dsh 思考强度报错解决方案（11128 请求被拦截 / developer role 400）

适用症状：dsh（DeepSeek Harness）在 settings.yaml 给模型声明 reasoningEfforts 后（注意：声明即触发，与选了哪个档位无关，含 off），请求第三方/私有 OpenAI 兼容网关时失败：

• 网关带内容审计时：本轮运行失败 {"error":{"code":"11128","message":"请求被拦截，请重新发送","type":"invalid_request_error"}}
• 网关严格校验 role 时：400 ... messages[0].role: unknown variant 'developer', expected one of 'system', 'user', 'assistant', 'tool', ...

已于 2026-10-16 在 Windows + dsh 0.1.1-rc.2 上验证解决（示例 provider：coderelay，本地网关 http://127.0.0.1:11435/v1，上游带内容审计）。

根因（代码级因果链）

1. settings.yaml 给模型声明 reasoningEfforts（字典）后，dsh-llm-pi-ai 的 resolveModelReasoning 把该模型标记为 reasoning: true 并生成 thinkingLevelMap。
2. pi-ai 构造请求时据此决定系统提示词是否改用 developer role： openai-completions.js:787 — useDeveloperRole = model.reasoning && compat.supportsDeveloperRole
3. supportsDeveloperRole 的默认值按 provider 名 / baseURL 识别：只有非标准名单（nvidia / cerebras / xai / together / deepseek.com / zai / moonshot / opencode 等）默认 false；私有网关不在名单里，默认 true（openai-completions.js:1148）。
4. 于是系统提示词以 developer role 发出。上游网关不认识（或审计层直接拦截）时：严格校验的报 400 反序列化错误；带内容审计的直接拦截报 11128「请求被拦截」。

上游参考：deepseek-ai/deepseek-harness Discussion #636（第三方模型设置思考强度报错），评论区有腾讯系网关 content-audit 拒绝 developer role 的实测结论。

解决方案：加一行 compat

在 ~/.dsh/settings.yaml（Windows：C:\Users\<用户名>\.dsh\settings.yaml）对应 provider 下加：

llm-pi-ai:
  providers:
    <provider 名>:
      displayName: ...
      apiKeyEnv: ...
      api: openai-completions
      baseURL: ...
      compat:
        supportsDeveloperRole: false   # ← 新增：系统提示词改回 system role 发送
      models:
        - id: ...
          reasoningEfforts:
            ...

• 配在 provider（路由）级即对该 provider 下所有模型生效；也可配在单个 model 级。逐字段优先级：模型 → 路由 → 内置 catalog → pi-ai 自动检测。
• 思考强度功能保留，reasoning_effort 照常传递，只是 role 从 developer 改回 system。
• 改完重启 dsh 生效。多个 provider 都报同样错时每个都加。

本机实例（coderelay）：

    coderelay:
      displayName: coderelay
      apiKeyEnv: CODERELAY_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11435/v1
      compat:
        supportsDeveloperRole: false
      models:
        - id: deepseek-v4-pro
          ...
        - id: deepseek-v4.1-flash
          ...
		  reasoningEfforts:
            # ③ 逐模型声明可选档位
            off: #    提供"关闭"档，发送时省略参数
            low: low
            medium: medium
            high: high
            max: max

新机器上先检查版本

compat.supportsDeveloperRole 需要 dsh-llm-pi-ai 0.1.1-rc.2 及以上（更早版本 compat schema 没有这个开关，配置会被拒绝）。验证：

grep -c "supportsDeveloperRole" "$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-llm-pi-ai/lib/index.js"

返回 >0 即支持本方案；否则先把 dsh 升级到 0.1.1-rc.2（本机版本）再改配置。

改了还没好时的备用手段

按网关实际报错继续补 compat（同在 provider 的 compat 下）：

• 输出上限字段被拒：maxTokensField: max_tokens（未识别网关默认发 max_completion_tokens）
• 思考参数传输格式不对：thinkingFormat: deepseek 等
• 替代路线：
  1. 本地起一个几十行的 Node 转发器：把请求体里 messages[].role === "developer" 改写为 "system" 后原样透传（含 reasoning_effort），settings.yaml 的 baseURL 指向转发器。
  2. dsh plugin --profile web add pi2dsh + 对应网关的 Pi provider 包（Discussion #636 评论里的通用插件方案，较重）。
  3. 保底：删掉模型的 reasoningEfforts 声明，并把 agent-default-model.reasoningEffort 一起去掉；代价是思考强度功能不可用。

相关路径速查

内容	路径
配置	~/.dsh/settings.yaml
pi-ai developer role 判定	<dsh 安装目录>/node_modules/@deepseek-ai/dsh/node_modules/@earendil-works/pi-ai/dist/api/openai-completions.js（787、1148 行）
插件 compat schema	<dsh 安装目录>/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-llm-pi-ai/lib/index.js（compatProfile，884 行起）
插件中文文档	同目录 README.zh.md（含 supportsDeveloperRole: false 的官方私有网关示例）