llm-pi-ai：无法在只接受 system 角色的 OpenAI 兼容网关（如火山方舟 plan）上控制自定义模型的思考深度

[Iron-Man666]

在 DSH 的 llm-pi-ai 自定义提供方上启用 reasoningEfforts（即把模型标记为 reasoning: true）后，pi-ai 会把系统提示词以 role: developer 发送。对只接受 system/assistant/user/tool 角色的 OpenAI 兼容网关（火山方舟 /api/plan/v3、大量自建/中转网关），每条请求都返回 400。compat.supportsDeveloperRole 是 pi-ai 内部自动探测字段，DSH 的 compat 配置未开放，因此用户无法通过配置关闭。

环境

• 组件：@deepseek-ai/dsh-llm-pi-ai
• 网关：火山方舟 Agent/Coding Plan /api/plan/v3（OpenAI Chat Completions 兼容，只认 system 角色）
• 模型：deepseek-v4-flash / deepseek-v4-pro / glm-5.2 / glm-5.3 / kimi-k3

复现步骤

1. settings.yaml 配置自定义提供方，并给模型加 reasoningEfforts：

llm-pi-ai:
  providers:
    volcengine:
      apiKeyEnv: VOLCENGINE_API_KEY
      api: openai-completions
      baseURL: https://ark.cn-beijing.volces.com/api/plan/v3
      models:
        - id: deepseek-v4-flash
          reasoningEfforts:
            off: null
            high: high
            max: max

2. 在新对话中发送任意消息。

预期行为

• 启用思考深度选择器；系统提示词以 system 角色发送；不 400。
• 或至少有一个配置项让用户声明"该端点不接受 developer 角色"。

实际行为

每条消息 400：

{"code":"InvalidParameter","message":"The parameter `messages.role` specified in the request are not valid: invalid value: `developer`, supported values are: `system`, `assistant`, `user`, `tool`."}

去掉 reasoningEfforts 后恢复可用（但思考深度选择器也随之消失）。

根因

1. 声明 reasoningEfforts → resolveModelReasoning 返回 reasoning: true。
2. pi-ai 转换系统提示词时：useDeveloperRole = model.reasoning && compat.supportsDeveloperRole；对未知端点，detectCompat 给出 supportsDeveloperRole: true（该 baseURL 不匹配任何"非标准"特征）。
3. DSH 的 compat 配置仅开放 thinkingFormat 与 supportsReasoningEffort（config.ts compatProfile），supportsDeveloperRole 属"刻意不开放"的其余 compat 面，无法覆盖为 false。

即：reasoning: true 与"发 system 角色"在方舟上互相排斥，且配置层无解。

建议修复

开放 compat.supportsDeveloperRole（route 级默认 + 模型级覆盖，解析顺序与现有两个开关一致，仅限 openai-completions）。补丁见 patch/0001-llm-pi-ai-expose-supports-developer-role.patch（6 文件、+57/-10，已通过 git apply --check）。

可选后续（独立）：让 pi-ai detectCompat 对非标准/未知 URL 默认 supportsDeveloperRole: false，从源头避免误判。

变通方案（上游合并前）

• 暂不启用 reasoningEfforts（无选择器，但可用）；
• 或改用接受 developer 角色的网关。

附加信息

• DSH 官方文档已声明该 compat 面"刻意不开放配置"：packages/llm/llm-pi-ai/README.zh.md「推理分派的 compat 开关」。
• 与官方 DeepSeek API 不冲突（其接受 developer 角色），故不影响现有 catalog 路由。

[denial123789]

There is an important release boundary here: the limitation is accurate for rc.7, but rc.8 already exposes supportsDeveloperRole at both route and model scope for openai-completions (and the three Responses protocols).

A route-wide rc.8 configuration can keep the reasoning selector while sending the system prompt as system:

llm-pi-ai:
  providers:
    volcengine:
      apiKeyEnv: VOLCENGINE_API_KEY
      api: openai-completions
      baseURL: https://ark.cn-beijing.volces.com/api/plan/v3
      compat:
        supportsDeveloperRole: false
      models:
        - id: deepseek-v4-flash
          reasoningEfforts:
            off: null
            high: high
            max: max

A model-level compat block is also supported and wins over the route value field by field. Do not leave supportsDeveloperRole: valueless; rc.8 rejects null instead of falling through to URL detection.

We updated the source-backed guide with the rc.7 workaround versus rc.8 native fix, precedence, backport boundary, and wire gates:

https://sandbaseai.github.io/deepseek-harness-handbook/openai-compatible-developer-role.html

Canonical source:
https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/openai-compatible-developer-role.md

The decisive verification remains the outbound messages[0].role: it should be system while the model still exposes the intended reasoning levels.

[weijiafu14]

如果不想在 settings 里逐个手填火山每个模型的 reasoningEfforts 和 compat，现在可以直接用现成 Provider：

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-volcengine-provider
# 启动前 export VOLCENGINE_API_KEY=...
# restart dsh

这个包对 13 个火山 Coding Plan 模型逐个声明真实思考档位，并统一带 supportsDeveloperRole: false、maxTokensField: max_tokens；GLM 模型还使用自己的 thinking 形状。pi2dsh 在 rc.8 上把这些字段按协议翻译到官方 llm-pi-ai profile，真实 HTTP 仍由 DSH 官方 adapter 发送。

我刚在全新 DSH profile 复核过：volcengine-plan route 已注册，13 个模型进入原模型选择器。这样不会在 pi2dsh 里写死火山逻辑，后续同类 Provider 仍走同一套标准。

https://github.com/weijiafu14/pi2dsh