dsh-plugin-doctor
English · 中文
English
Health checks for DeepSeek Harness plugins — the practical answer to the dsh plugin check idea from RFC #1629, until the official command exists.
It works in two ways:
- CLI (dsh-plugin-doctor / node lib/bin.js) — run it in your terminal or CI before opening a PR.
- Plugin shell (dsh plugin add) — once installed in DeepSeek Harness, the agent can call the plugincheck tool directly: "check whether this plugin is ready to publish", no shell needed.
What it checks
| Check | What it verifies | Default | |---|---|---| | manifest | package.json exists; dsh.bundle + dsh.bundle.patch + prepare + main present | ✅ | | patch | cordis.patch.yml parses as YAML and contains at least one insert row with an id | ✅ | | entry | main target exists (warns when not built yet) | ✅ | | files | a files allowlist is declared | ✅ | | build | pnpm run build succeeds | --build | | pack + install + config | pnpm pack, install into a fresh DSHHOME profile, and confirm the plugin id in --dump-config | --full | | profile-shadow | a dsh profile has no real-directory @deepseek-ai/ copy shadowing the host instance (discussion #1697) | --profile <dir | | manifest-bom | a dsh profile's package.json has no UTF-8 BOM (crashes dsh web at boot, discussion #1842) | --profile <dir | | large-files | no profile file exceeds 100 MB (session logs can hit the ~512 MB stringify cap, discussion #1859) | --profile <dir | | entry-points | every installed plugin's main/exports target exists (source-copy installs without a build crash dsh web at boot, discussion #1965) | --profile <dir | | profile-deps | the runtime @deepseek-ai scope is present (a bare npm install in a profile dir prunes the shared tree, discussion #2081) | --profile <dir | | native-modules | koffi/node-pty are present in the runtime tree (npm 11 allow-scripts=false skips native builds, discussion #2081) | --profile <dir | | pre-execute-side-effects | pre-execute listeners do not run host-level side effects before approval (heuristic lint, discussion #1863) | default pipeline | | shell-launcher | childprocess usage does not invoke explorer/start/open/powershell/cmd surfaces that can bypass approval/workspace limits (heuristic, discussions #1923/#1863) | default pipeline | | node / pnpm / dsh-path / port-3080 / win-bash | environment diagnostics: toolchain on PATH, Web UI port free, and Windows bash resolvable for the minimal preset (discussion #1856) | --env |
Exit code is 0 when nothing failed, 1 otherwise. --json prints a machine-readable report for CI.
Evidence-first plugin audit
audit is a separate, read-only inspection mode. It never imports the target plugin, runs lifecycle scripts, installs dependencies, or contacts a registry. It reports:
- package identity, source repository metadata, local Git revision when available, and a SHA-256 digest of the inspected content;
- install/prepare/publish lifecycle scripts, declared dependency sources, and lifecycle scripts from locally installed direct dependencies;
- every Cordis patch operation, the affected entry ids and configuration keys, runtime !!js expressions, and changes that disable approval or sandbox entries;
- observed filesystem, network, process, environment, credential, dynamic-code, native-code, persistence, browser-storage, session-data, clipboard, and dynamic-module-loading capabilities;
- findings with stable rule ids, severity, confidence, redacted file-and-line evidence, coverage gaps, and honest limitations;
- upgrade differences when --compare <old-directory is supplied.
The scanner prefers the package's declared published files surface. When the declared main build output is absent, it falls back to the working tree and records that choice. Working-tree fallback skips tests, fixtures, examples, demos, ordinary JSON data, and undeclared development scripts; paths explicitly declared for publication are still scanned. Network combinations distinguish fixed external destinations from same-origin/loopback calls and dynamic destinations. Large generated bundles and source matches in distant file sections lower confidence because co-location is not proof of data flow.
CLI usage
npx dsh-plugin-doctor . # quick checks on the current directory
npx dsh-plugin-doctor --build ./my-plugin
npx dsh-plugin-doctor --full ./my-plugin
npx dsh-plugin-doctor preflight ./my-plugin # alias: build + full pipeline (discussion #1774)
npx dsh-plugin-doctor check ./my-plugin # same pipeline; matches the proposed `dsh plugin check` surface (RFC #1846)
npx dsh-plugin-doctor --json ./my-plugin
npx dsh-plugin-doctor audit ./my-plugin
npx dsh-plugin-doctor audit ./new-version --compare ./old-version --json
npx dsh-plugin-doctor audit-batch ./plugins/plugin-a ./plugins/plugin-b --json
npx dsh-plugin-doctor audit-batch ./plugins/* --markdown > plugin-ecosystem-audit.md
npx dsh-plugin-doctor --profile ~/.dsh/profiles/web # profile tripwire: host-shadowing + manifest BOM
npx dsh-plugin-doctor --env # environment diagnostics (node/pnpm/dsh PATH, port 3080)npx dsh-plugin-doctor env explain DEEPSEEKAPIKEY # secret-safe env provenance (RFC #1953) npx dsh-plugin-doctor env explain MYKEY --json # machine-readable envelope; value always [redacted] npx dsh-plugin-doctor --help
Run from the repo without installing (after `pnpm build`):
node lib/bin.js --full ./my-plugin