[BUG] dsh 0.1.2-rc.1 Settings→Models "Add provider" 静默失效

[zealta]

上游缺陷报告：dsh 0.1.2-rc.1 Settings→Models "Add provider" 静默失效

状态：待上报上游（deepseek-ai/deepseek-harness） · 日期：2026-09-04 · 影响版本：dsh 0.1.2-rc.1（web profile）/ pi-ai 0.84.4
验证环境：本仓库管理的 dsh web（127.0.0.1 直连与 auth-proxy 代理后均复现——与代理无关）

---

1. 现象（Symptoms）

设置 → 模型（Settings → Models）页面：

• 点击 Add provider：无任何反应——不弹对话框、不发请求、无 console 报错；
• Add a custom provider：按钮呈禁用态（disabled）；
• 已配置提供方的行内 Edit 正常可用（说明 React 事件与设置面板本身无问题）；
• 上述现象在 127.0.0.1 直连（原生 loopback、无任何中间层）与经 auth-proxy 访问时完全一致。

2. 复现步骤（Repro）

1. 在 旧版本（pi-ai catalog 尚含 grok-4.5 的 era，实测 8 月版本）通过 UI 为 opencode-go 提供方保存过自定义模型列表，其中含 grok-4.5（示例配置，实际为任意 catalog 已下线/不存在的 model id）：

   # ~/.dsh/settings.yaml
   llm-pi-ai:
     providers:
       opencode-go:
         apiKeyEnv: OPENCODE_GO_API_KEY
         models:
           - id: grok-4.5        # pi-ai 0.84.4 catalog 已下线（现为 grok-4.6）
             name: Grok 4.5
             contextWindow: 500000
             maxTokens: 500000

2. 升级到 dsh 0.1.2-rc.1（pi-ai 0.84.4）并重启 dsh web；

3. 打开 设置 → 模型：复现上述现象；

4. /api/settings/describe 响应中 namespaces 列表缺少 llm-pi-ai（实测 14 个，其余含 llm-deepseek 正常）。

反向验证（确定根因的数据实验）：

• 从 settings.yaml 移除整个 llm-pi-ai 段 → 重启 → describe 中 llm-pi-ai 回归（15 个），Add provider 恢复正常（含 41 个提供方的添加卡片）；
• 仅移除 models 中的 grok-4.5 一条 → 同样恢复；
• catalog 对照：pi-ai 0.84.4 的 opencode-go 模型列表（25 个）中无 grok-4.5。

3. 根因（Root Cause）

链路（源码均为 dsh-v0.1.2-rc.1 tag）：

1. packages/llm/llm-pi-ai/src/index.ts：ctx.inject(['settings']) → settings.installSection(ctx, 'llm-pi-ai', Config, config, { validate: assertServiceable, ... })；
2. packages/llm/llm-pi-ai/src/config.ts：assertServiceable(config) → resolveProfiles(config.providers)——models 覆盖中 catalog 不存在的 model id 会使 resolve 抛错（注释明确：拒绝 "a schema-valid profile the adapter cannot serve"）；
3. packages/settings/settings/src/index.ts register()：resolved: deepFreeze(this.resolve(schema, base, section, validate)) 同步执行——存储段校验失败即抛错 → installSection 失败 → namespace 从未进入 registrations 表；
4. 上游缺陷面：注册失败完全静默——无日志（watcher/error 路径均不触发）、describe 直接缺该 namespace、UI 无任何错误呈现；
5. packages/client/ui-settings-models/src/client/ModelsSection.tsx：点击 Add provider → setAdding(true)/setEditing(addable[0])，但渲染条件 addTarget !== undefined && addNamespace !== undefined（addNamespace = state.namespaces.get(addTarget.settingsNs)）不满足 → 回落到按钮区 → UI 静默无响应；同页 protocols = protocolChoices(state.namespaces.get('llm-pi-ai'), …) 为空 → Add a custom provider 禁用。

