插件救援 bi8boJ/dsh-rescue

dsh-rescue

DSH（DeepSeek Harness）被插件搞到打不开或崩溃的时候，用一条命令把它救回来，而且不丢东西。

零依赖 Node 命令行，跑在应用外面——因为 DSH 起不来的时候，任何装在 DSH 里面的东西也一起起不来。

$ dsh-rescue rescue
将回到 20261029T101010123Z-9f3e（1 小时前标记为可用）。确认还原？会先把当前现场完整存一份。[y/N] y 完成：已还原到 20261029T101010123Z-9f3e 写回 profiles/desktop/package.json, profiles/desktop/cordis.patch.yml 还原前现场 20261029T154130001Z-77ab 撤回 dsh-rescue restore 20261029T154130001Z-77ab

相对上次可用状态，坏掉时的现场是这样：新增 bundle：dsh-某个新插件依赖版本变化：dsh-better-sidebar ^0.28.0 → ^0.29.0 patch 新增条目：llm-pi-ai 以上差异已被撤消。

校验：当前配置与 good 逐字节一致 ✓

为什么需要它

DSH 自带一半救赎，但那一半有两个坑（都能在 app.asar 里读到依据）：

1. 自带的「禁用第三方插件」是不可逆的一刀切。 宿主致命崩溃时会弹原生对话框，第三个按钮走 sanitizeProfile()：把 cordis.patch.yml 改名成 .bak-<毫秒> 备份，然后把 package.json 里的 dsh.profile.bundles 直接覆写成出厂模板。
.bak 只保住了 patch 文件——「我原本启用了哪些插件、什么顺序」这条信息没有任何备份，被永久覆盖。你救回来了，但恢复不到原样。

2. 真正的「打不开」它根本救不到。
DesktopHostProcess.start() 的 readyPromise 只等子进程发 ready 或退出，没有超时。
插件在 apply() 里挂住（死循环、await 永不返回、等一个永远不会出现的服务）时，Electron 无限等待，没有窗口、没有崩溃报告、连那个恢复对话框都不会出现。你只能强杀、再启动、再挂。

3. 空的 patch 文件比坏的更糟。 dsh-app-boot 的文档写得很清楚：空或只有注释的 cordis.patch.yml 会让启动直接失败——要停用这一层必须写 []。所以「顺手清空一下」是把自己往启动失败上推。

4. 主应用和 DSH NEXT 共用同一份 profile。 NEXT 会把 dsh.desktopNext 键写进同一个 package.json，还额外用 desktop-next..patch.json 做 overlay，并自带几个 bundle（dsh-community-market、@agents-anywhere/dsh-bridge-next）。
两个应用同时开着就是两个宿主、两套 HMR、每个插件两份实例，各自往同一批状态文件里写——插件一直在抢文件，多半就是这个。而且这时候点恢复按钮，另一个实例还在改同一份配置。

dsh-rescue 补的就是这四件事：可逆、能覆盖挂死场景、绝不写空 patch、认得 NEXT 的痕迹。

和 DSH NEXT 一起用

- 同一时间只开一个应用。 doctor 会在两个同时运行时给出 instances.dualHome 警告。
- 救之前把两个都关掉。 否则工具会拒绝写（--force 可越过）。
- bundle 解析会同时看两个安装包：NEXT 内置的那两个不会被误报成「没装」。
- 还原较早的快照可能会去掉 NEXT 的 desktopNext* 键——rescue 会当场提示；NEXT 下次启动一般会补回，但 bundle 顺序可能变。
- 装在非标准位置时（比如 D:\deepseek harness\DSH NEXT），一般不用管：工具会从 NEXT 写进 profile 的 overlay 里反推它的安装位置；实在不行加 --asar <路径>。

装插件突然全废？先看这一条

dsh plugin add / update 开始报

ERR_PNPM_UNEXPECTED_STORE
ERR_PNPM_UNEXPECTED_VIRTUAL_STORE

那不是插件坏了，是 pnpm 的记账错位：node_modules/.modules.yaml 里记着「依赖来自某个 store」，而那个 store 已经搬走或删掉了。典型起因是把 profile 搬到别的盘（或搬过去又搬回来）却没重装 node_modules。

麻烦的是应用照常能开，只有装插件会失败，很容易被误判成别的问题。dsh-rescue doctor 现在会直接点名：

✗ store.mismatch pnpm 记着依赖来自 D:\DSH\pnpm-store\v11，而当前 store 是 C:\...\pnpm\store → 现在任何 dsh plugin add/update 都会报 ERR_PNPM_UNEXPECTED_STORE ✗ store.virtualMismatch pnpm 记着虚拟 store 在 D:\...\node_modules\.pnpm，而它应该在这里：C:\...\node_modules\.pnpm 修法就是让 .modules.yaml 里的两个路径回到真实位置（然后跑一次 pnpm install 让它自洽）。检查会读 pnpm 全局配置里的 storeDir，也可以用 --store <路径> 手工指定——合法的自定义 store 不会被误报。

