Preface

DeepSeek Harness (DSH) supports extending functionality through plugins, and the community maintains a public plugin list. Before submitting a plugin to this list, it must comply with a specific set of specifications. Manually checking dsh.bundle configuration, cordis.patch.yml mount relationships, and peerDependencies version ranges is error-prone, especially when dealing with pre-release versions of DeepSeek Harness.

dsh-plugin-preflight is a tool specifically designed to address these issues. It automatically verifies that a plugin’s structure complies with the specification and detects common compatibility problems before submission or release.

What Is This

dsh-plugin-preflight is a zero-dependency DSH plugin for performing preflight checks on DeepSeek Harness plugins.

  • Maintainer: AphyTOT
  • License: MIT
  • Core Positioning: A developer diagnostic tool for automated validation before plugin submission.

Core Features

The tool primarily validates the following five areas:

  1. dsh.bundle Manifest Validation
    Checks whether the dsh.bundle configuration exists and is correct. Declaring only dsh.client without dsh.bundle is the most common reason for plugin submission rejection.
  2. cordis.patch.yml Mount Check
    Validates that the file pointed to by dsh.bundle.patch exists and that the patch layer is correctly mounted (checking that line names and IDs match).
  3. Client Package Shape Validation
    Checks whether the dsh.client exports are correct to ensure that the client module system can load the package.
  4. Peer Dependencies Compatibility
    Detects pre-release version compatibility issues in peerDependencies. DeepSeek Harness releases pre-release versions (such as 0.1.5-rc.2), and ordinary version ranges may silently exclude these versions, causing runtime ERESOLVE errors.
  5. Manifest Integrity
    Checks package.json for a BOM, marketing language, missing repository URL, and whether the CLI executable is included in files[].

Installation and Activation

Add this plugin to the current DSH configuration file:

dsh plugin --profile web add dsh-plugin-preflight

After installation, it registers a read-only, model-facing tool in the DSH environment. You can call it directly in a DSH session:

plugin_preflight(dir)

Typical Usage

After installation, you can run the preflight check via the command-line tool in any directory.

Check the current directory:

npx dsh-plugin-preflight

Check a repository at a specified path:

npx dsh-plugin-preflight path/to/repo

Use in CI (fail on warnings):

npx dsh-plugin-preflight --strict

Use Cases and Notes

Use Cases
* Self-check before submitting a plugin to awesome-dsh-plugin.
* Ensure the manifest and dependency configuration are correct before publishing a plugin to npm.

Cautions

  • Runtime Environment: The development environment has only been tested on Windows.
  • npm Publishing: The plugin has not yet been published to npm, and the direct npm installation path has not been validated.
  • Local Path Installation: When installing via a local path, the system creates a junction (similar to a symbolic link on Windows); this is actually the behavior of pnpm link. Since Node resolves ESM imports by searching upward for node_modules through real paths, this may prevent the host package from being found correctly. This plugin avoids the issue by lazily loading the host package, ensuring that even if the runtime environment is unreachable, the plugin can run as a CLI tool without crashing the DSH process.
  • Pre-release Version Validation Scope: Validation for peer/prerelease-tuple is currently based only on fixtures (test data) and has not been comprehensively tested against a large number of actually published plugins.

Conclusion

dsh-plugin-preflight can cover most of the machine-verifiable rules in the plugin submission specification. By running it locally or in CI, you can avoid submission rejection or runtime errors caused by manifest misconfiguration or version range pitfalls.