插件热激活 lixiaohao001/dsh_plugin_refresh

dsh_plugin_refresh

安装 DSH 插件后立刻就能用，不用重启。

dsh_plugin_refresh 是 DeepSeek Harness 的宿主插件，它盯着已安装的 composition，在运行中的进程里把插件激活收尾：插件管理器操作后可能留下没挂载的 bundle，它来核实；再走 Web Plugins 页面用的那条带类型路径重新驱动一遍；插件文件变了但路径没变，它重新加载插件代码。它从不写你的配置档 manifest 或补丁层。

中文说明见下方「中文文档」一节。本插件解决的是：插件安装完成后无需重启 DSH 即可生效。

为什么需要它

配置档处于 live 状态（hmr 服务已组合）时，DeepSeek Harness 本来就会在进程内应用全新的 bundle 安装：插件管理器选中 bundle，调用 reconcileProfilePatches，接着 app-boot/config-reload 跟上。但仍有三种真实情况会落到「下次启动才生效」，这里全都覆盖了：

| 情况 | 没有这个插件会怎样 |
| 安装时指定的依赖，配置档里已经有了（重装 / 升级 / 本地重新 link） | installBundle 在重新加载之前就返回 application: "restart-required"——选择保存了，什么都没挂载。 |
| 插件第一次 import 失败 | Node 会缓存失败的模块任务。之后每次重试同一个模块 URL，都报同样的错，插件一直死着，直到进程重启——哪怕你已经把文件改好了。 |
| 插件自己的文件变了，路径没变（重新构建 bundle、重新 link 本地开发插件） | 装好的包在 node_modules 下，官方热重载服务按设计会忽略这里；运行中的进程还留着旧代码。 |

已有的同类方案，以及这里到底哪里不同

已经有好几个 DSH 插件在攻「不用重启」这件事。把话说清楚，也是发布这个插件的一部分：

| 项目 | 做法 | 重合度 |
| dsh-hot-reload | 原地换上升级后的插件，重载失败就回滚，否则提示手动重启 | 最高——和 lib/deep-reload.js 是同一个原地替换思路 |
| dsh-hot-installer | 热安装 / 移除 / 更新 / 启用禁用配置档 bundle；明确说模块代码变更仍需重启 | 高，在宿主 composition 这一侧 |
| dsh-hotreload-plugin-manager | 同上，另加一个 Web 设置页 | 高；多了浏览器 UI |
| dsh-refresh | 侧边栏按钮，刷新清单并重载页面 | 互补——它管浏览器那一半 |
| dsh-plugin-refresh | 右键 → 整页重载 | 浏览器侧的同一思路；注意名字很像 |
这个包和其他包不一样的地方：

1. 它能修复首次导入失败。 插件的首次导入一旦失败，就会在进程的整个生命周期里一直死着，因为 Node 会把失败的模块任务缓存下来——改好文件再重试也没用。这一轮处理会丢掉被污染的模块任务并重新导入，所以坏掉的安装不用重启也能恢复可用。
2. 它能把真正的错误暴露出来。 插件管理器只报 failed to import，别的什么都不说；repairs[].probe.error 会带上底层的异常，而这通常就是全部答案。
3. 它自动运行，且没有依赖。 只用 node: 内置模块——没有 chokidar，没有 js-yaml，也没有构建步骤（你编辑的文件就是运行的文件）。检测是事件驱动的，再加一个指纹轮询兜底，而不是等人去按按钮。
4. 它支持本地 link: 安装，这类安装的真实路径在配置档之外，裸标识符这个运行时解析不了；这一行会通过它解析后的 URL 来激活。

它弱的地方也直说：没有浏览器 UI，没有安装/卸载/更新操作（它刻意不执行任何包操作），只有一个小型单元测试套件而不是集成测试，而且它会伸手去碰 Node 加载器的内部实现，所以对 DSH 和 Node 版本很敏感。

它做什么

