Preface¶

DSH’s philosophy is “everything is a plugin”; installing a plugin is often just one command. But the DSH plugin ecosystem is still evolving rapidly, and many plugins remain at the rc stage: the peerDependencies declared by a plugin says @deepseek-ai/dsh-tools@^0.0.1, while the local installation is 0.1.0-rc.6. This mismatch, once installed, can result in tools not working at best, or the web interface failing to start at worst.

Manually opening each package.json to verify is clearly impractical. The dsh-plugin-doctor described below turns “check before installing” into a single sentence: let DSH itself run a health check on the target plugin, then decide whether to install based on the result.

What Is This¶

dsh-plugin-doctor is an open-source DSH plugin maintained by lin-cheng-lab (MIT license, classified as admin-security in the community catalog). It is positioned as a “DSH plugin health-check tool”: before installing any DSH plugin, it checks repository accessibility, bundle declaration, compatibility between peer dependencies and local versions, and build artifacts, preventing startup crashes caused by rc version mismatches.

In implementation, it uses ctx.tools.register(defineTool(...)) to register itself as a tool, loading and unloading with the profile. In other words, there is no need to leave DSH and run a separate script; you can simply ask it to do the job using natural language.

What It Checks¶

The health check consists of five items:

Local environment: reads the local DSH / cordis / dsh-tools / dsh-workflow versions as the baseline for later comparisons.
Repository accessibility: checks whether the plugin repository is public; a 404 is blocked immediately to prevent installing “ghost plugins.”
Bundle declaration: checks whether dsh.bundle.patch is declared (the official installable format).
Peer compatibility (core): performs semver matching item by item between the versions required by the plugin and the locally installed versions, correctly handling prerelease (rc) rules — this is exactly the root cause of the startup crash scenario mentioned at the beginning.
Build artifacts: checks whether the entry file pointed to by main has been committed to the repository.

Two implementation details:

The network check uses the built-in DSH web service (ctx.web.fetch); local versions are read from the globally installed DSH package manifest via the fs service, without requiring additional permissions.
Semver matching is implemented as a built-in pure function with zero dependencies, supporting ^, ~, >=, <=, >, <, =, *, and multi-condition ranges.

How to Read the Health-Check Result¶

The conclusion has three levels: ok (safe to install), warn (proceed with caution, watch out for risk items), and danger (do not install; installing will crash).

The report is structured JSON, including the fields target, verdict, summary, checks, and recommendation. Among them, checks provides name / status / detail / items for each item. Below is an output example from the README (excerpt), showing what a peer-compatibility failure looks like:

{
  "target": "dsh-external/dsh-deep-research",
  "verdict": "danger",
  "summary": "体检不通过，不要安装",
  "checks": [
    { "name": "本地环境", "status": "pass", "detail": "DSH 0.1.0-rc.6 · cordis 4.0.1 · dsh-tools 0.1.0-rc.6 ..." },
    { "name": "仓库可访问", "status": "pass", "detail": "github.com/dsh-external/dsh-deep-research 可访问" },
    {
      "name": "peer 兼容性",
      "status": "fail",
      "detail": "2 个 peer 依赖与本地版本不匹配（rc 不匹配风险！）",
      "items": [
        { "dep": "@deepseek-ai/dsh-tools", "required": "^0.0.1", "installed": "0.1.0-rc.6", "ok": false },
        { "dep": "@deepseek-ai/dsh-workflow", "required": "^0.0.1", "installed": "0.1.0-rc.6", "ok": false }
      ]
    }
  ],
  "recommendation": "不要安装：存在不兼容项，装进去可能导致启动崩溃。等插件更新适配后再装。"
}

recommendation provides the corresponding handling advice, such as waiting for the plugin to be updated and adapted before installing.

Installation and Enablement¶

The README provides two installation methods. The GitHub method is currently labeled “after release” and contains a placeholder; before release, please refer to the repository README:

# 从 GitHub 安装（发布后）
dsh plugin --profile web add "github:<你的用户名>/dsh-plugin-doctor"

At the current stage, local source installation is more direct. First clone the repository to any local path, then run:

dsh plugin --profile web add "file:/path/to/dsh-plugin-doctor"

After installation, the profile must be restarted for it to take effect:

dsh --profile web

Note that the plugin itself declares peer dependencies @deepseek-ai/dsh-tools ^0.1.0-rc.6 and @deepseek-ai/cordis ^4.0.1, and the local DSH environment must satisfy them.

Typical Usage¶

After the steps above, you can trigger a health check with a single sentence to DSH:

Please use plugin_doctor to check dsh-external/dsh-deep-research for me.

The tool accepts three types of input:

GitHub repository URL: https://github.com/owner/repo
owner/repo shorthand: owner/repo
npm package name: @scope/name or name

Local Build¶

If you want to modify the code or build it yourself, install dependencies and then compile:

npm install --legacy-peer-deps   # 安装 typescript（跳过未发布的 @deepseek-ai peer）
npm run build                    # tsc → lib/

Type resolution depends on @deepseek-ai/cordis and @deepseek-ai/dsh-tools from the local DSH installation. Symlinks need to be created first:

ln -sfn <dsh安装>/node_modules/@deepseek-ai/cordis  node_modules/@deepseek-ai/cordis
ln -sfn <dsh安装>/node_modules/@deepseek-ai/dsh-tools node_modules/@deepseek-ai/dsh-tools

Applicable Scenarios and Cautions¶

It is suitable for two types of users. First, users who frequently try third-party DSH plugins from GitHub or npm: running a health check before installation can avoid rc mismatches and “ghost plugins.” Second, plugin authors: before publishing, they can use it to self-check whether the bundle declaration, peer dependency ranges, and build artifacts are complete.

A few cautions:

The plugin runs with the permissions of the current dsh process. Before installing any third-party plugin (including this one), you should first inspect its source code and license.
The health-check result is a reference before installation: for the warn level, carefully review each risk item; for the danger level, do not install.
The current project version is 0.1.0, package.json is marked private: true, and it is still in an early stage.

Summary¶

The problem solved by dsh-plugin-doctor is quite specific: in an “everything is a plugin” ecosystem, it turns pre-installation verification from manual item-by-item checking into a one-sentence health-check report. The scope of functionality is these five checks, and its advantages are direct conclusions and no extra permissions required.

Community catalog page: https://www.skillhub.cn/plugins/lin-cheng-lab/dsh-plugin-doctor
GitHub repository: https://github.com/lin-cheng-lab/dsh-plugin-doctor

dsh-plugin-doctor: Do a health check before installing the DSH plugin