In agent development, frequent updates to DeepSeek Harness (DSH) can easily introduce configuration errors or dependency conflicts, and direct upgrades may cause service interruptions. dsh-safe-updater ensures that the upgrade process is rollback-capable through isolated-environment validation, configuration verification, and health checks.

The plugin is maintained by lucifer726. It fetches versions from npm, clones a profile into an isolated DSH_HOME, installs dependencies, validates configuration, starts a temporary web server, and allows controlled switching. If health checks fail, it automatically rolls back to the previous version.

Installation and Default Configuration

Installing the plugin requires specifying a profile name. The following uses the web profile as an example:

dsh plugin --profile web add dsh-safe-updater

After installation, the plugin inserts default configuration. The default mode is notify, and it does not silently replace a running Harness:

- insert:
    - id: safe-updater
      name: dsh-safe-updater
      config:
        mode: notify
        channel: latest
        profile: web
        checkIntervalMs: 21600000
        checkOnStart: true

Core Modes

The plugin provides three modes. Switching is done by overriding the mode field in the configuration file or via the command line:

  1. notify
    Checks for and logs whether a new version is available. It does not perform installation or restart operations. This is the default mode.

  2. stage
    Clones the profile, performs dependency installation, configuration assembly, and HTTP smoke tests. It does not perform an actual restart. Suitable for pre-upgrade rehearsal.

  3. apply
    After stage completes, requests an external supervisor to perform version switching. This mode refuses to run in environments without an external supervisor.

Typical Usage

After installation, the following tools can be used for operations.

General Status Viewing

dsh_update_status

This command reads the current, available, staged, and rollback status.

Manual Check and Staging

Manually trigger a check or stage a specific version:

# 手动检查当前版本
dsh-safe-updater check --current-version 0.1.1-rc.1

# 手动暂存指定版本
dsh-safe-updater stage --version 0.1.1-rc.1 --profile web

Rollback Operations

If the staged version fails health checks, or if a rollback is needed during operation:

# 执行回滚
dsh-safe-updater rollback

Supervisor Mode

To enable automatic activation, run the supervisor under the Web profile:

dsh-safe-updater supervise \
  --version 0.1.1-rc.1 \
  --profile web \
  --host 127.0.0.1 \
  --port 3080

When the staged version is ready, the supervisor starts the process based on the parameters, waits for HTTP health checks, commits the switch if successful, and returns to previousVersion if failed.

Security and Trust Model

The plugin is designed with emphasis on security isolation and execution control:

  • Execution security: Registry version strings are parsed as semantic versions, and candidate commands use argument arrays (shell: false), preventing command injection.
  • Data isolation: The staging environment does not copy .credentials.yaml or other runtime data, preventing leakage of sensitive information.
  • State storage: State and lock files are stored under ~/.dsh/safe-updater, with restricted permissions and atomic replacement mechanisms.
  • Recursion prevention: Smoke mode disables the update timer, preventing recursive staging triggers.

Environment Requirements and Dependencies

To use this plugin, the following conditions must be met:

  • Node version: The Node.js version must be greater than or equal to 22.
  • Peer Dependencies:
    • @deepseek-ai/dsh-tools: version range >=0.1.1-rc.1 <0.2.0
    • @deepseek-ai/schemastery: version range ^3

Summary

dsh-safe-updater provides DSH with a rigorous automated update mechanism. It reduces the risk of version iteration in agent development through isolated-environment validation and an atomic rollback strategy. With the notify, stage, and apply modes, developers can choose to check, rehearse, or automatically switch depending on the scenario.

View plugin directory
View source