[Desktop 0.2.1-rc.2] 旧 inject 服务名令第三方插件静默 pending，侧栏 API 全量空体 405（复现 / 根因 / 修复路径 / 可诊断性建议）

[nuke09040317-commits]

环境

• DSH Desktop 0.2.1-rc.2（win-x64，安装版；resources/app.asar 内版本号与全部 @deepseek-ai/dsh-* 依赖 pin 均为 0.2.1-rc.2；桌面 nightly 通道自动更新）
• profile：desktop；Windows 11；运行时为安装包自带 Node 24
• 第三方插件（本机实测）：dsh-better-sidebar@0.24.1、dsh-univer-office@0.3.6、dshmarket@1.66.8
• 升级路径：桌面 nightly 0.2.0-rc.2 → 0.2.1-rc.2（自动更新完成、未改动任何插件）

现象

侧边栏里打开任意 Markdown 文件，预览区只显示红字 HTTP 405；同一插件的文件树刷新、git、编辑保存等数据面板一并失效，但插件 tab 与编辑器 UI 仍然渲染（能显示文件名与路径）。聊天主界面正常。

抓包（Electron DevTools 等价结果）：

POST http://127.0.0.1:<port>/sidebar/api/fs.read   405 (Method Not Allowed)   ← 响应体为空
POST http://127.0.0.1:<port>/sidebar/api/fs.tree   405
GET  http://127.0.0.1:<port>/sidebar/api/...       404
WS   ws://127.0.0.1:<port>/sidebar/ws/fs-watch      握手失败（连接被关闭）

插件前端把「非 {ok:...} JSON 的响应」统一兜底成 HTTP ${status}，所以用户最终只看到 HTTP 405，无法从 UI 判断是宿主没挂载插件，还是插件路由写错。

根因链

