# dsh-hot-installer

[中文](README.md) | [English](README.en.md) | [更新日志](CHANGELOG.md)

**给 DeepSeek Harness 装上之后，`dsh plugin add` / `remove` / `update` 都不再需要重启。** 装一次、重启一次，之后这个插件替你监听 profile 的插件清单：新装的包当场挂载、卸掉的包当场卸载、升级的包当场重载；就算你手动编辑了补丁文件，它也会把被冲掉的热装行自动补回来。

## 我需要装吗（按 dsh 版本看）

| 你的 dsh | 平台自身能力 | 这个插件提供什么 |
| --- | --- | --- |
| `0.1.5-rc.2`（npm `latest`，普通用户默认装到的） | HMR 只监听补丁文件，**完全不看 profile 清单**：装/卸/升级都必须重启才生效 | **全部能力**——装、卸、升级三种操作都免重启 |
| `0.1.6-alpha.2` 及以后 | 平台自带 `dsh-hmr` 接管清单，**装/卸已原生免重启** | 补平台跳过的部分：**依赖版本升级**（`add pkg@新版本`）仍免重启；另带预检、失败回滚、紧急卸载保护链 |

结论：稳定版用户装它**不是没用，而是全靠它**；alpha 新版用户装它仍有价值（平台不管版本升级，也不做失败回滚）。哪天平台把这两件也做了，这个插件就可以卸载了。

## 这是什么

DeepSeek Harness 里一切皆插件，但你用 `dsh plugin --profile web add <pkg>` 装一个新 bundle 后，必须重启 `dsh web` 它才生效——因为 profile 的插件清单（`package.json` 里的 `dsh.profile.bundles`）只在启动时读取，运行中的进程不会再看它。卸载更糟：`dsh plugin remove <pkg>` 把包从磁盘删掉，但已挂载的插件行还留在内存里，此时刷新网页会看到 "Failed to load plugins" 报错（客户端还在向已删除的包要代码）。版本更新同样冷：新代码要等重启才会被加载。

这个插件把这条唯一的"冷路径"变热。它装好后常驻在 profile 里，监听清单文件的变化：发现新 bundle 就读取该包声明的补丁（`cordis.patch.yml`），把里面的插件行注入到运行中的插件树，loader 的 diff 机制当场激活（实测十几毫秒）；发现 bundle 被移除，就按"包→行"映射把对应行从树里摘掉；发现版本号变了，就把行摘掉再重挂，让 loader 重新加载新模块。整个过程不写任何配置文件、不改你的补丁层，重启后依然与正常启动完全一致。

## 安装与使用

```sh
# 一次性安装（换成你实际在用的 profile 名），然后重启一次 dsh
dsh plugin --profile web add dsh-hot-installer
```

重启之后，插件就永久生效了，日常操作和原来一模一样：

```sh
dsh plugin --profile web add some-plugin      # 立即生效，不用重启
dsh plugin --profile web remove some-plugin   # 立即卸载，不用重启，页面也不会报错
dsh plugin --profile web add some-plugin@latest   # 立即升级重载，不用重启
```

日志在 `~/.dsh/logs/dsh-hot-installer/dsh-hot-installer.log`，每次热装/热卸/热重载都有记录（如 `hot-applied dsh-alive (1 patch entry)`、`hot-removed dsh-alive (1 patch entry)`、`hot-reloaded dsh-pomodoro (0.1.0 -> 0.3.0, 1 patch entry)`）。

## 工作原理

