Configuring Bailian Token Plan via custom provider silently breaks: schema rejection, missing developer compat, and unintuitive models replacement semantics

[zhaoshan987-eng]

Environment

• DSH Desktop: 2.0.1
• Harness: 0.1.0-rc.7
• pi-ai: bundled with desktop
• Provider endpoint: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 (Bailian Token Plan CN)
• OS: Windows

Summary

When a user manually configures the Bailian Token Plan endpoint as a custom provider (instead of using the built-in qwen-token-plan-cn catalog route), they encounter three cascading failures that are extremely difficult to diagnose:

1. Reasoning effort selector does not appear for any model
2. developer role 400 error from the Bailian API
3. "API key is invalid" after attempting to fix #2 by adding compat.supportsDeveloperRole: false at the route level

All three stem from configuration-layer UX issues in dsh-llm-pi-ai, not from the Bailian API itself. The built-in qwen-token-plan-cn catalog route handles all of these correctly, but there is no GUI guidance to use it.

Detailed Reproduction

Step 1: User adds Bailian as a custom provider

This is the natural first approach — the GUI offers "Add Custom Provider" but does not surface the built-in qwen-token-plan-cn catalog route:

llm-pi-ai:
  providers:
    aibaba:
      displayName: Bailian
      apiKeyEnv: AIBABA_API_KEY
      api: openai-completions
      baseURL: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3.7-max
        - id: deepseek-v4-pro
        # ... more models

Result: No reasoning effort selector appears for any model. The models work for basic chat, but reasoning capability is invisible.

Root cause: Hand-declared models have no reasoning metadata. The settings-models UI deliberately does not expose reasoningEfforts editing (source comment: "There is deliberately no reasoning-effort control, here or on the editor"). Without reasoningEfforts, resolveModelReasoning returns {reasoning: false} → reasoningInfo() returns {} → UI hides the selector.

Step 2: User encounters developer role 400 error

After extended multi-turn usage, requests fail with:

400 {"error":{"code":"invalid_parameter_error","message":"developer is not one of ['system', 'assistant', 'user', 'tool', 'function']"}}