一句话：catalog 模型下线使旧配置校验失败 → llm-pi-ai settings namespace 注册整体失败且静默 → 依赖该 namespace 的整个 Models 添加流失效。

4. 影响（Impact）

• 无法通过 UI 添加任何新提供方（官方适配器与自定义均不可用）；
• 已配置提供方行（如 opencode-go）也不在目录中呈现为可管理行；
• 无任何错误提示，用户与运维均不可见；
• 属于"旧配置 + 升级"的常见场景（模型下线/改名在 LLM 领域高频发生），影响面大。

5. 期望行为（Expected）

1. 容错：resolveProfiles/schema 校验对"catalog 已不存在的自定义 model id"降级（warn + 保留可服务部分 / 提示失效条目），而非整体拒绝注册；
2. 可观测：settings namespace 注册失败至少输出 warn 日志并在配置 UI 呈现错误；describe 不应静默缺失；
3. 迁移：catalog 模型下线时提供迁移容忍或 UI 标注"已失效模型"。

6. 上游 issue 草稿（可直接粘贴 GitHub）

### Title
dsh 0.1.2-rc.1: Settings → Models "Add provider" silently does nothing when a saved custom model list references a retired catalog model id

### Environment
- dsh 0.1.2-rc.1 (web profile), pi-ai 0.84.4
- Reproduced both via direct loopback (127.0.0.1) and behind a reverse proxy — independent of deployment

### Repro
1. On an older build, configure a provider (e.g. opencode-go) through the Models UI with a custom `models` list containing an id that no longer exists in the pi-ai catalog (e.g. `grok-4.5`, retired in favor of `grok-4.6` in pi-ai 0.84.4).
2. Upgrade to 0.1.2-rc.1 and restart `dsh web`.
3. Open Settings → Models:
   - Clicking "Add provider" does nothing (no dialog, no request, no console error).
   - "Add a custom provider" is disabled.
4. `/api/settings/describe` lists 14 namespaces; `llm-pi-ai` is missing (`llm-deepseek` is present).

Removing the `llm-pi-ai` section (or just the `grok-4.5` entry) from `settings.yaml` and restarting restores the namespace and the whole add flow.

### Root cause
- `llm-pi-ai` registers its settings namespace via `installSection` with `validate: assertServiceable` → `resolveProfiles`. A custom model id absent from the pi-ai catalog makes this throw.
- `settings.register()` resolves the stored section synchronously; the throw aborts registration entirely (comment: "An invalid stored section fails the registration itself").
- The failure is silent: no log, no UI error; `describe` simply omits the namespace.
- `ui-settings-models` renders the add UI only when `state.namespaces.get(addTarget.settingsNs)` exists and derives custom-provider protocols from the same namespace — both gone → clicks no-op and the custom button is disabled.

### Expected
- Degrade gracefully when a stored custom model list references a retired catalog id (warn, keep the serviceable parts, surface the stale entries) instead of failing the whole namespace registration.
- Log a warning when a settings namespace registration fails; surfaces should show the error instead of silently dropping the section.
- Consider a migration path when catalog models are retired.

7. 本仓库缓解措施（已在部署侧修复数据）

• ~/.dsh/settings.yaml：移除 llm-pi-ai.providers.opencode-go.models 中已下线的 grok-4.5（其余 15 个自定义模型保留）；
• 修复后 describe 恢复 15 个 namespaces，Add provider / Add a custom provider 全部可用。

[argszero]

Confirmed against master (76fda72979) — your root cause holds, and I'd sharpen one gate so the report is airtight for upstream.

Source trace confirms the failure is real and silent.

llm-pi-ai registers its namespace via settings.installSection(ctx, 'llm-pi-ai', Config, config, { validate: assertServiceable, ... }), and assertServiceable runs resolveProfiles(config.providers) (config.ts:356-357). For each provider, resolveProfiles calls resolveRouteModels(...) (config.ts:400+, catalog.ts:797).