一次串行处理，在启动时、每次 plugin-manager 操作之后、以及被监视的文件发生变化时运行：

1. 深度重载 —— 每个模块文件在路径不变的情况下发生变化的存活插件，都会就地重新导入并重新激活，步骤和官方 @deepseek-ai/dsh-hmr 服务一样：丢掉 Node ESM 的 loadCache（用 Map.prototype.delete，Node 24 上必须这样）和插件自身包的 CommonJS require.cache，重新导入，对旧一代执行 registry.delete()，在同一批 fiber 上重新激活，再重新挂上原来的 Loader Entry，让条目身份、配置和诊断信息在替换后依然保留。
2. 修复 —— 对于已选中但没有运行行的 bundle，它会丢掉被污染的模块任务，导入声明的模块一次以捕获真正的失败原因，然后通过 pluginManager.setBundleEnabled() 重新驱动组合——这是官方路径，它会自己拿配置档写入锁和热重载队列。如果运行时仍然解析不了这一行声明的标识符，就通过它已经解析好的文件 URL 来激活这一行（见下面的本地安装）。
3. 报告 —— 一张按 bundle 划分的健康表（已选中、运行行、错误）和一段有上限的处理历史，日志和 HTTP 里都能看到。

安装

从这个仓库安装——不需要发布到 npm：

dsh plugin --profile desktop add github:lixiaohao001/dsh_plugin_refresh

从本地克隆安装，这也是开发环境（包是链接的，所以改动即时生效）：

dsh plugin --profile desktop add /absolute/path/to/dsh_plugin_refresh
或者从智能体会话里，用 plugin_manager 工具的 install_bundle 动作，传入同一个绝对路径。包声明了 dsh.bundle.patch，所以它会作为配置档 bundle 安装，并且只插入一行：

- insert:
- id: plugin-refresh
name: dsh_plugin_refresh

配置

当 @deepseek-ai/schemastery 可访问时，行配置由导出的 schema 校验；无论哪种情况，都会由 lib/config.js 归一化。

| 字段 | 默认值 | 含义 |
| autoCheck | true | 启动后检查，每次插件管理器操作后也检查。 |
| autoRepair | true | 重新驱动刚安装或刚启用、但没有运行行的 bundle。 |
| deepReload | true | 重新加载文件已变化、但路径未变的插件模块。 |
| watchProfile | true | 监听配置档补丁文件和 manifest。 |
| devWatch | [] | 插件开发时要额外监听的绝对文件或目录。 |
| devReload | true | devWatch 路径变化时深度重载。 |
| pollIntervalMs | 2000 | 指纹轮询的间隔，用来兜底文件监听；0 表示禁用。每轮只比对记录的大小和修改时间，开销很低。 |
| debounceMs | 400 | 静默窗口，把一串变化事件合并成一轮。 |
| startupDelayMs | 1200 | 应用就绪后，第一次检查前的延迟。 |
| route | /api/plugin-refresh | 状态路由前缀；空字符串会关闭 HTTP 接口。 |
| verbose | false | 记录那些没发现任何待办事项的轮次。 |

- id: plugin-refresh
config:
devWatch:
- /absolute/path/to/my-plugin/lib

HTTP 接口

仅限回环地址，和它注册所在的 Web 服务器一样。

| 方法 | 路径 | 含义 |
| GET | /api/plugin-refresh/status | 配置、引擎 generation、快照大小、最近一轮、bundle 健康状况、轮次历史。 |
| GET | /api/plugin-refresh/status?detail=1 | 额外返回逐条目的模块快照（文件路径、记录的大小和 mtime）。 |
| POST | /api/plugin-refresh/check | 立即运行一轮。 |
| POST | /api/plugin-refresh/repair?bundle=<name> | 校验并修复一个 bundle（省略 bundle 时修复所有不健康的 bundle）。 |
| POST | /api/plugin-refresh/reload?path=<abs> | 深度重载拥有某个文件或目录的插件。 |

