Introduction

DeepSeek Harness (DSH) introduced a declarative cordis.patch.yml mechanism in version 0.1.7+ and removed the legacy directory scanning mode. During framework upgrades, existing Agent preset declarations are highly prone to becoming invalid due to package renames, configuration key changes, or syntax migrations, causing the UI to only show “Failed to load” and making it difficult to locate the specific cause.

dsh-preset-doctor is a DeepSeek Harness plugin designed to automatically detect and repair these invalid preset declarations. It uses deterministic code with zero LLM involvement to handle the full process from legacy format migration and package name replacement to atomic repair.

Core Features

This plugin provides the following automation capabilities:

  1. Automatic scanning: Detects invalid Agent preset declarations.
  2. Automatic migration: Automatically converts legacy directory structures into declarative patches.
  3. Automatic replacement: Automatically replaces renamed package names based on migration tables.
  4. Configuration key splitting: Automatically splits the text key in persona configuration into prefix and suffix.
  5. Path rewriting: Automatically rewrites local paths (.//../) into file:// URLs.
  6. Safe writing: Automatically creates a backup (.bak) before repair and performs atomic writes, supporting idempotent operations.
  7. Chain convergence: Supports chained convergence to handle version drift, ensuring presets from different eras are uniformly adapted to the current version.

Installation and Enabling

Install the plugin globally via npm, then add it to DSH.

npm install -g dsh-preset-doctor
dsh plugin add dsh-preset-doctor

After installation, the plugin scans $DSH_HOME/cordis.patch.yml, profiles/<name>/cordis.patch.yml, and the legacy .agent-presets/ directory about 1 second after the DSH process starts.

Usage

For repairs to take effect, the DSH process must be restarted (the preset registry is only loaded at startup). You can run the following commands in a session:

  • /preset-doctor: Scans and automatically performs mechanical repairs.
  • /preset-doctor scan: Scans and reports only, without performing disk writes.

Technical Details and Limitations

  • Zero LLM involvement: Fully based on static analysis and repair using the @deepseek-ai/schemastery and yaml libraries.
  • Syntax repair only: The plugin guarantees that repaired presets have valid, loadable syntax, but does not guarantee that the repaired behavior is fully equivalent to the older version.
  • Installation behavior: The plugin installation process itself does not install dependencies, modify package.json, or restart the process.
  • Environment dependencies: The host version must satisfy the engines.dsh requirement (>=0.1.1-rc.1) and depend on @deepseek-ai/cordis (>=4.0.1 <5).

Resources

  • GitHub: https://github.com/drscrewdriver/dsh-preset-doctor
  • Directory page: https://www.skillhub.cn/plugins/drscrewdriver/dsh-preset-doctor