dsh-plugin-reloader
English | 中文
Hot-reload installed DeepSeek Harness plugins without restarting dsh web. After you upgrade a plugin (e.g. dsh plugin add github:...), the new code takes effect in place; only a dependency-tree change restarts the process (through an external supervisor script).
It reuses the same reload pipeline dsh's built-in HMR uses for user code — clear the module caches, re-import the plugin entry, dispose the old fibers, mount fresh ones, roll back on failure — minus the node_modules exclusion that keeps the built-in HMR away from installed plugins. The loader's internal module cache is reachable through dsh's vendored loader without any special flag.
Features
- Auto hot-reload — polls the installed plugins' entry and
package.jsonfiles (every
pollIntervalMs, default 2s) and hot-reloads a plugin in place when its code changes. Polling (stat mtime+size) is used instead of a file-watcher library: chokidar's fs-watch never reached ready inside the long-lived dsh web process on Windows, and polling is immune to pnpm's whole-directory replacements (the stat simply sees the new files on the next tick). Plugin upgrades are low-frequency, so a 2-second stat of a handful of files is negligible.
/reload <plugin>command — manually hot-reload one installed plugin; with no
argument it lists the loaded plugins, marking non-reloadable ones ([official], [service], [self]).
/watch-statuscommand — prints live watch diagnostics: watched scopes, event count,
the last observed change, reload count, skipped reloads, and any startup error. Read it after upgrading a plugin to confirm the auto-reload fired (events and reloads incremented).
- Dependency-change restart — if a plugin's
package.jsonchanges its
dependencies/peerDependencies, the process exits with code 42 (configurable) so a supervisor relaunches it.
- Reloadability guard — official
@deepseek-aiplugins and plugins that provide
services other plugins depend on are not hot-reloaded by default: the attempt is skipped, logged, and counted in /watch-status. Reloading a service provider would cascade restarts through every plugin that injects its services, and reloading an official plugin is equivalent to patching dsh itself mid-session. Override per category with allowOfficial / allowServiceProviders.
- Rollback on failure — a failed re-import or mount restores the module caches and the
previous plugin; the session keeps running.
Install
dsh plugin --profile web add github:deepforce/dsh-plugin-reloaderRestart dsh web once so the plugin loads. For the dependency-change restart to be useful, start dsh through the supervisor instead of directly:
# Windows (cmd)
scripts\dsh-restart.cmd web
# Windows (PowerShell)
powershell -File scripts\dsh-restart.ps1 webUsage
After upgrading an installed plugin:
dsh plugin --profile web add github:deepforce/dsh-balance # upgradeThe watcher notices the changed lib/ files and hot-reloads it — no restart. To force it manually, type /reload @deepforce/dsh-balance in a session, or /reload with no argument to list candidates.
If the upgrade also changed the plugin's dependency tree, the process exits 42 and the supervisor relaunches dsh web automatically (a supervisor is required — a plain dsh web just exits).
Configuration
| Field | Default | Meaning |
|---|---|---|
watchEnabled | true | Poll installed plugins and hot-reload on code changes |
watchRoots | ["@deepseek-ai", "@deepforce"] | Scoped directories under the profile's node_modules to consider |
debounceMs | 400 | Change coalescing window before a reload fires |
pollIntervalMs | 2000 | Polling interval for change detection |
restartExitCode | 42 | Exit code used when a dependency tree changed (supervisor restarts on it) |
allowOfficial | false | Also hot-reload official @deepseek-ai plugins (not recommended) |
allowServiceProviders | false | Also hot-reload plugins that provide services other plugins depend on (not recommended) |
Example overlay:
# reloader.cordis.yml
- patch:
- id: plugin-reloader
config:
debounceMs: 600
restartExitCode: 50Compatibility
Tested against DeepSeek Harness 0.1.0-rc.6 (web profile, Windows 11, Node 24). It depends on the loader's internal module cache (loader.internal), which the vendored loader exposes by default; if a future dsh removes that surface, the plugin degrades to /reload reporting "loader internal is unavailable".
Security
- The watcher only reads files; it never executes anything itself.
- A reload failure rolls back instead of leaving a half-mounted plugin.
- The dependency-change exit is intentional and announced in the log before exiting.
Building locally
pnpm install # uses pnpm-workspace.yaml overrides for upstream npm gaps
pnpm run build # tsc emits lib/index.jsLicense
MIT