插件每次替换自己的模块 generation 时，generation 都会变化，这样一次成功的热重载就能直接观察到：记下它，保存一个源文件，再读一次。

每个 POST 都要求同源请求。Web 服务器自身不强制任何 origin 策略——那属于路由所有者的职责——否则跨站页面就能强制触发重载。同源请求要么省略 Origin（所有非浏览器客户端），要么写出它访问到的主机名，而浏览器无法伪造后者。

装上它之后开发插件

当 devWatch 覆盖了你插件的目录（或者你调用 reload 路由），编辑一个源文件就够：改动通过每个活动条目的模块图检测出来，缓存的代际被丢弃，插件原地替换。典型循环：

after editing <my-plugin>/lib/.js
Invoke-WebRequest -Uri 'http://127.0.0.1:19387/api/plugin-refresh/reload?path=<my-plugin>/lib' -Method POST

本地安装与裸标识符限制

从本地目录安装的插件是 link: 依赖，其真实位置留在配置档之外。本运行时通过启动时所用的组合来解析配置档插件的模块标识符，而位于配置档之外的包无法被它命名：用裸标识符导入 <your-plugin> 会失败并报 failed to import，而导入它已解析的 file:///…/lib/index.js 则正常。这就是本地链接的插件会表现为「已安装却从未激活」的原因。修复流程会处理它：把该行绑定到解析后的 URL 一次；之后的重新组合会恢复声明的标识符，活动 fiber 继续运行。从 registry 或 git URL 安装会把包放进配置档内，不需要这一步。

兼容性

| DSH | 0.2.0-rc.2（desktop 配置档，Web GUI），Node 22.22 —— 构建和验证所用的版本 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| 必需的 DSH 服务 | 无：hmr、pluginManager、profileContext、webServer 和 appReady 都是可选的，插件在缺少它们的情况下也能加载，并报告自己做不到什么 |
| Peer 范围 | @deepseek-ai/dsh >=0.2.0-rc.2 <0.3.0-0，由插件管理器在安装前强制 |
| 平台 | 宿主侧：任意。devWatch 循环和状态路由假定本地文件系统和已组合的 Web 服务器 |

DSH 发布候选版的节奏很快，所以 peer 范围刻意收窄：DSH 进入下一个 rc 时，插件管理器会拒绝这个版本，直到匹配的发布放宽范围。深度重载路径还用到 Node loader 内部机制，所以 Node 大版本升级后值得手动检查一次 —— 运行 POST /check，预期没有 error。

开发

node --test # unit tests for config normalization; needs no DSH runtime
node --check lib/.js

没有构建步骤：lib/ 里的文件就是运行的代码。编辑之后，指纹轮询大约两秒内会捡起改动；想自己触发：

Invoke-WebRequest -Uri 'http://127.0.0.1:19387/api/plugin-refresh/reload?path=<repo>/lib' -Method POST

原地替换成功时，/status 里的 generation 字段会变化。

已知限制

- 版本替换若改变了已解析的包目录，仍然需要重启。 app-boot 的解析路由拒绝在进程运行期间用不同的目录、版本或 scope 替换已有的包名。在不变的
- 路径已被覆盖；把 node_modules/<pkg> 换成另一个版本目录则不在覆盖范围内。
- 浏览器那一半由宿主负责。 插件只管宿主侧的激活；新挂载插件的客户端 bundle 通过 dsh-client-modules + dsh-client-hmr 到达已打开的页面。如果这张浏览器依赖图无法更新，页面可能需要刷新。
- 状态路由未做鉴权，只是绑定在回环接口上，和 /api 下的其他插件路由一样。它会暴露插件名、文件路径和检查结果；设置 route: "" 可以移除它。
- 回滚是尽力而为。 如果重新 import 成功但重新激活抛错，会尽可能重新激活上一代，并把失败写进检查结果和日志；进程绝不会静默地留下一个已销毁的插件而没有替代品。
- 修复有频率限制。 一次修复会让 plugin-manager 发出正是用来调度下一轮检查的事件，所以每个 bundle 在 15 秒窗口内只允许尝试一次。无法激活的 bundle 会报告 cooling-down，而不是陷入循环。
- 被有意关闭的行不算故障。 如果某个 bundle 的所有行都被补丁层禁用（被替换的皮肤、限定预设范围的工具），会报告为健康，而不是可修复。
- @deepseek-ai/schemastery 是动态 import 的：从 link: 安装时它不可达，所以那里 Config 导出为 undefined，该行回退到原始配置。包内没有其他东西依赖非内置模块。

