Introduction

The philosophy of DSH is “everything is a plugin”. The final behavior of a profile usually comes from the stacking of multiple patch layers. The problem is that certain configuration errors won’t make dsh fail to start, but will cause the configuration to silently become ineffective. dsh-doctor is a health check tool maintained by asdf17128, used to check for configuration items in a DeepSeek Harness (dsh) profile that have been dropped by patches, become invalid, or are not loaded. Below is an introduction to its scope of checks, usage, and boundary cases to be aware of.

What is this

The positioning of dsh-doctor is: Health check for your DeepSeek Harness (dsh) profile — finds config fields your patches silently dropped, dead patches, and unmaintained plugins.

It can be used in two ways:

  1. As a command-line tool to directly check a dsh profile.
  2. As a dsh plugin installed in a profile, registering the config_doctor tool.

The license is MIT.

Core Checks

dsh-doctor checks the following types of issues:

  • config-clobber: Default fields are lost after a patch completely replaces an entry’s config without overwriting them.
  • dead-patch: The patch points to a non-existent entry ID, causing the patch to be ineffective.
  • tool-collision: Two mounted plugins register the same tool name, causing dsh to refuse to start.
  • plugin-not-mounted: An installed but never loaded plugin.
  • plugin-stale: Third-party plugins with no npm release for over 180 days.
  • entry-removed: Shipped entries removed by patch layers.
  • entry-toggled / entry-added: Differences compared to the shipped profile, reported as info.

It is a more convenient usage order to perform basic checks first, then use --explain to view the current profile tree.

How it Works

dsh-doctor performs a diff on the synthesized result of dsh’s own configuration:

dsh --profile <p> --dump-config
dsh --profile <p> --dump-default-config

The first command gives the actual profile tree that starts up, and the second command gives the default tree without the user layer. dsh-doctor attributes the difference between the two to the user patch layer. During the check process, plugins are not started, and !!js expressions in the configuration are not evaluated.

Installation and Activation

As a command-line tool, you can run it directly:

npx dsh-doctor

If you want to install it as a DSH plugin to the web profile:

dsh plugin --profile web add github:asdf17128/dsh-doctor

After installation, it registers the config_doctor tool in that profile. To remove it, use:

dsh plugin --profile web remove dsh-doctor

Typical Usage

Common commands are as follows.

Basic check:

npx dsh-doctor

Check another profile:

npx dsh-doctor --profile headless

View profile tree:

npx dsh-doctor --explain

--explain describes states like active, disabled, and conditional in the profile tree. For entries where disabled: is an !!js expression, the report will mark them as conditional, because the actual enabled state depends on the machine starting it, rather than being evaluated at the time of the check.

Output and run options:

npx dsh-doctor --verbose
npx dsh-doctor --json
npx dsh-doctor --offline
npx dsh-doctor --quiet

If you confirm that you need to fix the merged missing fields:

npx dsh-doctor --fix

Boundaries of –fix

--fix writes to files. It only rewrites the marked missing fields into the same config block and creates a .bak before writing. dead-patch cannot be automatically fixed, as renaming or deleting is determined by the user.

Exit Codes

  • 0: Clean or only warnings.
  • 1: At least one error.
  • 2: Unable to check.

After the above steps, you can determine whether to continue processing based on the exit code in your local workflow.

Use Cases and Notes

Suitable for:

  • AI agents maintaining DSH profiles.
  • Confirming if patches are still valid after dsh version changes.
  • Workflows that need to treat profile configuration issues as error signals.

Notes:

  • Requires Node 18+ and an available dsh; prefer using the local node_modules/.bin/dsh, otherwise use the dsh in PATH.
  • Verified compatible with @deepseek-ai/dsh 0.1.0-rc.5. dsh is in developer preview and may introduce breaking changes.
  • --fix writes to files, but only writes the marked config blocks and creates a .bak first.
  • Running on $DSH_HOME where there is no profile yet may cause dsh to create profiles/<name>/ template directories.
  • After installing and enabling as a DSH plugin, it runs within the permissions available to the current dsh process. You should check the source code before installing and confirm the MIT license fits your usage requirements.

Links

GitHub: https://github.com/asdf17128/dsh-doctor

Directory Page: No specific URL provided for the directory page, avoid fabricating it; search for dsh-doctor in the DSH community directory.