Foreword

DeepSeek Harness (DSH) adopts the “everything is a plugin” philosophy, with the host and plugins decoupled through interfaces. However, during host upgrades, breaking changes can occur, which may cause community plugins to become incompatible with the new host and lead to host startup failures.

dsh-upgrade-guard is a compatibility inspection plugin designed to address this pain point. It acts as a resident plugin in the host and automatically triggers an inspection on the first startup after a host upgrade. It can determine plugin compatibility, provide repair suggestions, and—when the host cannot start—rescue it or roll it back to the previous host version through a Supervisor process outside the host.

What Is It

This is an independent community project maintained by zzy6-a and licensed under the MIT License. It does not modify the host upgrade process, nor does it tamper with plugin source code. Instead, it acts as a “guard” that automatically audits the compatibility status of installed plugins after a host upgrade, and repairs or disables faulty plugins by modifying configuration files, thereby preventing the host from getting stuck in a “cannot start” state.

Core Capabilities

1. Automatic Post-Upgrade Inspection and Declared Compatibility Check

On the first startup after a host upgrade, the plugin runs automatically. It reads each installed plugin’s engines.dsh and peerDependencies and compares them with the resolved host/core version. If a plugin does not declare compatibility information, it cannot be determined in advance, so runtime fallback is required.

2. Composition Layer Hygiene Check

The plugin scans the host’s cordis.patch.yml for duplicate entry ids or invalid patch targets. If duplicates are found, it can clean them up with one click (keeping the last modification and automatically backing up to ~/.dsh/upgrade-guard/backups/ before the operation). It can also integrate with the dshmarket diagnostic API to merge issues related to duplicate, invalid, multi-version, or peer-mismatched market plugins.

3. Plugin Self-Check Probe

Plugin authors can declare dsh.compat.probe in the plugin package. The guard executes the probe in an independent Node child process and aggregates pass/fail results. This design ensures that the plugin’s own compatibility checks do not affect the stability of the host main process.

4. Startup Failure Rescue and Host Rollback

If loading the plugin tree fails and the host cannot start, all mechanisms inside the plugin become ineffective. In that case, a Supervisor outside the host acts as the fallback:
* Rescue: read the most recent startup logs, match the failed to apply loader entry error, use dsh --dump-config to map package names to entry ids, back up the patch and write disabled: true, then restart the host.
* Rollback: if rescue does not work, the guard starts the previous host version from ~/.dsh/upgrade-guard/host-snapshots/<version>/. A snapshot is a full copy of the host directory (approximately 300 MB) and defaults to retaining the two most recent snapshots.

Installation and Enabling

Use the following command to add the plugin to the DSH Web profile:

dsh plugin --profile web add https://github.com/zzy6-a/dsh-upgrade-guard/releases/download/v0.2.0/dsh-upgrade-guard-0.2.0.tgz

After installation is complete, restart DSH. The guard remains active as part of the profile bundle. You can enable it, check its status, or manually restart DSH from the “Upgrade Guard” card in the settings panel.

Configuration and Usage

Default Configuration in cordis.patch.yml

The guard supports default configuration in cordis.patch.yml:

- id: dsh-upgrade-guard
  config:
    autoScanMs: 0        # 自动扫描间隔（毫秒），0 = 仅启动/升级/手动
    supervisor: true     # 宿主外救援 / 回滚 / 重启
    snapshotHost: true   # 保留宿主快照用于回滚

Plugin Self-Check Probe Example

Plugin developers can define compatibility check logic by declaring dsh.compat.probe:

{
  "dsh": {
    "compat": {
      "probe": { "file": "./lib/probe.js", "export": "probe", "timeoutMs": 20000 }
    }
  }
}

The corresponding implementation file lib/probe.js is shown below:

// lib/probe.js —— ctx: { hostVersion, profile, dshHome, pluginDir }
export async function probe(ctx) {
  const ok = await checkSomethingAgainst(ctx.hostVersion)
  return { ok, message: ok ? '正常' : '与当前宿主不兼容的原因' }
}

Notes

  • File modifications: The guard modifies cordis.patch.yml and invokes package manager commands during repair. Before each write, it automatically backs up the file to ~/.dsh/upgrade-guard/backups/.
  • Permissions and scope: The guard does not intercept host upgrades, nor does it modify plugin source code. If no compatible version is available, the only options are disabling the plugin or rolling back the host.
  • Windows compatibility: Code-level compatibility for Windows environments has been implemented, but full validation on real machines has not been performed. If you encounter an issue, please include the logs under ~/.dsh/upgrade-guard/ when submitting an issue.
  • Project nature: This is an independent community project, not an official DeepSeek product.