DeepSeek Harness (dsh) uses a plugin-based architecture. The built-in hot reload mechanism (cordis-plugin-hmr) deliberately ignores node_modules, so upgrading an installed plugin (dsh plugin add pkg@x) usually requires a full dsh restart to take effect. The dsh-hot-reload plugin fills this gap: it watches the current profile’s pnpm-lock.yaml, and when the version of a loaded plugin package changes, it swaps the plugin instance live while running.

The following sections describe how to use this plugin.

Feature Overview

dsh-hot-reload provides the following core capabilities:

  1. Hot reload: Upgrade plugin code in real time without stopping the dsh process. dsh automatically invalidates the module cache and reimports the new code.
  2. Safe rollback: If loading or initializing the new code fails, the plugin automatically falls back to the previous stable version, ensuring service continuity.
  3. State persistence: The plugin writes its own state to a file, enabling hot reloading of the plugin itself.
  4. Result reporting: Reload results are written to dsh logs and the Web application.
  5. Generality: It works in any profile.

Installation and Activation

Installing the plugin requires specifying a profile (for example, web):

dsh plugin --profile web add dsh-hot-reload

After installation, dsh must be restarted once. This is because plugin configuration (such as cordis.patch.yml) is loaded at startup. After the restart, the plugin becomes active.

Typical Usage

Upgrading a Plugin

After the plugin is installed, subsequent plugin upgrades automatically trigger hot reload. Simply run the upgrade command:

dsh plugin --profile web add some-plugin@newer

Viewing Detailed Logs

The plugin outputs only a single concise line to the terminal. To view all log details (including warnings and diagnostic information), additionally add the console logger plugin:

dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console

Then enable this plugin in the profile configuration and restart dsh.

Notes and Limitations

Before using this plugin, confirm the following environment requirements:

  • Version requirements: dsh version 0.1.0-rc.6 and Node.js version >= 22 are required.
  • State file: The plugin runtime depends on the state file profileDir/.dsh-hot-reload-state. This file is maintained by the plugin and records committed versions, failed versions, and notified versions.
  • Failure retry: The plugin does not automatically retry failed versions. If an upgrade fails, you need to manually choose another version or restart dsh.
  • Full-screen interfaces: In full-screen profiles such as tui, the terminal prompt line for hot reload may appear in the middle of the screen until the interface refreshes. This does not affect functionality, but may temporarily affect the display.
  • Browser messages: Notification messages in the Web application are displayed only once and are not persisted. If the browser is not open, the message is lost, but it is recorded in the logs.

Summary

dsh-hot-reload solves the pain point that upgrading plugins in the DSH environment requires a restart. By watching pnpm-lock.yaml, it enables safe, in-place plugin replacement. With state files and log reporting, it can update code without interrupting the service, making it suitable for development scenarios that require frequent iteration on plugin logic.