Introduction

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. When anomalies occur during plugin installation, upgrades, or runtime — such as startup failures, silent service outages, or broken dependencies — traditional troubleshooting approaches often fail to identify the root cause. The dsh-repair plugin aims to provide diagnostic and repair capabilities for DSH deployments to address these issues.

What It Is

This is a DSH plugin maintained by gezi-wen. It includes one skill that is placed into the agent’s skill directory along with the plugin. This skill focuses on fixing installation failures, dead plugins, broken dependency bridges, and upgrade-related issues.

Installation

Install it using the official command:

dsh plugin --profile web add dsh-repair

Core Features

The plugin covers common operational pain points in DSH through a series of scripts and skills:

  1. Startup and Filesystem Failures

    • Detects Boot crashes before the readiness stage (e.g. ERR_MODULE_NOT_FOUND, cannot resolve profile bundle).
    • Repairs junction/symlink traversal corruption in plugin node_modules.
    • Audits or repairs symlinks and junctions via link-doctor.js.

  2. Silent Runtime Failures

    • Diagnoses silently failing services, such as missing providers on model pages or disabled buttons.
    • Handles cases where configuration parses successfully but apply throws exceptions.
    • Resolves cases where adapters silently drop model IDs not present in their directories.
    • Uses inspect-session.js to extract runtime evidence from session files.

  3. Dependency Bridges

    • Handles the bridging mechanism for out-of-tree plugins (link:) that cannot access host core packages.
    • Performs read-only health checks with bridge-doctor.js.
    • Rebuilds dependency bridges with bridge-rebuild.js (dry-run preferred).

  4. Upgrade Process

    • Before upgrade: stop instances, back up, and run isolated dry runs.
    • After upgrade: perform three-layer verification and review settings.yaml.

  5. Windows Remote Jobs

    • Covers pitfalls when working on Windows DSH instances over SSH from another machine, including process lifecycle, quote escaping, PowerShell, pnpm junctions, and path drift.

Script Usage

The plugin includes six scripts for specific repair operations:

  • bridge-doctor.js: dependency bridge health checks and rebuilding.
  • bridge-repair.js? Wait: keep original bridge-rebuild.js: dependency bridge rebuilding (dry-run preferred).
  • bridge-lib.js: shared probing logic.
  • dep-diff.js: compares version tables of two node_modules directories.
  • inspect-session.js: obtains runtime evidence from session files.
  • link-doctor.js: audits/repairs symlinks and junctions.

Technical Details

  • Package type: This package is an ESM package, but the six scripts above are written in CommonJS.
  • Path resolution: Paths are always resolved from --home or $DSH_HOME; no machine-specific paths are hard-coded, supporting cross-machine operations.
  • License: MIT License.

Notes

  • This plugin runs with the permissions of the current dsh process; review the source code and license before installation.
  • During installation, the skills/ directory in the package is registered as a skill root.

References

  • Plugin directory: https://www.skillhub.cn/plugins/gezi-wen/dsh-repair
  • Code repository: https://github.com/gezi-wen/dsh-repair