插件热管理器 KYinCode/dsh-hot-installer

dsh-hot-installer

| English | 更新日志

给 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 新版用户装它仍有价值（平台不管版本升级，也不做失败回滚）。哪天平台把这两件也做了，这个插件就可以卸载了。

该矩阵已于 2026-09-22 用隔离环境实测复核：把 @deepseek-ai/dsh@0.1.5-rc.2 装到临时目录、DSH_HOME/USERPROFILE 双隔离后，用旧版自己的 CLI 装 dsh-hot-installer@0.5.4 并启动——日志为 hot install/remove/reload enabled, v0.5.4（完整能力模式），热装 hot-applied + 目标 bundle 当场激活、热卸 hot-removed 全部成功。

这是什么

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

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

安装与使用

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

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

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 版本上都能跑；启动日志会写明当前处于哪种模式。

dsh 0.1.7-alpha.1 起：dsh.bundle.patch 从“单个文件路径”扩展为有序文件数组（dsh-web-app 已改成 5 个文件：主补丁 + 4 个 agent preset），插件按声明顺序逐个解析并拼接，顺序与平台一致（行记录靠深度相等匹配，顺序错了就摘不掉行）；单文件声明照旧。另外，profile 模板自带的 bundle（dsh-base / dsh-web-app，在 dependencies 里没有条目）只做索引、不纳入版本热更新——它们的组合由平台自己负责，而“回滚到空 spec”会执行 pnpm add @，那不是报错而是装该包的 latest（dsh-web-app@ 会解析到 0.0.1-rc.1），属于静默降级。

0.5.3 起补上的一个细节：平台解析任何补丁文件时（bundle 补丁、--patch overlay、profile 补丁层），都会把 insert 行里绝对路径 / ./ / ../ 开头的 name 改写成“紧邻该补丁文件”的 file:// URL。插件现在做同样的改写，否则记录的行与活配置里的行匹配不上：热卸会退化成 rows already gone、重挂被去重成空，行继续跑旧代码却不报错。裸包名（如 @deepseek-ai/dsh-persona）保持原样。

0.5.4 起：解析 bundle 目录时复刻平台的顺序——先找 dsh 安装树、再回落 profile。随 dsh 自带的 bundle（dsh-base、dsh-web-app、dsh-experimental-agent-team-profile 等）既不在 profile 的 node_modules 里、也不在 dependencies 里；平台按安装锚点能正常挂载它们，而只按 profile 找就会误报“未安装”。锚点取自平台的 profileContext.installAnchor，取不到时保持旧行为。

开发与验证

npm install && npm test # 纯函数单测（diff / 解析 / 去重 / 移除 / 重放 / 补丁声明）

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

License

MIT，见 LICENSE。