The model-validity gate is the interesting part. In resolveRouteModels (catalog.ts:886-891), a model id absent from the installed catalog resolves through three fallbacks:

const api     = request.api ?? base?.api ?? routeApi
const baseUrl = request.baseURL ?? base?.baseUrl ?? providerBaseUrl

where base = defaults.get(id) is undefined for a retired id like grok-4.5. So a catalog-missing model only throws when the route also declares neither api nor baseURL:

if (api === undefined)     invalid(provider, `model "${entry.id}" needs an api; ...`)
if (baseUrl === undefined) invalid(provider, `model "${entry.id}" needs a baseURL; ...`)

routeApi comes from sharedCatalogApi(defaults) (catalog.ts:631), which is undefined whenever the provider's catalog spans more than one wire protocol. So for opencode-go (whose 25 models span multiple apis), a stale grok-4.5 entry with no route-level api/baseURL hits api === undefined → invalid(...) throws → the whole llm-pi-ai namespace registration aborts.

The add-provider UI then no-ops for a mechanical reason: ui-settings-models renders the add flow only when state.namespaces.get(addTarget.settingsNs) exists, and derives custom-provider protocols from that same namespace (protocols = protocolChoices(state.namespaces.get('llm-pi-ai'), …)). With llm-pi-ai silently absent from describe, both the add dialog and the custom-provider button are gated off.

The real defect is the silent whole-namespace abort, two ways:

1. assertServiceable (a settings-validation hook) is being used to reject the stored config because of one stale catalog id — comment in settings register() literally says "An invalid stored section fails the registration itself," but that string appears in the validator path for store-time validation, not load-time. A retired catalog id is not a malformed stored section; it's a drift that should degrade (warn + keep the serviceable entries / surface stale ones) rather than fail the namespace.
2. The failure is invisible — no log, no describe entry, no UI error. That's an observability gap regardless of the degrade decision.

Your mitigation (remove the stale entry, or the whole section) is correct and matches exactly where the throw fires. Upstream-wise, I'd frame the fix as: catalog drift on a configured model list should not make the whole settings namespace unserviceable — resolve it per-model (warn + drop the unreachable entry, or surface it as "invalid model") instead of failing resolveProfiles, and log a warning when a settings namespace registration fails so it's never silent.

One thing to double-check before you file upstream: whether opencode-go's pi-ai catalog actually spans multiple apis (which is what makes routeApi undefined here). If it's single-api, routeApi is defined and the api fallback would save it — then the throw would be baseURL-gated instead. Either way the reporter's conclusion (silent whole-namespace abort on a stale id) is correct; only the exact offending field differs.

[KYinCode]

+1 — 在 0.1.2-rc.1（Windows，pi-ai 0.84.4）上完整复现了同样的问题：升级前目录里还有 grok-4.5，升级后我配置的自定义 provider（opencode-go、opencode、longcat）全部消失，settings/describe 里没有 llm-pi-ai 命名空间，Add provider 点了没反应，Add a custom provider 是禁用状态。删掉过期的 grok-4.5（改成 grok-4.6）并重启后恢复正常。

回答 @argszero 留下的待核实问题：我在本地核实过，opencode-go 的内置目录确实横跨多种协议——anthropic-messages（minimax-m3、qwen3.8-flash）、openai-completions（20 个模型，含 deepseek-v4-flash、glm-5.x、kimi-*、qwen3.x）、openai-responses（gpt-5.6-luna、grok-4.6、muse-spark-1.2-contributor）。所以 sharedCatalogApi 确实为 undefined，过期的模型 ID 在路由没写 api/baseURL 时就会抛 needs an api。分析结论确认无误。

同意修复方向应该是逐模型降级（警告 + 保留可用条目 / 标记失效条目），并在 settings 命名空间注册失败时打一条警告日志。另外补充一点：这个失败只显示在终端（stderr），UI 里完全没有提示——升级 CLI 的用户根本不知道自己的 provider 为什么消失了。希望上游尽快处理。