安装

需要 Node.js 20+。三种方式，任选：

直接从仓库用
git clone https://github.com/bi8boJ/dsh-rescue.git
node dsh-rescue/bin/dsh-rescue.mjs status

或者全局装
npm install -g .

Windows：双击 bin\dsh-rescue.cmd 就是交互菜单它会自己去找 PATH 上的 node，找不到就用 DSH 自带的那个。

装 DSH 的机器上 node 常常不在 PATH 上（DSH 自带运行时但没导出）。bin/dsh-rescue.cmd 和 bin/dsh-rescue.sh 会自动去常见位置找，也可以用 DSH_RESCUE_NODE 直接指定。

60 秒上手

1. DSH 正常的时候，先记一次"这个状态是好的" dsh-rescue good

2. 哪天它起不来了（或者起来了但明显不对劲） dsh-rescue status # 体检 + 最近崩溃 + 跟上次好状态的差异 dsh-rescue rescue # 一键回到上次可用，先存现场再还魂

还没标记过 good？先用可逆的安全模式 dsh-rescue safe-mode # 只留出厂 bundle，第三方全不加载 dsh-rescue undo # 起来之后一次性撤回

good 之前建议先跑一次 dsh-rescue doctor；体检不过时 good 会拒绝（可以用 --force 强记，但那等于把坏状态当退路）。

命令

| 命令 | 作用 |
| launch | 看门狗启动：N 秒没就绪就杀掉、回滚到上次可用、再试一次 |
| bisect | 二分定位是哪个插件害的（自动启停，跑完还原配置） |
| status | 总览：静态体检 + 最近一次崩溃的事实 + 与上次可用状态的差异 |
| doctor | 只做静态体检，有错误时退出码 1（适合放进脚本/CI） |
| good | 把当前状态标记为"已知可用"（体检不过会拒绝） |
| save | 打一份普通快照（改插件前手动留档） |
| rescue | 一键救援：存现场 → 回到最近 good → 报告撤了什么 → 校验逐字节一致 |
| restore <ref> | 还原任意快照；ref 支持 last / good / 完整 id / id 前缀 |
| safe-mode | 只保留 @deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app，第三方全部不加载 |
| undo | 撤回上一次写操作（靠 journal 里的前置快照） |
| list | 快照列表，标出 good 指针 |
| diff [a] [b] | 两个状态的差异，默认 good → 当前 |
| crash | 解析最近一次崩溃报告，抽出退出码、被跳过的 bundle、版本不兼容项、一直等不到服务的 entry |
| menu | 交互菜单（双击 .cmd 时默认走这里） |

通用选项：

--home <目录> DSH_HOME，默认 $DSH_HOME 或 ~/.dsh --profile <名字> profile 名，默认 desktop --runtime <版本> 直接指定 DSH 运行时版本（跳过探测） --asar <路径> 额外读一个 app.asar（比如 DSH NEXT 的），用来解析它内置的 bundle --app <可执行文件> 要启动的 DSH 应用（默认自动找） --boot-timeout <秒> 看门狗等多久算卡死，默认 90 --round-timeout <秒> 二分时每轮等多久，默认 60 --no-auto-restore 卡死时只杀不回滚（默认会回滚到最近 good） --json 机器可读输出 --yes 跳过确认 --dry-run 只打印计划，不写任何文件 --force DSH 在跑也照写 / 体检不过也标记 good

运行时版本会自动从安装目录的 app.asar 里读（和 DSH 自己做版本闸门时读的是同一份清单），所以不需要 dsh 在 PATH 上；真的读不到（比如装到了非常规位置）就用 --runtime <版本> 指定，否则版本闸门那一项会跳过。

让每次启动都受保护（看门狗）

rescue 要你自己发现"打不开"。但有一种坏法连对话框都不会出现：插件卡在 apply() 里，宿主永远不报 ready，Electron 就一直等——没窗口、没崩溃报告、没有可点的按钮。

launch 就是为这个准备的：

dsh-rescue launch # 90 秒内没就绪 = 卡死 dsh-rescue launch --boot-timeout 120 dsh-rescue launch --no-auto-restore # 只杀不救它做的事：启动 DSH → 每秒看一次，应用是不是真的在 loopback 上监听并对外服务了 → 超时就 taskkill /T 连子进程一起杀掉 → 回滚到最近 good → 再启动一次 → 还不行就停下，并告诉你怎么继续（不会无限重试）。

