# DSH Desktop 0.2.1-rc.3 升级后起不来（vault 适配层被静默禁用）

日期：2026-10-26
环境：macOS，DeepSeek Harness 0.2.1-rc.2 → 0.2.1-rc.3（Electron 44.7.0 / Node 24.21.0）

## 现象

升级后桌面端窗口空白，无法使用。崩溃日志只有渲染端聚合错误：

```
web boot: 33 entries did not activate
@deepseek-ai/dsh-client-ui-session: pending (waiting for service: sessions)
@deepseek-ai/dsh-client-ui-sidebar: pending (waiting for service: uiWorkspace)
dsh-vault-plugin: pending (waiting for service: sessions)
…（共 33 条，全部 pending，无 failed）
```

关键特征：**没有任何 entry 处于 failed**，缺的服务恰好是 vault 适配层那四个包提供的
（`sessions` / `uiWorkspace` / `uiConversation` / `sidebarRight`）。

## 排查路径（以及两条弯路）

1. `node compat/probe-dsh.mjs` → 判定 **L1**：3 个 bundle 字节变了、锚点全中。
   按老经验这只需换 baseline hash。**这条经验在 rc.3 上不够**（见根因）。
2. 弯路 A：以为 overlay 是 rc.2 旧快照，逐字节对比 `lib/client.js` —— 结果
   `dsh-api-session-controller` 与 rc.3 原版**完全一致**，其余三个只差 patch 自身的行。
   排除「旧快照内容」假设。
3. 弯路 B：怀疑宿主 `lib/index.js` 的 `export * from file://…app.asar…` 在 rc.3 断了。
   用 Electron 的 Node 模式逐个 import，四个包全部 OK，排除。
4. 弯路 C：`dsh --profile desktop --dump-config` 被拒（desktop profile 由 Electron 独占）；
   复制成 `desktop-probe`（node_modules 软链）后 dump 成功 → 4 条 `vault-compat-*`
   insert 行**都在**组合树里，`disabled: true` 也正确生效。排除补丁未应用。
5. 决定性证据：把同一份 profile 用 CLI 启动 `dsh --profile desktop-probe`，
   宿主把**行级禁用**的原因打到了 stdout：

```
dsh: disabling profile plugin row "vault-compat-session-controller":
Plugin @deepseek-ai/dsh-api-session-controller@0.2.1-rc.2 is incompatible with
dsh 0.2.1-rc.3: requirements { …31 项，全部 0.2.1-rc.2… }
Exact-version exemption: not active.
```

## 根因

0.2.1-rc.3 新增**插件 peer 版本门禁**：profile 行所属 package 的
`peerDependencies` 若精确锁在非当前版本，该行被**静默禁用** —— 不是 boot 错误、
不进崩溃日志，只留一行宿主日志。

rc.2 overlay 的 `package.json` 是 `0.2.1-rc.2` 且 31 个 peer 全部精确锁 rc.2，
于是 session-controller 行被丢。它不提供 `sessions`，`uiSession` / `uiWorkspace` /
`uiConversation` 全部排队等待，最终 33 条 pending。

另三个包只 pin `@deepseek-ai/cordis`（`~4.0.5`，范围），所以只有一条被禁用 ——
这也解释了为什么日志里只提 session-controller 一次。

**正确修法不是 `dsh plugin allow-version`**（那是让 rc.2 宿主语义跑在 rc.3 Host 上，
等于把旧快照问题换个入口再犯一次），而是用「已安装版本」的 fixture 重新生成 overlay：
`prepare-overlay.mjs` 会复制 fixture 的 `package.json`，版本与 peer 自动变 rc.3，门禁自过。

## 修复步骤（已执行）

```sh
cp -R compat/dsh-v0.2.1-rc.2 compat/dsh-v0.2.1-rc.3      # 补丁逻辑一行没改
# 写入 probe 给出的 4 个新 hash（session-controller 未变）
DSH_CLIENT_FIXTURE=.cache/dsh-v0.2.1-rc3-fixture \
  node --test compat/dsh-v0.2.1-rc.3/compat.test.mjs      # 4/4 pass
node compat/dsh-v0.2.1-rc.3/prepare-overlay.mjs \
  .cache/dsh-v0.2.1-rc3-fixture ~/.dsh/plugin-packages/vault-desktop-021rc3 \
  "/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules"
# cordis.patch.yml 的 4 条 insert 指向 vault-desktop-021rc3（先备份 .bak-<ts>）
```

验证：

- CLI 复刻启动：`disabling profile plugin row` 0 条、`did not activate` 0 条，`dsh web` 正常
- 桌面端重启：无新增 `crash-*-web-boot.log`，宿主端口正常监听
- `POST /dsh-vault/api` → 403（originless 被拒 = 路由已挂载）
- `node compat/probe-dsh.mjs` → 两道门禁全过，exit 0

## 沉淀

- `probe-dsh.mjs` 现在查两道门禁，新增 **L1-O** 判定：补丁字节匹配但 overlay 版本过期，
  并打印「重生成 overlay + 改 insert 路径」的动作提示。可用第三个参数指定 profile 文件
  来验证故障态。
- 桌面端崩溃日志只收渲染端 `error` 级输出，**宿主行级禁用永远不在里面**。
  升级后要判定这类问题，直接 CLI 复刻 profile 启动看 stdout，或用
  `--dump-config`（desktop 需复制成非保留名）。
- 绝对路径的 insert 行 + 版本命名 overlay 目录：每次升级必须一起改，否则静默失效。