1. 0.2.1 起 Web 侧公开服务 webRuntime 被删除（现役服务是 webStartup；`0.2.1-alpha.2` 删除了公开服务 `webRuntime`，但迁移指南挂在了 `v0.2.1-alpha.1` 目录下，release notes 也无提示｜breaking change without an entry of its own #9598 已记录这个 breaking change 的文档归属问题）。
2. dsh-better-sidebar@0.24.1 仍声明 inject = ["webServer", "sessions", "webRuntime", "tools"]，请求栅栏里也仍读 ctx.webRuntime.trustedHosts。
3. ⇒ 插件条目永远停在 pending (waiting for service: webRuntime)；宿主只打一行 dsh: warning: 1 entry did not activate，桌面用户看不到 stderr。
4. ⇒ 该插件的宿主半包从未挂载：/sidebar/api、/sidebar/file、/sidebar/html、/sidebar/bundle、/sidebar/ws/* 全部没有注册；而客户端半包照常加载并渲染 UI。于是每个 POST 落到宿主静态兜底（只收 GET）→ 空体 405，GET → 404，WebSocket 升级握手失败。
5. 结果：UI 看起来「正常」，但该插件的所有 API 调用全部失败，且失败原因被 HTTP 405 完全掩盖。

快速自检（约 1 分钟，可复跑）

• 宿主启动 stderr（桌面版通常不可见）：pending (waiting for service: webRuntime) / 1 entry did not activate。
• 宿主 asar 里 webRuntime 0 命中、webStartup 多处命中：

  rg "webRuntime|webStartup" F:\<dsh-install>\resources\app.asar
  

• 插件包内引用点（3 处）：

  rg -n "webRuntime" ~/.dsh/profiles/desktop/node_modules/dsh-better-sidebar/lib/index.js
  # inject 数组 / ctx.webRuntime.trustedHosts / 注释
  

• 关键点：--dump-config、peer 检查、行加载全部是绿的 —— 现有静态检查无法发现这条故障。

修复路径（按推荐度）

1. 升级插件（长期解）：dsh-better-sidebar 升到 0.28.0（npm latest；devDependencies 钉 @deepseek-ai/dsh-* 0.2.1-rc.1、peer ^0.2.1-rc.1，客户端 inject 面已不再依赖 webRuntime），然后重启 DSH。注意：升级/重装会覆盖下面第 2 条的热修。
2. 本地热修（社区已在 0.24.1 / 0.25.0 / 0.26.1 多平台验证，见插件仓 bug: v4 flash 模型跑任务，一致报错工具不可调用 #931）：改 lib/index.js 3 处 webRuntime → webStartup（inject 项、ctx.webRuntime.trustedHosts、注释），完全退出 DSH 再启动（宿主插件树只在启动时组装）。
   本机已按第 2 条处理，重启后我会回来补充结果。

给宿主侧的建议（桌面场景优先）

1. 迁移窗口的兼容别名：把 webRuntime 保留为 deprecated alias 一个 minor（读取时打一次性 warning 并指向迁移指南）；或让 loader 在「inject 的服务名不存在」时给出比 pending 更明确的提示（缺失服务名 + 迁移指南链接）。现在这条 breaking change 只能靠翻源码、翻 alpha 目录里的指南才能发现（`0.2.1-alpha.2` 删除了公开服务 `webRuntime`，但迁移指南挂在了 `v0.2.1-alpha.1` 目录下，release notes 也无提示｜breaking change without an entry of its own #9598）。
2. 桌面可见诊断：桌面版没有 stderr 可见性，health 仍回 200（[Feature] An entry that fails to activate is only a launcher warning while health stays 200 — make it fatal or visible to readiness #9067 已从 readiness 角度提过）。建议在设置 → 插件页/通知中心把 pending (waiting for service: X) 的条目显示为「未激活：缺少服务 X」，并提供一键复制诊断；dsh doctor 增加 inactive-entry 检查。
3. 兜底响应可诊断：未匹配的 API 形态路径（如 POST /xxx/api/*）被静态兜底后返回空体 405，会让插件作者与用户都误以为「插件路由方法写错」。建议返回结构化错误体（例如 {"error":{"code":"route-not-found","message":"no plugin route registered for POST /sidebar/api/..."}}），或至少非空 body 并提示「宿主可能未挂载该插件」。
4. 自动更新通道的兼容预检：桌面 nightly 自动升级时，对已安装插件的 inject 做一次只读预检，升级后在 GUI 提示「N 个插件需要更新以适配本版本」，不阻塞启动即可。

关联

• `0.2.1-alpha.2` 删除了公开服务 `webRuntime`，但迁移指南挂在了 `v0.2.1-alpha.1` 目录下，release notes 也无提示｜breaking change without an entry of its own #9598 —— 同根因：0.2.1-alpha.2 删除 webRuntime、迁移指南挂在 v0.2.1-alpha.1 目录下、release notes 无提示
• [Feature] An entry that fails to activate is only a launcher warning while health stays 200 — make it fatal or visible to readiness #9067 —— pending 条目仅 launcher warning、health 仍 200 的 readiness 问题
• 插件侧：omdsh-dev/DSH-better-sidebar bug: v4 flash 模型跑任务，一致报错工具不可调用 #931（含已验证热修与 0.2.1-rc.1/rc.2 复现）、ds你自己都不在源码上支持切换思维等级。本轮运行失败The `reasoning_content` in the thinking mode must be passed back to the API. INVALID_REQUEST #906

English summary

On DSH Desktop 0.2.1-rc.2 (Windows, nightly channel), dsh-better-sidebar@0.24.1 never activates because it still injects the removed webRuntime service (0.2.1 provides webStartup). The host only logs 1 entry did not activate / pending (waiting for service: webRuntime), which desktop users cannot see; the plugin's host half never mounts, so every /sidebar/api/* POST hits the static fallback and returns an empty-body 405 (GET 404, WS handshake fails) while the client half keeps rendering and surfaces only HTTP 405 in the UI. Fix: upgrade the plugin to 0.28.0 (built against dsh 0.2.1-rc.1), or hot-patch the three webRuntime references to webStartup in lib/index.js and restart. Host-side asks: (a) a deprecation alias or a precise loader diagnostic for unknown injected services; (b) desktop-visible pending-plugin diagnostics (settings/plugin page, dsh doctor); (c) a structured JSON fallback for unmatched API-like paths instead of a bare empty 405; (d) an upgrade-time read-only compatibility precheck over installed plugins' inject lists, reported in the GUI without blocking startup.

[argszero]

Your root-cause chain is right in every step, and the source shows two of them more sharply than the report does. There is also one item on your suggestion list that is already answered — a plugin now files the report the host composes and never writes.

What the source says

webRuntime is gone, not deprecated. It has zero hits in shipped source (packages/*/*/src, apps/*/src) at 687f282e86. The removal is documented, and documented in exactly the place you said was hard to find — docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.md: "A profile, overlay, or --patch file that injects webRuntime now waits for a service that never mounts, and an expression reading ctx.webRuntime.trustedHosts fails to evaluate, so the required Connection cannot start."

The pending state is not a soft failure — it is permanent. A pending fiber's own inject map is the only thing consulted: packages/boot/app-boot/src/index.ts:1072-1074 computes missing as Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined). Nothing re-evaluates an entry after the tree settles, so an entry injecting a name that no row provides stays pending for the life of the process. Your 0.24.1 plugin is not "temporarily inactive"; it can never activate in 0.2.1.

The message you read is one line, and the informative version exists but is unreachable for you. auditStartupEntries (:1153-1167) marks an entry required only when it is the bootstrap Include or its id is in requiredStartupEntryIds — a third-party id can never be in that set. So:

• optional entries → activationDiagnostic (:1092) → dsh: warning: 1 entry did not activate plus <id> (<name>): pending (waiting for service: webRuntime), one line to stderr (:1166);
• required entries → startupDiagnostic (:1114) → a grouped table with a Missing services column, the format you asked for in suggestion 2. It is produced only on the fatal path (:1162), so a healthy application can never print it.

That is the whole gap between your suggestion 2 and the shipped code: the diagnostic you want is already written, and only the branch that chooses warn instead of fail keeps it out of reach.

The 405 comes from the static fallback, as you guessed. packages/host/frontend-static/src/index.ts:122-125: "Non-GET/HEAD without a matching named route is 405 (fallback-only)" — an empty body, because the handler writes the head and ends. A POST to /sidebar/api/* therefore renders as 405 with no JSON, which is why your client's generic fallback cannot tell "no route" from "wrong method". Your suggestion 3 is the fix with the best ratio: any non-empty structured body would have named the cause on the first try.

One correction: dsh doctor does not exist at 687f282e86 (apps/cli/src/args.ts has no such mode), so suggestion 2's second half targets something to be built rather than something to extend. dsh --dump-config is the nearest existing diagnostic, and it is deliberately green in your failure mode — the composition is valid; the services are absent.

Your suggestion 2 already has an implementation

I maintain @argszero/dsh-activation-doctor (0.3.0), written for the same class of loss:

• https://github.com/argszero/dsh-activation-doctor
• npm install github:argszero/dsh-activation-doctor (npm publish is pending on my side — the registry has been unreachable from here for a while)

It subscribes to internal/status (vendor/cordis/src/events.ts:333, still present at this head), sweeps ctx.loader.entries() after the tree settles, awaits every fiber to recover the original error, and files a durable report under $DSH_HOME/logs/. For the state in your report it prints the row you asked the settings page for: pending — "waiting for a service; the missing service names are reported", includePending defaulting to true. It also covers two losses your case does not reach: a bundle the profile names but the process did not start from (recovered from loadProfileDirectory(...).skippedBundles, so no dependency is declared on app-boot), and a package that is installed but never selected into dsh.profile.bundles.

It is a detector, not a repairer: it cannot revive your 0.24.1 plugin and it cannot make the desktop shell's stderr visible. It does mean that the next occurrence names the plugin, the missing service and the entry id in a file you can open.

On the compatibility alias

Suggestion 1 is the one I would not do. webRuntime → webStartup also changed the shape of the value (trustedHosts semantics, lanAddresses removed), so an alias would have to answer differently for different consumers — and an alias that returns a plausible-but-wrong object inside a trust fence is worse than a pending entry. The upgrade guide plus a visible inactive-entry report is the honest pair; both halves now exist, one shipped and one as a plugin.