lemonxiny55/dsh-composition-doctor

English | 中文

See exactly why your DSH profile looks this way.

DSH profiles are layered compositions. dsh-doctor shows which sources and layers contributed the rows you see, what the available evidence proves, and what remains unknown.

Read-only · Offline by default · No automatic fixes or installs

Composition and upgrade preflight doctor for DeepSeek Harness (dsh). It reads an explicitly selected profile and explains observable Cordis/plugin composition facts with concrete evidence. It never edits a real profile or silently changes permissions.

Quick start

npm install -g dsh-composition-doctor
npx @deepseek-ai/dsh plugin --profile web add dsh-composition-doctor
dsh-doctor --version

Then ask a concrete question about the composition:

dsh-doctor why row tool-bash --profile C:\path\to\profile
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile

why explains one observed row and its source chain. impact bundle lists rows and diagnostics directly associated with that bundle source.

flowchart LR
  B["Bundle<br/>direct association"] --> S["Source"]
  S -->|"introduced / patched-by"| R["Row"]
  L["Layer"] -->|"contains"| R
  R -->|"diagnosed-by"| D["Diagnostic"]

These links appear only when the report has supporting facts; missing ownership is left unknown.

Commands · Evidence boundaries · Safety & privacy · Compatibility · Development

What it explains

Command	Purpose
dsh-doctor scan	Detect duplicate Cordis rows, hook-order risks, UI slot/route ownership conflicts, bundle overrides, peer/platform mismatches, and profile drift.
dsh-doctor snapshot	Create a redacted, comparable profile snapshot with lockfile hashes.
dsh-doctor diff	Summarize added/removed/upgraded plugins, rows, hooks, UI claims, peers, and platforms.
dsh-doctor preflight	Rehearse a target DSH upgrade in an isolated temporary profile.
dsh-doctor why row <id>	Explain one row from an explicitly selected profile using observed source/layer facts.
dsh-doctor impact bundle <name>	List rows and diagnostics directly associated with an observed bundle source.

The why and impact commands require --profile <dir>. Reports include an optional, versioned, redacted compositionFacts section shared by these commands and the Web Composition Explorer. The Web Settings page remains display/export only: it reads the latest local report, shows diagnostic and composition graphs, and exports JSON/Markdown. It has no repair, install, or uninstall action.

Composition facts describe the structure returned by the public --dump-config command or static declarations when that is unavailable. introduced and patched-by edges describe the source chain recorded by DSH; they do not prove per-field ownership. If earlier config keys are not available, removed keys and field owners remain unknown. Route/slot ownership, runtime hook ownership, arbitrary dependencies, and possible dependents are reported as not observed/not modelled.

Reports and evidence boundaries

scan --output <dir> writes only to the requested directory. To make the same report visible to the read-only Settings page, opt in explicitly: --publish copies it to the default plugin directory .dsh-composition-doctor/reports, while --report-dir <dir> publishes to a configured plugin directory. Use --format both so the Web route has report.json and Markdown remains exportable. Do not use a profile directory, .env location, or any directory containing keys, tokens, or other secrets as a report directory.

Reports declare evidenceMode: static means allow-listed manifest/patch/package metadata only; composed means a public dsh --profile <name> --dump-config command returned a composition result; runtime-observed is reserved for a successful isolated runtime observation backend; and mixed is reserved for an adapter that supplies both. dump-config never proves runtime execution, including when a !!js or other runtime-dependent value is present. Static findings and bounded metadata coverage are not proof of the final runtime composition. If no compatible public DSH CLI is available, scan falls back to static and records a warning. Reports written before evidence schema 2 may still be read as legacy resolved, but new reports never emit that label.

preflight --candidate package@version records a validated exact reference in an isolated temporary package.json. Target artifact discovery is local-first (--dsh-bin, package directory, tarball, installed dsh, --package-manager-cache, then Doctor-owned cache); registry access is allowed only with explicit --online. Online resolution downloads exact registry tarballs into Doctor-owned cache, records source/version/integrity/hash, and never installs or runs lifecycle scripts. --allow-build does not grant permission to execute third-party runtime code.

scan --fail-on never|info|warning|error controls the scan exit code. The default is never: warnings and errors remain in the report without changing the exit code. info fails on any diagnostic, warning fails on warnings or errors, and error fails only on errors. Malformed arguments return exit code 2; operational failures return 1.

After changing a profile, restart the Web UI (npx @deepseek-ai/dsh web) before scanning it again.

Each finding is info, warning, or error and includes evidence, explanation, and the smallest remediation. runtimeSmoke.status=not-run is not a runtime PASS; artifact-unavailable is not incompatible; and a warning is not a confirmed failure.

More commands

dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.5-rc.2

Safety and privacy

Default operations are read-only or isolated under the OS temporary directory. The plugin does not modify profiles, install/remove plugins, migrate configuration, escalate permissions, or perform network I/O by default. It never reads .env, profile secrets, session bodies, or workspace file contents, and does not collect or persist arbitrary environment-variable values. Public CLI execution receives only the minimal process-routing variables required by the host platform.

Support and limitations

The real public CLI harness verifies @deepseek-ai/dsh@0.1.5-rc.1 and @deepseek-ai/dsh@0.1.5-rc.2. 0.1.6-alpha.1 remains expected-compatible/experimental only; 0.1.0-rc.6 is historical context, not a current verified target. Missing artifacts are reported as unavailable, never as PASS. Verified development runtime: Node.js 24 on Windows; CI covers Node.js 20 on Ubuntu. Runtime hook/UI ownership is reported as unverified unless public metadata supplies it, and a temp profile is not a security sandbox.

Development

pnpm test
pnpm typecheck
pnpm build

For checkout-only development, run the CLI with node dist/cli/main.js after building.

See README.zh.md, docs/compatibility.md, and docs/examples/scan-report.md. MIT licensed.