清单文件每次变化（`dsh plugin add` 会写两次：pnpm 写依赖、再同步 bundles 列表，插件用 300ms 防抖合并），插件对比自己维护的快照（包名 → 版本号）找出新增、移除和升级的包。对新增的包：从 profile 的 node_modules 解析出包目录，读取它 `package.json` 里 `dsh.bundle.patch` 指向的补丁文件（用与启动完全相同的 YAML 方言解析，包括 `!!js` 表达式），把解析出的 patch 条目追加到根 include entry 的 `config.patches` 并调用 `entry.update`——这正是启动时挂载插件的同一条通道，所以热装与冷装的结果完全一致。对移除的包：把该包贡献的 patch 条目从 `config.patches` 里按深度相等逐个摘除再 `entry.update`，loader 卸载对应行。对升级的包：先摘除旧行再重新挂载新行，loader 会重新 import 拿到新版代码（绕开 ESM 模块缓存）。包→行的映射在启动时对清单里所有包建立（重启后 boot 挂载的包同样可热卸），每次热装时更新，只存在于内存。

**补丁层保护（重放）**：dsh 的补丁监听在 `cordis.patch.yml` 被手动编辑时会用启动时的快照全量重组插件树，这会丢掉热装的行。本插件每 5 秒做一次对账：发现记录的某行从活配置里消失了，就把它补回去；如果补丁文件里显式写了某行的 `disabled: true`（比如插件开关工具做的禁用），则尊重它、不补。所以手动编辑补丁文件不会再"冲掉"热装插件。

## 已知边界

更新热重载有完整防护链：先预检新版本（解析它的补丁声明），解析失败时旧行保持不动、只记录 `restart required`；如果新代码本身无法被 loader 加载（import/apply 失败），会自动用 pnpm 把依赖装回旧版本并重新挂载（日志 `update failed ... rolling back` / `rolled back`），插件几乎无感地继续用旧版——只有回滚本身也失败（比如旧版本已从 registry 下架）才需要重启。卸载也一样诚实：如果卸载时发现对应行已经不在活配置里（比如补丁层重组刚把它冲掉），直接视为已卸载成功，不会误报 `restart required`。连热安装器自己都可以热更新（0.4.4 起）：自更新不会与自身的文件监听互相等待，`dsh plugin add dsh-hot-installer@latest` 同样免重启。官方"设置 → 插件列表"读取的是运行时插件树，热装的包即时可见。

本地开发期常用的 `link:` 安装有一个已知角落：Windows 上 pnpm 用 junction 重解析点指到你的本地目录，Node 进程内会缓存该 junction 解析出的真实路径。因此**同一次 dsh 运行期间，把 link 目标切换到另一个目录再热升级，行会继续跑旧目录的旧代码**——日志照常打印 `hot-reloaded`（假成功），但新代码从未被加载，包自己的激活日志仍是旧版本。这不影响 npm 正式包（按版本换装每次都加载新代码）；也不影响在同一个 link 目录内原地改文件（但那本来就不会触发自动更新，因为没有 spec 变化）。应对：切换 link 到不同目录后重启一次 dsh，或干脆把本地包发布到 npm 用 `add pkg@新版本` 走正式热升级通道。

**dsh 0.1.6-alpha.2 起的协作方式**：平台自带的 `dsh-hmr` 接管了 profile 清单的监听，装/卸 bundle（bundles 列表变化）由它原生重组；但"只有依赖版本号变化"时它会直接返回，所以版本热升级仍由本插件负责。此时插件不再抢同一个监听路径（平台已注册），改为每秒轮询清单、只处理 spec 变化，并保留缓存驱逐、预检、回滚、紧急卸载整条链。新旧两代 HMR 服务方法名（`watchConfig` / `registerConfig`）都做了特性探测，同一份代码在两个 dsh 版本上都能跑；启动日志会写明当前处于哪种模式。

## 开发与验证

```sh
npm install && node --test test/   # 纯函数单测（diff / 解析 / 去重 / 移除 / 重放）
```

仓库自带一个测试用 bundle（`examples/dsh-hot-test-bundle`，装它后写一条激活日志），可用来做免重启的装/卸演练。要求 Node >= 20、带 HMR 的长驻表面（如 `dsh web`）；没有 HMR 的一次性命令行面会正常启动但永不激活监听。

## License

MIT，见 [LICENSE](./LICENSE)。