Preface¶

After working with DeepSeek Harness (DSH) plugins for a long time, you inevitably encounter situations such as DSH crashing, failing to start, or a plugin corrupting a profile. DSH lacks a built-in doctor command. Most of the time, you are left guessing the cause from error logs, hoping restarting the process will fix it, or manually sifting through configuration files to troubleshoot.

The dsh-doctor introduced below addresses this issue: it starts with read-only diagnostics to tell you what is broken and why; then proceeds with tiered fixes, where every change is reversible; and if something goes wrong, it even supports one-click rollback.

What is It¶

dsh-doctor (@jorinyang/dsh-doctor, current version 0.3.2) is a DSH plugin maintained by jorinyang. It is designed as an integrated “diagnosis + repair + rollback” tool and also acts as a runtime self-healing service. It is released under the MIT license, consisting of a standalone plugin and CLI that do not modify the DSH core and do not conflict with DSH’s built-in commands.

Core Features¶

Read-Only Diagnostics¶

It provides two interfaces: the dsh_doctor tool and the dsh-doctor CLI, both for performing read-only checks. It covers 9 major categories, reporting where the issues lie and why, without modifying any files.

Tiered Repair¶

The corresponding tool is dsh_doctor_fix, and the CLI command is dsh-doctor fix. The repair process is divided into three tiers:

Every repair generates a journal that records the undo steps for each change. Specifically: files that are overwritten will have their original content saved and restored during rollback; newly created files/directories will be deleted upon rollback (only empty directories); and system-level operations (such as pnpm install or killing processes) will be marked as “requiring manual intervention.”

Rollback¶

The corresponding tool is dsh_doctor_rollback, and the CLI command is dsh-doctor rollback. Rollback is executed in reverse order, restoring the state to before the repair. rollback --list lists all repair logs, and rollback --id <id> allows you to rollback a specific entry.

Runtime Self-Healing Service¶

Besides the offline CLI, dsh-doctor also integrates into running DSH as a Cordis service:

1. Exposes diagnosis/repair/rollback APIs to other plugins via ctx.provide (service name: dsh-doctor);
2. Reactively monitors plugin lifecycle via ctx.on('internal/status') and automatically alerts upon detecting a FAILED status;
3. Declares reversible effects via ctx.effect(), ensuring no residue remains upon uninstallation.

In other words, when DSH is running, it can dynamically diagnose and monitor, rather than requiring a shutdown to repair.

Self-Contained CLI and Cross-Platform¶

dsh-doctor is a self-contained CLI that does not rely on DSH running. Even if DSH crashes to the point where plugins cannot load, you can still execute dsh-doctor fix directly. It supports Windows / macOS / Linux / fish, automatically registers to the system PATH after installation, or you can manually register using dsh-doctor setup.

Installation and Activation¶

Method 1: Install as a DSH plugin for use within the Agent:

dsh plugin --profile web add @jorinyang/dsh-doctor
dsh web

The first command installs the plugin from npm, and the second command restarts dsh web to apply it.

Method 2: Install the CLI globally for direct use in the command line:

npm install -g @jorinyang/dsh-doctor
# Or run directly without installation
npx @jorinyang/dsh-doctor

The plugin’s peerDependencies are @deepseek-ai/cordis ^4.0.1-rc.1, @deepseek-ai/dsh-tools, and @deepseek-ai/schemastery ^3.18.1-rc.1.

Typical Usage¶

The most basic workflow is to diagnose first, then repair:

dsh-doctor          # Read-only diagnostics (default behavior, aliases: diagnose / check)
dsh-doctor fix      # Repair (alias: repair)

The diagnostic output looks like this (example from the project README):

DSH Diagnostic Report  (profile: web, port: 3080)
DSH home: ~/.dsh

  [OK]   Node.js v24.15.0
  [OK]   pnpm 11.9.0
  [OK]   DSH 0.1.0-rc.6
  ...
  [XX]   bundle missing: some-broken-plugin
         fix: Run pnpm install in profile dir

  48 pass  0 fail  3 warn

Rollback-related commands:

dsh-doctor rollback              # Rollback the most recent fix
dsh-doctor rollback --list       # List all repair logs
dsh-doctor rollback --id <id>    # Rollback a specific log

When using within the Agent, simply tell the agent in the conversation:

Run dsh_doctor                    # Diagnose
Run dsh_doctor_fix with safe scope # Repair
Run dsh_doctor_rollback           # Rollback if needed

There are three general options: --profile <name> to specify the DSH profile (default web), --port <number> to specify the Web port (default 3080), and --scope <level> to specify the repair scope (safe / deps / full, default safe).

Regarding scope selection, the three tiers are progressive in risk: it is recommended to start with safe, which only involves files and configurations; if the issue persists, upgrade to deps to reinstall dependencies; and finally, consider full to clean up processes.

Use Cases and Considerations¶

Suitable for: developers who frequently tinker with DSH plugins and profiles, especially those who need to ensure DSH remains usable and do not want to spend time troubleshooting crashes. It does not require you to understand the error messages; the diagnostic report directly points out the issues and provides repair suggestions.

A few points to note before use:

1. The full scope terminates residual processes; please confirm that no critical tasks are running before executing it;
2. System-level operations (such as pnpm install or killing processes) cannot be automatically undone and will be marked as “requiring manual intervention” in the journal; please pay attention to such changes after rollback;
3. The plugin runs with the permissions of the current DSH process; it is recommended to check the source code and license before installing. dsh-doctor uses the MIT license, and the source code can be viewed directly on GitHub.

Conclusion¶

dsh-doctor converges the post-crash processing workflow of DSH into three steps: dsh-doctor diagnosis, dsh-doctor fix repair, and dsh-doctor rollback. Combined with the runtime self-healing service, it makes the act of “fixing a mistake” itself controllable.

Project homepage: https://github.com/jorinyang/dsh-doctor

Community directory page: https://www.skillhub.cn/plugins/jorinyang/dsh-doctor (The community directory is an independent site and has no official affiliation with DeepSeek / Hypothesis)