「续 #3379」建议：supportsDeveloperRole 默认改为 false，并在模型配置 UI 增加可见开关

[Yn4brns]

Follow-up on #3379: default supportsDeveloperRole to false for non-native OpenAI endpoints, and consider a visible toggle in model settings

接 [接入火山方舟（Ark, volces.com）报 400：pi-ai 将系统提示词以 developer 角色发出，方舟只接受 system/assistant/user/tool #3379](#3379)

背景

上一个 discussion 的根因：自定义提供方声明 reasoningEfforts（推理模型）后，pi-ai 会以 developer 角色发送系统提示词，而多数非 OpenAI 端点拒绝该角色，直接 400。

好消息：rc.8 已在 dsh-llm-pi-ai 的 compatProfile 中加入 supportsDeveloperRole 开关，通过 settings.yaml 可以关闭（我已在方舟、Dots 等场景实测生效），上一个 discussion 提到的问题已经解决。👍

随之而来的新问题

1. 默认值仍不安全：自定义提供方只要 baseURL 不在 pi-ai 的 isNonStandard 名单里，supportsDeveloperRole 就默认 true（responses 协议更是无条件 ?? true）。新增"推理模型 + 不在名单的端点"组合，依然一请求就 400。

2. 模型配置 UI 没有任何 compat 开关：设置 → 模型 的自定义提供方卡片只有 Provider ID / 显示名 / baseURL / 协议 / API key / 模型列表。用户无法在 UI 关闭它，只能手改 settings.yaml（官方文档也写明"表单没有对应字段"）。

3. 报错极具误导性，排查容易走弯路。以我最近的一次实际遭遇为例：配置了新模型 dots3-note-prev（声明了 reasoningEfforts），调用时报 400 status code (no body) / CONTEXT_WINDOW_EXCEEDED。按错误码先查上下文，结果：

   • 当时实际上下文只有约 97K tokens，远低于模型 512K 窗口；
   • 又逐一排除 max_tokens=64000、stream_options、tools 数组、1MB 大载荷——全部返回 200。

   折腾一圈后回到老问题：用与 DSH 相同的 SDK 复现，role: developer 立刻 400，role: system 返回 200——最终确认还是 接入火山方舟（Ark, volces.com）报 400：pi-ai 将系统提示词以 developer 角色发出，方舟只接受 system/assistant/user/tool #3379 的同一个根因。而这个 400 响应体为空，被 pi-ai 的启发式规则（为 Cerebras 加的 400/413 (no body) 匹配）误分类成 CONTEXT_WINDOW_EXCEEDED，与真实原因毫无关系。

为什么建议默认改为 false

这个问题有不少先例，不是孤立现象：

• [OpenClaw #27037 / PR #29479（已合并）](https://github.com/openclaw/openclaw/pull/29479)：*"only native api.openai.com accepts it — every other backend (Qwen, DeepSeek, GLM, Kimi, Azure, proxies) returns a hard 400"*；修复方式就是强制非 api.openai.com 端点 supportsDeveloperRole=false，并保留 per-model 显式 true 覆盖。
• [pi-ai 库 #1048](https://github.com/earendil-works/pi/issues/1048)：DeepSeek API 拒绝 developer role。
• [OpenClaw #21066](https://github.com/openclaw/openclaw/issues/21066)：阿里 Dashscope 同样 400。
• 加上本仓库 接入火山方舟（Ark, volces.com）报 400：pi-ai 将系统提示词以 developer 角色发出，方舟只接受 system/assistant/user/tool #3379（方舟）和我们最近遇到的 Dots：都是同一族故障。

结论：目前已知可靠接受 developer role 的只有原生 api.openai.com（OpenClaw 调研：非原生端点中 "none known"）。黑名单式逐个打补丁永远追不上现实，默认 false + 显式 opt-in 才是安全形态。

改动方法（建议）

改动很小，两个协议都要覆盖。以当前 DSH 内置的 pi-ai 0.82.1 为例，共三处：

// 1) node_modules/@earendil-works/pi-ai/dist/api/openai-completions.js
//    约 1148 行（detectCompat() 内）
//    注：用 includes 判断而非精确相等，以兼容尾斜杠等 URL 变体
supportsDeveloperRole: isOpenRouterDeveloperRoleModel || baseUrl.includes("api.openai.com")

// 2) node_modules/@earendil-works/pi-ai/dist/api/openai-responses.js
//    约 52 行（getCompat() 内）
supportsDeveloperRole: model.compat?.supportsDeveloperRole ?? false

// 3) node_modules/@earendil-works/pi-ai/dist/api/openai-responses-shared.js
//    约 92 行（convertResponsesMessages() 内，role 判定处）
const compat = model.compat;
const defaultSupportsDeveloperRole = typeof model.baseUrl === "string" && model.baseUrl.includes("api.openai.com");
const role = model.reasoning && (compat?.supportsDeveloperRole ?? defaultSupportsDeveloperRole) ? "developer" : "system";

⚠️ 落实时的重要发现（易踩坑）：responses 协议的 role 判定在 openai-responses-shared.js 约 92 行，它读取的是 model.compat（原始配置），而不是 getCompat() 的解析结果。因此只改第 2 处（responses.js 的 ?? false）是死代码、不会生效——实测改完后 responses 实际发出的仍是 developer，必须同时改第 3 处。completions 协议走的是解析后的 compat（getCompat 合并 model.compat ?? detected），所以第 1 处单独就够。

保留 compat.supportsDeveloperRole: true 作为显式逃生舱（OpenClaw 已验证此模式可行）。若不想依赖上游 pi-ai，也可在 dsh-llm-pi-ai 构建 provider 时做归一化（思路同 OpenClaw 的 normalizeModelCompat：非原生端点默认 false、显式配置优先）。

已在本机 rc.8（pi-ai 0.82.1）落实并验证：通过 pi-ai 真实 streamSimple 路径抓取实际发出的 wire 消息，completions 与 responses 两个协议下均为——非 OpenAI 端点默认 system、原生 api.openai.com 保持 developer、显式 compat.supportsDeveloperRole: true 覆盖仍生效。

收益与风险

收益：

• 保护所有现有与未来用户（包括从不改配置的用户），一行判定，成本极低；
• 有 OpenClaw 已合并的同类修复作先例。

风险/代价：

• system 与 developer 都是系统级指令，绝大多数端点等效；唯一受影响的是"非原生端点但接受 developer"的情况——目前已知为零；
• OpenAI 对 o1/o3 等推理模型推荐 developer role，默认 false 后这类模型会收到 system，功能等价但存在理论上的细微差异；在意者可用 per-model compat.supportsDeveloperRole: true 覆盖。

UI 开关建议（征询）

除了改默认值，建议在 设置 → 模型 的自定义提供方卡片里增加一个可见的 supportsDeveloperRole 开关（provider 级默认值 + 模型行 per-model 覆盖），写入 compat.supportsDeveloperRole。这样：

• 无需手改 settings.yaml，可发现、可操作；
• 为"默认 false 后仍需要 true"的少数端点提供 UI 逃生舱。

想请教社区：

1. 这个 UI 开关有必要吗？还是保持"高级参数留在 settings.yaml"的现状即可？
2. 如果要做，放在 provider 级还是 model 级（或两级都要）？
3. 默认值改为 false 是否还有我没想到的兼容性顾虑？

[weijiafu14]

你这两条我都同意，补一个来自另一套实现的旁证，正好支持你的第 1 条。

默认值这件事，"显式写入"比"检测后回落"更可靠。

我维护的桥在把包自带的 provider 定义翻译成官方 llm-pi-ai profile 时，走的是显式写入 compat 三字段这条路——由包的作者声明端点到底支不支持，而不经过 detectCompat 的名单判断。原因跟你说的一模一样：isNonStandard 是一份枚举，而端点是无穷的，任何基于名单的默认值都必然对名单外的新端点判错，而且判错的方向是"假定支持"，代价是一请求就 400。

所以你提的"默认改 false"我认为方向对。更彻底一点的形状是：让声明成为必填而不是有默认值——自定义 provider 在配置时必须表态支不支持 developer 角色，写错了是配置问题，比"没写、系统猜、猜错"要好排查得多。当然那是 breaking change，默认改 false 是成本低得多的中间态。

第 2 条（UI 没有 compat 开关）不只是 compat。 同一个形状在别处也在发生：input（多模态）、reasoningEfforts（思考档位）这些字段在 llm-pi-ai 的 settings 里都是有的，但添加模型的表单没覆盖，用户只能手改 yaml（#3965、#3284、#4044 都是这件事）。所以这可能不该是"给 compat 加个开关"，而是"模型配置表单缺了一整层字段"——按这个角度提，也许比逐个字段加更容易被接受。

第 3 条那个误导性报错值得单独强调：CONTEXT_WINDOW_EXCEEDED 出现在实际上下文很小的时候，会把人往完全错误的方向带。"400 no body 被翻译成一个具体的语义错误码"本身就是缺陷——没有 body 的时候，如实报"上游返回 400、无响应体"远比猜一个错误码有用。这条我觉得比默认值那条更值得修。

我这边不涉及的部分：我们不修 dsh-llm-pi-ai，也不改 DSH 的设置页。上面全是对你提案的旁证和角度补充。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。第一段说的是它内部的做法，不需要你装任何东西——你已经用 settings.yaml 解决了自己的问题，这里只是给你的提案添证据。

[hairyf]

我们在 dsh-tauri 中支持了模型配置的更多选项，以及自动配置的功能：