想日常都用：把桌面快捷方式改成

"...\dsh-rescue\bin\dsh-rescue.cmd" launch

（双击 bin\dsh-rescue.cmd 不带参数仍然是交互菜单，第一项就是 launch。）

两条注意：

- 已经有一个实例在跑时，它会拒绝启动第二个——看门狗只对「从零启动」有意义。
- 判定「就绪」的依据是「有 DSH 进程在 loopback 上监听」。这是从外面能拿到的最可靠的信号；如果你知道更好的判据，--boot-timeout 调到肉眼可接受的等待时间也能用得稳。

启动信标（可选的小插件）

good 要你记得按。想让这件事自动一点，装仓库里那个小插件：

dsh plugin --profile desktop add file:<本仓库>/plugin

它做的事只有一件：宿主 apply 时往 <DSH_HOME>/rescue/beacon.json 写 booting，30 秒后改成 ok，并记下当时的 bundle 列表哈希。于是：

dsh-rescue good --auto # 信标说这套配置确实起过才标记，否则告诉你为什么不行 dsh-rescue status # 多一行：启动信标：成功启动 · 12 分钟前 · 配置与当前一致

它不影响启动：所有写入包在 try/catch 里，路径在调用时解析，原子写。不想要了就 dsh plugin --profile desktop remove dsh-rescue-beacon。

定位是哪个插件害的（bisect）

救回来之后还有个问题：到底是谁干的。bisect 用二分法把它揪出来：

dsh-rescue bisect # 需要先关掉 DSH dsh-rescue bisect --round-timeout 45 --yes

它做的事：先确认「现在这套确实起不来」「只留基线 bundle 确实能起来」两个对照，然后把候选插件一半一半地加载，每轮自动启停一次 DSH，按「起得来 / 卡住」把范围砍半。8 个候选只要 2~3 轮，十几分钟到几分钟不等。

几条硬约束：

- 跑完一定还原成你原来的 dsh.profile.bundles，中途出错也一样（finally）。
- DSH 开着时拒绝执行——它要反复启停，不能和你正在用的实例打架。
- 假设只有一个元凶。真的有多个时，它会收敛到其中一个，然后你把它关掉再跑一次。
- 如果「全关掉第三方也起不来」，它会直接说问题不在插件上，让你去 crash / doctor。

它是怎么保证"不丢东西"的

- 写之前先存证。 任何写操作都会先打一份前置快照（pre-restore / pre-rescue / pre-undo / pre-safe-mode），坏现场永远还在。
- 被覆盖的文件留副本。 快照里不存在的文件若当前存在，是改名成 .pre-<时间戳> 而不是删除。
- 逐字节还原。 还原后会自动重算哈希跟快照比对，不相等会明确告诉你。
- 运行中拒绝写。 检测到 DSH 正在运行就拒绝（dsh-hmr 会当场热应用，可能把好的也弄坏）；确实要写加 --force。
- 快照自身坏了也不硬来。 快照缺文件、或里面的 package.json 是坏 JSON 时，拒绝用它还原。

快照存在哪

<DSH_HOME>/rescue/
snapshots/<id>/snapshot.json 元数据（bundles 清单、每个文件的哈希） snapshots/<id>/installed.json 当时装了哪些包、什么版本 snapshots/<id>/files/... 5 个配置文件的原文 good.json 指向最近一次 good journal.json 最近 50 次写操作

默认保留最近 30 个非 good 快照，good 永不被回收（--retention 可调）。配置文件都是几 KB，不用担心占地方。

它不做什么

- 不启动、不守护 DSH。 自动看门狗（启动超时就杀 + 自动回滚）在 v0.2。
- 不动 node_modules。 包真缺了只报错 + 给命令，不代装、不联网。
- 不碰会话、工作区、记忆库。 只碰那 5 个插件配置文件。
- 不重排 YAML。 只追加行，注释和 !!js 表达式原样保留。
- 不猜语义。 某个 entry 已存在但没写 disabled 时，它不会替你改，而是告诉你手动改。

平台

Windows 是实测平台（DSH Desktop 的主场）。macOS / Linux 的路径与崩溃日志目录都实现了，但未在真机验证——如果你在上面跑通了或者踩到坑，欢迎提 issue。

崩溃日志目录会同时看这两处：
- %APPDATA%\@deepseek-ai\dsh-desktop\logs（或 macOS/Linux 的等价位置）
- <DSH_HOME>\electron-user-data\logs（DSH NEXT 用的那套）

开发

node --test # 218 个用例，全部跑在临时目录的合成 home 中
DSH_REAL_HOME=1 node --test test/real-smoke.test.mjs # 额外跑两个真实机器只读检查

设计文档在 docs/design.md。

License

MIT