Root cause: detectCompat() in openai-completions.js defaults supportsDeveloperRole: true for the Bailian URL (it's not in the isNonStandard list). The built-in catalog explicitly sets supportsDeveloperRole: false for every Bailian model, but hand-declared routes lose this metadata. When model.reasoning && compat.supportsDeveloperRole evaluates to true, DSH sends role: "developer" which Bailian rejects.

Step 3: User tries to fix it and makes things worse

Attempting to add compat.supportsDeveloperRole: false at the route level:

qwen-token-plan-cn:
  displayName: Bailian
  apiKeyEnv: AIBABA_API_KEY
  compat:
    supportsDeveloperRole: false   # ← NOT in compatProfile schema
  models:
    - id: wan2.7-image
    # ...

Result: The entire llm-pi-ai provider section fails schema validation silently. The route is never registered. Subsequent requests fail with "API key is invalid" or "no adapter registered for provider qwen-token-plan-cn" — neither of which points to the actual cause (schema rejection).

Root cause: compatProfile only accepts thinkingFormat and supportsReasoningEffort. Writing any other field causes assertServiceable → resolveProfiles to throw. The onChange handler catches this and logs "keeping the previously registered routes after a refused update", but the user sees only the downstream symptom ("API key is invalid"), not the validation failure.

What Works (But Is Undiscoverable)

The built-in qwen-token-plan-cn catalog route handles everything correctly with just:

qwen-token-plan-cn:
  displayName: Bailian
  apiKeyEnv: AIBABA_API_KEY

No api, baseURL, models, or compat needed. All ~15 text models inherit correct reasoning metadata, supportsDeveloperRole: false, and DeepSeek's requiresReasoningContentOnAssistantMessages: true.

But there is no way for a user to discover this without reading source code.

Structural Limitation: models Replacement Semantics

Writing a models list on a catalog route completely replaces the built-in catalog (line 1139 of dsh-llm-pi-ai/lib/index.js):

const entries = configured.length > 0 ? configured : [...defaults.values()].map(...)

This means users cannot supplement the built-in catalog with additional models (e.g., image/audio models not in the catalog). They must choose between:

• Full built-in catalog (correct compat, but no custom models)
• Custom model list (loses all built-in metadata including critical compat flags)

There is no merge mode.

Suggested Improvements

1. Surface built-in catalog providers in the GUI

Add a "Use Built-in Provider" option in the Models settings page that lists available catalog routes (qwen-token-plan-cn, deepseek, etc.) alongside the manual "Add Custom Provider" flow. This would prevent users from ever needing to hand-configure endpoints that already have full catalog support.

2. Provide explicit errors on schema validation failure

When assertServiceable / resolveProfiles throws during onChange, the error should be surfaced to the user (toast notification, settings page banner, or at minimum a prominent log entry) rather than silently falling back to previous routes. The current behavior — logging "keeping the previously registered routes after a refused update" to the error log while the user sees an unrelated "API key is invalid" — makes diagnosis nearly impossible.

Specifically, when compatProfile rejects an unknown field like supportsDeveloperRole, the error message should name the invalid field and suggest valid alternatives.

3. Consider a models merge mode for catalog routes

Allow catalog routes to declare additional models without replacing the entire catalog. For example:

qwen-token-plan-cn:
  apiKeyEnv: AIBABA_API_KEY
  extraModels:           # merge instead of replace
    - id: wan2.7-image
    - id: qwen-audio-3.0-tts-plus

Or alternatively, allow per-model compat overrides on catalog routes so users can fix individual fields without losing the rest of the catalog metadata.

4. Document the compatProfile schema boundary

The fact that only thinkingFormat and supportsReasoningEffort are user-configurable compat fields is not documented anywhere visible to users. The other dozen+ compat fields (supportsDeveloperRole, requiresReasoningContentOnAssistantMessages, supportsStore, etc.) are internal-only but look like reasonable configuration options. A docs page or inline schema description listing allowed fields would prevent silent misconfiguration.

Impact

These issues affect any user who configures a provider endpoint that happens to have built-in catalog support but doesn't know to use the catalog route name. The Bailian Token Plan case is particularly painful because:

• The endpoint is widely used in China
• The developer role error only manifests after multi-turn usage (not on first request)
• The attempted fix (adding supportsDeveloperRole) triggers a completely different failure mode
• The error messages at each stage point in wrong directions

I've written a detailed troubleshooting guide based on my debugging experience that I'd be happy to contribute as documentation if helpful.

[denial123789]

I checked this across the tagged rc.7 and rc.8 sources. There is an important release boundary that changes the safest answer.

For rc.7, compatProfile exposes only thinkingFormat and supportsReasoningEffort; supportsDeveloperRole is not a valid user-configurable key. The least fragile recovery is therefore the minimal installed catalog route:

llm-pi-ai:
  providers:
    qwen-token-plan-cn:
      displayName: Bailian Token Plan CN
      apiKeyEnv: AIBABA_API_KEY

Omitting api, baseURL, and models preserves the installed endpoint, model metadata, reasoning levels, and vendor compatibility. A 400 that explicitly rejects developer also proves the request reached and authenticated with the provider; it should not be diagnosed first as an invalid key.

rc.8 expands the configurable compat schema and does include supportsDeveloperRole, so a genuinely custom openai-completions route can set it to false. rc.8 also documents modelOverrides: it can adjust one installed catalog model while retaining the rest. It does not add an unknown model, cannot coexist with a replacing models list, and models remains full replacement rather than append.

I published a version-aware runbook with the exact failure classification, minimal route, replacement/override rules, custom-model workflow, rollback, and acceptance gates:
https://sandbaseai.github.io/deepseek-harness-handbook/bailian-token-plan.html

That distinction should keep rc.7 users from applying an rc.8-compatible field and then chasing the downstream registration/auth symptom.

[weijiafu14]

这帖的主要配置缺口在 rc.8/rc.2 已变化：当前 schema 已支持更多 compat 字段。另需注意 models 数组整体替换目录而非追加；复用内置 Bailian catalog 时，最小 route 覆盖通常更稳。升级后验证 reasoning 元数据、system 角色和明确 schema 错误。