Introduction

The core architecture of DeepSeek Harness (DSH) is built around plugins. When dependencies between plugins conflict, versions mismatch, or global resources are contested, the host often fails to start or exhibits abnormal behavior. Troubleshooting directly is cumbersome and especially difficult in a crashed state. dsh-compat-guardian is a plugin focused on detecting, isolating, and recovering plugin compatibility issues. Through its sidebar interface and standalone command-line tools, it helps developers identify conflicts on the plugin management page, Web interface, or CLI, automatically isolate problematic plugins, and attempt repairs.

Core Features

The plugin provides multi-layered compatibility checking and repair mechanisms:

  • Environment and Version Checks: Checks DSH version requirements, Node.js, and the system environment.
  • Declarative Conflict Detection: Parses the dshCompat metadata of plugins to check declared dependencies, mutual exclusions, globally exclusive tools and services, and duplicate top-level entries.
  • Runtime Monitoring: Monitors consecutive loading failures in the Loader.
  • Isolation and Recovery: Supports automatic isolation of conflicting plugins (default policy) or automatic uninstallation. Provides recovery functionality to re-enable isolated plugins based on a record ID.
  • Standalone Diagnostics: Provides independent check and offline repair commands for use when the DSH host fails to start.

Installation and Enablement

In the DSH plugin management page, enter the following package name in the installation box:

dsh-compat-guardian@0.2.1

Or install using the Desktop command line (Web users should change desktop to web):

dsh plugin --profile desktop add dsh-compat-guardian@0.2.1 --save-exact --ignore-scripts

After installation, a “Compatibility Guardian” entry appears in the sidebar. By default, plugins are automatically isolated when conflicts are detected; uninstallation must be selected as the policy.

Typical Usage

Web Interface Operations

Open “Compatibility Guardian” in the sidebar to view check results, the plugin list, and recovery records. It supports upgrade pre-checks without actually upgrading DSH; it only calculates compatibility.

Configure automatic policies through cordis.patch.yml, for example setting remove to automatically uninstall conflicting plugins:

- id: compat-guardian
  config:
    policy: quarantine
    intervalMs: 30000
    failureThreshold: 2

Command-Line Tools

Guardian provides standalone CLI tools that can be used when the host crashes.

View help:

npx --yes --package=dsh-compat-guardian@0.2.1 dsh-compat-guardian --help

Common commands:

  • check: Checks currently installed and running plugins.
  • history: Views isolation, uninstallation, and recovery records.
  • restore: Restores an isolated plugin (recordId is required).
  • rescue: Performs offline repair, backs up the configuration, and disables conflicting bundles.

Applicable Scenarios and Notes

This tool is suitable for development and maintenance scenarios with DSH 0.2.0-rc.2 and later (Peer declaration range >=0.2.0-rc.2 <0.3.0-0).

Notes

  • dshCompat Is Not an Official Standard: This is a custom metadata field defined by this plugin for declaring mutual exclusions. Plugin authors should add this field to package.json.
  • Permission Limitations: Guardian runs with the current DSH process permissions and cannot intercept process.exit(), native crashes, or host exit early in startup. Such situations require the standalone CLI to handle.
  • Configuration Location: Automatic policy configuration is stored under the profile’s .compat-guardian/preferences directory.
  • Source Build: To build from source, you need to run steps such as npm ci, typecheck, test, and build.

Summary

dsh-compat-guardian provides a necessary “safety net” for the DSH plugin ecosystem, effectively reducing the risk of startup failures caused by configuration conflicts.