故障排查

读取 GET /api/plugin-refresh/status：

- 某次检查的 error —— 检查本身失败了；HMR transactions cannot be nested 不应再出现（引擎在已经处于队列内部时会内联运行）；
- repairs[].probe.error —— 损坏插件的实际 import 失败原因，plugin-manager 只会把它报成 failed to import；
- repairs[].purgedModules > 0 —— 一个被污染的模块任务已被丢弃，这样重试才能读到修好的文件；
- repairs[].rebound —— 该行是通过解析后的文件 URL 启动的；
- health[].needsRepair === true —— 某个被选中的 bundle 没有正在运行的行。

中文文档

这个插件做什么

安装完插件后无需重启 DSH，即可让插件立即生效。

DSH 本身在「在线 profile」下已经能就地加载全新安装的 bundle（由 hmr 服务 + plugin-manager 的 reconcileProfilePatches 完成）。但有三种情况仍然会退化成「下次启动才生效」，本插件专门补齐这三种：

| 情况 | 没有本插件时的表现 |
| 安装的依赖名在 profile 里已存在（重装 / 升级 / 本地重新 link） | installBundle 在重载之前就返回 application: "restart-required"，选择被保存，但没有任何东西被挂载。 |
| 插件第一次 import 失败 | Node 会把失败的 module job 缓存住，之后同一个模块 URL 的重试会一直报同样的错——即使文件已经修好，也必须重启进程。 |
| 插件自身文件在同一路径下被改动（重新构建、本地开发重新 link） | 已安装的包在 node_modules 下，而官方热重载按设计忽略该目录，运行中的进程会一直用旧代码。 |

工作机制

一次串行化的检查流程，在启动后、每次 plugin-manager 操作后、以及被监视文件变化时执行：

1. 深度重载（deep reload）：找出「模块文件在路径不变的前提下已改动」的在线插件，按官方 @deepseek-ai/dsh-hmr 同样的步骤就地替换：清理 Node ESM loadCache （必须用 Map.prototype.delete，Node 24 需要）与 CJS require.cache、重新 import、
registry.delete() 旧一代插件、在同一批 fiber 上重新激活，并把原来的 Loader
Entry 接回去，保证 entry 身份、config、诊断信息都不丢。
2. 自动修复（repair）：对「已被选中但没有运行中的行」的 bundle，先丢弃被污染的 module job，再直接 import 一次以捕获真实报错，然后通过
pluginManager.setBundleEnabled() 重新驱动组合——这是官方路径，profile 写锁和热重载
队列都由它自己获取。若运行时仍无法解析该行的 specifier，则改用已解析出的文件 URL 激活该行（见下）。
3. 状态上报：每个 bundle 的健康表（是否选中、有几行在运行、是否有错误）与有界的历史记录，同时输出到日志和 HTTP 接口。

安装

dsh plugin --profile desktop add /绝对路径/dsh_plugin_refresh

或在会话里用 plugin_manager 工具的 install_bundle，参数同样是绝对路径。

配置项

见上方英文表格；在 profile 的 cordis.patch.yml 里覆盖，例如开发时监视自己插件的目录：

- id: plugin-refresh
config:
devWatch:
- /绝对路径/my-plugin/lib

HTTP 接口

仅监听回环地址（与 Web server 一致）：

