[BUG]Upgrade from rc.6 to 0.1.2-rc.1: models page dead until restart + lazy client bundle race

[freeze892]

Feedback: DeepSeek Harness 0.1.2-rc.1 — upgrade & plugin ecosystem issues

环境：macOS · dsh 由 0.1.0-rc.6 升级到 0.1.2-rc.1（npx 缓存整体替换）· profile: web
时间：2026-08-17 ~ 2026-09-04 · 反馈人希望帮助改善 rc 阶段的升级体验

摘要 / TL;DR

rc 阶段升级 + 第三方插件 = 连续两次"装完/升完才炸、还要外部工具救场"。以下 3 个问题若能解决，能大幅减少这类事故。

---

1.【高】升级后「模型设置页」僵死：provider 全空、点不动、无报错；重启才恢复

现象：从 0.1.0-rc.6 升级到 0.1.2-rc.1（期间 profile 被重装、多个插件升级）后：

• 聊天模型选择器只剩 deepseek；
• Settings → Models 页：之前配置过的 provider（zai/zhipu/kimi 等，settings.yaml 中仍在）全部不显示；
• 在 Models 页新增/编辑 provider 点了没反应，且没有任何报错；
• 完整重启 dsh 后一切恢复（provider 回来了、也能新增保存了）。

诊断线索：

• settings.yaml 中 llm-pi-ai.providers 内容完整、分区名未变（新版仍是 llm-pi-ai），pi-ai 内置目录（@earendil-works/pi-ai）也包含这些 provider id；
• 因此更像是运行实例在热更新/升级迁移后处于坏状态：设置注册静默失败、UI 保存静默 no-op，无任何日志/报错可查。

建议：a) 设置热更新失败时给出可见错误并自动回退/提示重启；b) 升级迁移后主动校验 llm 目录注册状态并上报；c) Models 页保存失败不要静默。

2.【中】重启后首个页面加载的竞态：懒加载 client 插件报 failed to load，且不重试

现象（0.1.0-rc.6 时也出现过）：

failed to import loader entry 89315beb (@deepseek-ai/dsh-client-ui-input-trigger):
client-modules: bundle script /plugins/@deepseek-ai/dsh-client-ui-input-trigger/client.js?rev=0bd00b04060f failed to load

发生时机：dsh 重启后、服务器尚未完全就绪时，浏览器（旧页面自动重连/手动刷新）去拉非 immediately 的懒加载 client 条目，请求落空 → <script> error → 该条目一次性失败，无自动重试。强刷一次即好，文件哈希与 rev 均一致（已核实非文件损坏）。

建议：懒加载 bundle 拉取失败时自动重试 N 次（或指数退避）；启动窗口内对静态资源请求排队/等待目录就绪。

3.【中】rc 升级与第三方插件的兼容性对用户不可见：引用已删除包、peer 语义含糊

现象：

• dsh 升级后，第三方插件常引用已被本版本删除/更名的客户端包（实例：dsh-client-store、dsh-client-ui-primitives、dsh-client-ui-slots 在 0.1.2-rc.1 已不存在，插件 0.1.15 仍 require 它们）→ 客户端加载才炸，引导期无提示；
• 插件 peer 范围语义含糊（例：^0.1.0-rc.8 || ^0.1.1-rc.1 与运行中的 0.1.2-rc.1 按严格 semver 预发布规则"不满足"，实际可用），用户无法判断"这插件到底认不认当前 rc"；
• @deepseek-ai/* 内部包 peer 全部锁同一 rc，升级时任何一边不同步都牵连全局。

建议：a) 启动/升级时做一次"插件兼容矩阵"检查（当前 dsh rc vs 每个插件的 peer/依赖声明），在 Settings→Plugins 或启动页给出清单级红黄绿，而不是等运行时报错；b) 让 peer 范围表达"支持到哪个 rc"更宽松或提供运行时实际校验；c) 引导第三方插件作者在 release 时声明目标 rc（发布元数据里带 dsh 兼容字段）。

---

附：对用户的建议（非 bug）

• 升级 dsh 前对 ~/.dsh/profiles/<p> 与 settings.yaml 做快照，出问题一条命令回滚；
• 大版本/rc 升级后如 Models 页异常，先完整重启一次再排查配置；
• 当前已通过把 llm-pi-ai.providers 全部写成显式 api+baseURL+models（不依赖目录兜底）加固，规避了目录/校验不确定性。

[argszero]

Excellent, well-structured report. I dug into #5603 (very similar "models page silently dead" report) and want to bridge the two — issue #1 here is very likely the same silent-registration-failure root cause, but your trigger is different and worth distinguishing for upstream.

Issue #1 — the "models page dead after upgrade" is almost certainly the same mechanism I traced for #5603.

The path is llm-pi-ai → settings.installSection(ctx, 'llm-pi-ai', Config, config, { validate: assertServiceable, ... }). Inside settings.register (packages/settings/settings/src/index.ts:436):

resolved: deepFreeze(this.resolve(schema, options?.base, this.section(parsedNs), options?.validate)),

This runs synchronously during register(), before the effect. If validate throws (and assertServiceable → resolveProfiles → resolveRouteModels throws on a route whose model can't be served), the throw aborts registration, the namespace never lands in registrations, describe silently omits it, and downstream the Models UI is gated off (it only renders the add flow when state.namespaces.get(...) exists). No log, no UI error — exactly what you saw.

The distinguishing variable is what makes resolveRouteModels throw. In #5603 it was a retired catalog model id (grok-4.5). Here you note the providers are intact and even in the catalog — so if it is the same mechanism, your throw is coming from a different validation branch: a custom/third-party provider route that relies on catalog fallback for api/baseURL can throw when the catalog can't supply those. That's precisely why your mitigation — "write every provider as explicit api+baseURL+models, don't rely on catalog fallback" — fixes it: it removes the throw by making the route self-describing. I'd frame it that way in the upstream issue: the defect isn't that a provider is "wrong", it's that a route which legitimately needs catalog fallback can silently kill the whole llm-pi-ai namespace on one unservable entry.

Issue #2 (lazy-load race) — confirmed gap, no retry. The client-module bundle loader (packages/client/modules) has no retry/backoff for a failed <script> fetch during the startup window; a single miss marks the entry failed with no retry. A bounded retry (or queuing static requests until the server's directory is ready) is a clean fix. Client-side.

Issue #3 (plugin compat matrix) — this is a real, recurring ecosystem pain. It maps exactly to two known upstream problems: (a) the stale @deepseek-ai/dsh-* latest dist-tag (frozen at 0.0.1-rc.1; the real line is next=0.1.2-rc.1) and (b) strict pre-release semver making ^0.1.0-rc.8 || ^0.1.1-rc.1 unsatisfiable against 0.1.2-rc.1 even though it works. A startup/upgrade "compatibility matrix" check in Settings→Plugins (red/yellow/green per plugin vs. current dsh rc) is exactly the right ask, and the peer-range matching logic should compare against the resolved version, not reject on strict pre-release rules.

Concrete upstream framing for all three: the common thread is silent failure with no degradation and no observability. All three would be substantially improved by "fail loudly with a visible error + graceful fallback" at the point of failure (settings registration, bundle load, plugin compat resolution) rather than a silent no-op.

I'm happy to help verify the exact resolveRouteModels throw branch for your specific custom-provider config if you can share the llm-pi-ai.providers shape that reproduces it — that would pin whether it's the catalog-fallback api/baseURL branch or something else.