dsh-hot-reload
无需重启 dsh，即可热重载升级后的 DeepSeek Harness (dsh) 插件——运行中的插件会原地替换；如果重载失败，则回滚到可正常工作的旧版本，并提示手动重启。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-hot-reload@0.2.4Hot Reload 以 dsh-hot-reload 发布，当前版本为 0.2.4。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
Live-reload upgraded DeepSeek Harness (dsh) plugins without restarting dsh.
dsh's built-in hot-reload (cordis-plugin-hmr) deliberately ignores
node_modules, so upgrading an installed plugin (dsh plugin add pkg@x)
normally requires a full dsh restart to take effect. This plugin closes that
gap: it watches your profile's pnpm-lock.yaml, and when an already-loaded
plugin package's version changes, it swaps the running plugin in place.
On a plugin package upgrade, for each affected plugin:
Reload it live — invalidate the module caches, re-import the new code, and re-instantiate the plugin fiber in place. dsh, your sessions, and every other plugin keep running.
If the reload fails — you're left with the working old version, never a
dead plugin, plus a logged note that a manual dsh restart is needed to
pick up the new code. Two cases, both handled:
apply throws, sync or async)
is rolled back — the old version is re-instantiated in place.A version that failed is not retried automatically — retrying would tear down the working plugin again on every later lockfile write. Install a different version, or restart dsh, to pick the new code up.
Two cases produce no reload, by design:
no live fiber to reload right now and left
alone. Nothing was torn down, so this one is re-examined on every later
lockfile change, and it reloads by itself as soon as a running copy appears.
You are told once per version, not once per check — so if you still see
the same version reported after the plugin has had time to start, restart dsh.dsh-hot-reload can hot-reload itself too. When its own package is
upgraded, the running instance imports the new module, commits its own version
and persists it, closes its watcher, and then swaps its own fiber in place. The
new instance re-reads the state file and opens its own watcher — the old watcher
is closed before the new one opens, so there is never more than one live watcher.
To make that handoff — and a plain restart — safe, the plugin keeps its tracked
state in a file: profileDir/.dsh-hot-reload-state.json. It holds the committed
versions, the never-retried failedVersions, and the once-announced
noticedVersions. The file is written atomically — a .tmp file is written
and then renamed over the target, so a crash mid-write never leaves a truncated
file — and read back at startup, so a fresh instance inherits what the previous
one committed instead of treating already-loaded plugins as new and re-reloading
them.
This state file is required. If it cannot be written at startup, the plugin refuses to start (it throws) rather than running with in-memory-only state that a later self-reload or restart would lose.
It never restarts dsh for you — restarting is left to you (and your supervisor, if any).
The plugin writes every result to dsh's log. But dsh does not print its log to your terminal, so those lines are easy to miss. Two extra places show you what happened.
1. One line in your terminal, for every outcome. You get this in every profile:
dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
2. A short pop-up message in the dsh web app. You get one when a reload works. You also get one in every case where the new code did not load, so the old code is still running:
dsh.hotReload: falseThe second case is announced once per version, not once per check. That case is retried on every later lockfile write — including writes for other packages — so without this limit you would get the same pop-up over and over, with no way to dismiss it. The other three are announced each time they happen.
The message slides in, stays a few seconds, then fades out. If one upgrade reloads several plugins, the messages line up and show one after another.
The web part only loads in a profile that runs a web server. It sends the
messages over GET /dsh-hot-reload/events. A profile with no web server, such
as tui, still gets the terminal line and the log.
Messages are not saved. If no browser tab is open when a reload happens, that message is gone. The log still has the record.
If you restart dsh with a tab open, the tab opens a new channel by itself and pop-ups keep working. It tries for about three minutes. If it still cannot connect after that, it writes one line to the browser console and stops trying; reload the page to start again.
The terminal line above covers every reload outcome — reloaded, failed, and stale (not attempted — the old code is still running). To see everything else this plugin writes to the log (its warnings and diagnostics), add dsh's console logger to your profile. It is a separate package:
dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console
Then add a row for it in that profile's cordis.patch.yml and restart dsh:
- insert:
- id: logger-console
name: '@deepseek-ai/cordis-plugin-logger-console'
This prints all dsh log lines, not only this plugin's.
Note for full-screen profiles. The terminal line is written straight to the screen. In a profile that draws a full-screen interface, such as
tui, the line can land in the middle of the drawing and make the screen look wrong. It looks wrong only until the screen is drawn again.
dsh plugin --profile web add dsh-hot-reload
Then restart dsh once (bundle patch layers load at boot). After that, upgrades apply live:
dsh plugin --profile web add some-plugin@newer # reloaded automatically
Works in any profile — swap web for whichever profile you use; it watches
the profile it's loaded into.
Built and tested against dsh 0.1.0-rc.6 (Node 22 / 24). It reaches into
cordis/loader internals — mostly the same ones cordis-plugin-hmr uses — so a
future dsh that changes any of them may require an update:
| Internal | Used for |
|---|---|
loader.internal.loadCache | invalidating the ESM module cache |
loader.internal.resolve / resolveSync | resolving a specifier to a URL (dispatched on internal.version) |
loader.import / loader.unwrapExports | re-importing the fresh module and unwrapping its plugin export |
registry.plugin / registry.delete | swapping the plugin instance |
fiber.entry, fiber.runtime | re-attaching the new plugin to the running rows |
entry.disabled | skipping disabled rows (inherited getter) |
entry.options.group | skipping group container rows |
The pop-up message in the web app (and only that part) also uses:
| dsh part | Used for |
|---|---|
ctx.webServer.register | serving the message channel |
window.__ModuleLoader__ | loading the browser half |
the shell.overlay slot | placing the message over the app |
Toast from @deepseek-ai/dsh-client-ui-primitives | drawing it |
The plugin fails safe. If a part it needs is missing, it reports "restart needed"
instead of breaking dsh. The pop-up behaves the same way. A missing web server,
a browser module it cannot load, an unknown slot, a repeated registration, or a
dsh build with no Toast each cost you the pop-up only. Reloading still works,
and the web app still starts.
One exception: the browser half asks dsh for a service named slots. dsh's web
app refuses to start if any plugin never becomes ready. So if some future dsh
build had no slots service at all, this part would wait forever and show up in
dsh's start-up error list. Every other failure listed above is caught and simply
does nothing.
A plugin that knows it isn't safe to hot-reload can force the restart-needed
path (no reload attempt) by declaring, in its own package.json:
{ "dsh": { "hotReload": false } }
Set on the hot-reload row in your profile's cordis.patch.yml:
| Key | Default | Meaning |
|---|---|---|
debounce | 300 | ms to wait after a lockfile change before acting |
profileDir | auto | absolute path to the profile dir to watch (auto-detected from the loader base URL if omitted) |
This plugin is optimistic, not verified. It attempts the reload and falls back to "restart needed" only when something throws (or when there is no live fiber to swap). It does not detect silent leaks:
A plugin that acquires a raw resource outside cordis — a bare
setInterval, a net/http server, a WebSocketServer, an fs.watch,
a child_process — without a ctx.effect disposer can reload without
throwing yet leave that resource dangling (a stray timer, a duplicate
listener, an orphaned watcher). These accumulate across upgrades and are
cleared only by an eventual restart.
Cordis auto-unwinds everything a plugin registers through ctx
(ctx.effect, ctx.on, ctx.provide, tool schemas, adapters), so
well-behaved plugins reload cleanly. The risk is limited to plugins that
bypass ctx. If in doubt, have such a plugin set dsh.hotReload: false.
Reloading a plugin that holds live connections (e.g. a WebSocket bridge) drops and re-establishes them; clients must reconnect. That's expected, not an error.
The reload path relies on the cordis/loader internals listed under
Compatibility. If they are unavailable (no
--expose-internals and no node-addon-require-builtin addon), the plugin
degrades to reporting "restart needed" for every change instead of reloading.
The lockfile is only the trigger. Version numbers are read from each
package's installed package.json, because that is the only file that says
what an import would really get. On pnpm 11 (measured on 11.21.0) the files on
disk are written first and the lockfile last, so by the time this
plugin acts, the versions it reads have settled. But nothing here checks
that. If some future pnpm wrote the lockfile first, a check could read the old
version, skip it, and never look again — the lockfile is the only thing
watched, so that upgrade would be missed silently, with no message, until
you install another version or restart dsh. The debounce setting does not
help: the gap measured 2.5–4 seconds, far longer than any sane debounce.
The message channel (GET /dsh-hot-reload/events) has no password check,
the same as dsh's own /plugins/events. It sends plugin names and version
numbers. dsh already shows those through its plugin list, so this adds no new
secret. But if you bind dsh to 0.0.0.0, count it as one more address that
anyone on your network can open.
Scope note: this handles upgrades of already-loaded plugins. Installing a
brand-new plugin is a separate concern (adding its row to cordis.patch.yml,
which dsh already hot-applies).
MIT © Stuart Hu
A plugin that loads after dsh-hot-reload in the bundle order is reloaded
once — to its current version — on the first lockfile write after boot, even
when that write was for an unrelated package. Until this plugin has tracked the
package across one cycle, it cannot tell whether the running code is the old or
the current version, so it reloads rather than adopting a version that may
never have run. For an HMR-safe plugin this is a harmless single redundant
reload.
The state file is required. The plugin writes its tracked state to
profileDir/.dsh-hot-reload-state.json. If that file cannot be written — for
example because the profile directory is read-only — the plugin refuses to
start (it throws) rather than running with in-memory-only state.