| 方法 | 路径 | 说明 |
| GET | /api/plugin-refresh/status | 配置、快照规模、最近一次检查、bundle 健康表、历史 |
| GET | /api/plugin-refresh/status?detail=1 | 额外返回每个 entry 的模块快照（文件路径） |
| POST | /api/plugin-refresh/check | 立即执行一次检查 |
| POST | /api/plugin-refresh/repair?bundle=<名字> | 校验并修复某个 bundle（不带参数则修复全部不健康 bundle） |
| POST | /api/plugin-refresh/reload?path=<绝对路径> | 对拥有该文件/目录的插件做深度重载 |

开发时的热重载

配置 devWatch 指向你的插件目录（或直接调用上面的 reload 接口）后，改完源码即生效：改动会通过每个在线 entry 的模块依赖图被检测到，旧的模块代被清理，插件就地替换。

本地安装与「裸模块名」限制

从本地目录安装的插件是 link: 依赖，真实路径在 profile 之外。本运行时为 profile 插件解析模块名时走的是启动时的组合表，而位于 profile 之外的包无法被它命名：用裸包名 import 会失败（failed to import），而用已经解析好的 file:///…/lib/index.js 导入则成功。
这正是「本地 link 的插件显示已安装却一直不生效」的根因。修复流程会先把该行绑定到解析后的 URL 启动一次；之后重新组合时会恢复声明的 specifier，而已运行的 fiber 不受影响。从 npm /
git 安装会把包放进 profile 内，不存在该问题。

已知边界

- 改变了「解析到的包目录」的版本替换仍然需要重启：app-boot 的 resolution router 拒绝对已存在的包名替换目录 / 版本 / scope。文件内容在同一路径下变化可以就地生效，把 node_modules/<pkg> 换成另一个版本目录不行。
- 浏览器半边由 DSH 自己的 dsh-client-modules + dsh-client-hmr 负责；本插件只管 Host 侧。
若浏览器模块图无法更新，页面可能需要手动刷新。
- 状态接口除绑定回环地址外没有额外鉴权（与其他 /api 下的插件路由一致），会暴露插件名、文件路径和检查结果；把 route 设为 "" 可完全关闭。
- 回滚是「尽力而为」：重新 import 成功但重新激活失败时，会尽量恢复上一代并在结果与日志中报告，不会让进程停在「插件被卸载且没有替代」的状态。
- @deepseek-ai/schemastery 是动态导入：link: 安装下不可达，因此那里导出的 Config 为 undefined，该行退化为「原始 config 直接传入」。包内其余代码不依赖任何非内置模块。

排错

打开 GET /api/plugin-refresh/status 看：

- 某次检查有 error：检查流程本身失败；
- repairs[].probe.error：真实的 import 失败原因（plugin-manager 只会说 failed to import）；
- repairs[].purgedModules > 0：丢弃了被污染的 module job，使重试能读到修好的文件；
- repairs[].rebound：该行是通过解析后的文件 URL 启动的；
- health[].needsRepair === true：某个已选中的 bundle 没有任何在运行的行。

本机验证记录（2026-10-11）

- 全新本地 link: 安装一个测试插件 → application: "applied"，其 HTTP 路由立即返回 200，未重启。
- 故意让测试插件的首次 import 失败 → 安装返回 failed to import；修好文件后，插件自动检测到「已选中但没有运行行」，丢弃被污染的 module job 并用解析后的 URL 启动该行
（repairs[].rebound），其 HTTP 路由随后返回 200，未重启。
- 修改本插件自身的 lib/*.js → 下一次指纹轮询检测到模块变化，清理 6 个缓存模块并就地替换自身， 未重启；/api/plugin-refresh/status 的 generation 由 g56e083 变为 g52eb39，且新实例的快照已记录改动后的文件大小，全程没有调用任何接口触发。
- 停止监视的判定修正后，被 patch 故意关闭的 ui-skin-orca-link 不再被误报为待修复（needsRepair: false）。