dsh-doctor

DSH Doctor

中文 | English

DSH Doctor is an upgrade and troubleshooting tool for DSH plugin developers and agents. It finds what needs to change during an upgrade, handles changes that are known to be safe, and then checks dependencies, build output, installation, and activation.

When a change depends on the plugin's business logic, Doctor calls it out for the agent or developer instead of guessing. Every edit is previewed and backed up first, and runtime checks use a temporary DSH environment rather than the developer's everyday profile.

This is a community-maintained third-party project, not an official DeepSeek project. The current migration scope is DSH 0.1.1 / 0.1.2 / 0.1.5 → 0.1.7. The default catalog exactly covers dsh-v0.1.1-rc.2 → dsh-v0.1.7-rc.2 (cumulatively including every earlier rule), alternate catalogs start from dsh-v0.1.2-rc.1 and dsh-v0.1.5-rc.2, and the 0.1.2 and 0.1.5 catalogs remain as history. Differences outside those catalogs still require a separate investigation and are not proven compatible by the catalog.

What it helps with

Agents can orchestrate these capabilities through the skill, while other tools can integrate the same structured CLI workflows.

Recommended: ask an agent to install and use the skill

Send this prompt to your agent:

Install this skill: https://github.com/bruc3van/dsh-doctor, and tell me how to use it.

You can also install the repository's dsh-plugin-upgrade skill manually:

npx skills add bruc3van/dsh-doctor

After installation, ask the agent from inside the plugin repository that needs migration:

Adjust and verify this plugin so that it is compatible with DSH 0.1.7.

The skill guides the agent to:

1. establish the plugin, actual DSH installation, Harness checkout, package manager, and usable DSH Doctor;
2. analyze source, dependencies, configuration, patches, and existing artifacts;
3. confirm whether the upgraded plugin release targets only 0.1.7 or must remain compatible with the 0.1.1, 0.1.2, or 0.1.5 version it supports today;
4. preview and apply exact changes allowed by that compatibility strategy, then handle semantic migrations that require business context;
5. rebuild and report static, artifact, isolated-runtime, and business-behavior evidence separately;
6. commit or publish through the plugin repository's own process only when the developer explicitly requests it.

npx skills add installs agent instructions only; it does not install DSH Doctor globally. The skill checks the local CLI and npm registry first. If the local version is unsuitable, it runs a pinned version through npm exec without changing the global installation.

An upgrade request does not itself authorize dropping the old runtime. When compatibility intent is missing, the skill may perform read-only analysis but asks before migration writes, dependency installation, build, or runtime commands. Dual-version mode requires separate evidence for the legacy version and 0.1.7; one 0.1.7 smoke test is not dual-version proof.

How it works

DSH Doctor has three parts that constrain one another:

• Skill: defines investigation steps, the compatibility decision, confirmation gates, and reporting standards for the agent;
• CLI: provides read-only analysis, safe edits, diagnosis, baselines, recovery, and staged verification;
• Migration catalog: stores exact DSH tags/commits and known package, symbol, Service, configuration, and behavior changes.

The plugin migration workflow is:

investigate the actual environment
  → catalog-driven analysis
  → reviewed-plan exact changes
  → agent handles semantic changes
  → build and artifact verification
  → temporary-profile installation and activation
  → plugin business-behavior verification

Moving from 0.1.1 to 0.1.7 changes more than package versions. 0.1.2 split legacy owners such as dsh-client-runtime and dsh-host-apiproxy, moving Session, Workspace, Conversation, and pending-interaction capabilities to new controllers, UI packages, or Services. 0.1.7 then moved plugin settings into .volatile() fields of the plugin's own Config (both settingsNamespace and ctx.settings.register are gone), renamed the code-runtime family to ptc-runtime, replaced dsh-agent-presets with declarative presets, and retired the E2B providers. The CLI only auto-edits relationships marked exact; ownership, lifecycle, and business-call changes are reported as MIG_SEMANTIC_API_CHANGE.

With an exact Harness checkout, Doctor also verifies the commits behind the two catalog tags and compares entry ids in the target web profile. The default cumulative catalog works for 0.1.1, 0.1.2, and 0.1.5 plugins; use --from dsh-v0.1.2-rc.1 or --from dsh-v0.1.5-rc.2 only when the plugin is already fully on that version and you want exact source-version evidence. After the additional source interval has been investigated, --target-version can bind dependencies and runtime checks to a newer 0.1.7 target, but it does not extend the catalog's API claims.

Core capabilities

No legacy string in source, a successful compile, an installable tarball, and correct business behavior are different evidence levels. Doctor does not present one as proof of another.

Safety and evidence

• diagnose, migrate analyze, and static verification are read-only and do not load or execute the inspected plugin;
• only migrations marked exact by the catalog can be changed automatically; semantic changes are not guessed mechanically;
• migrate apply uses a reviewed plan outside the plugin root and binds the full analysis, actual target version, and every input-file hash;
• SHA-256 is rechecked before writes, input drift rejects the apply, and existing files receive timestamped backups;
• build/runtime commands require explicit confirmation and synchronize dependencies with lifecycle scripts disabled;
• runtime verification uses a temporary DSH_HOME instead of installing into the developer's normal ~/.dsh;
• JSON, baselines, and recovery snapshots redact common secret, token, password, and key fields;
• global CLI installation, persistent quarantine, plugin removal, commits, and publication are never implicit actions.

Boundaries

• Doctor can report a new API owner and migration reason, but it cannot replace understanding the plugin's business logic;
• named imports and named re-exports from retained packages are recognized, while property access through namespace imports still needs manual investigation;
• runtime-verified proves packaging, installation, and basic activation, not UI, Service lifecycle, or business-flow correctness;
• DSH patches or prereleases outside the catalog require investigation of the additional source interval;
• static diagnosis cannot establish dynamic Service dependencies or whether plugin-owned external data is safe to delete.

CLI quick reference

Requires Node.js ^22.19.0 or >=24.0.0.

# Global installation
npm install --global @bruc3van/dsh-doctor

# Or run one pinned version without changing the global installation
npm exec --yes --package=@bruc3van/dsh-doctor@<version> -- dsh-doctor --help

Use dsh-doctor --help for full options and confirmation requirements. Migration orchestration and semantic-investigation rules live in dsh-plugin-upgrade and its references.

Output and exit codes

Text output supports Chinese and English. --json uses stable English codes and preserves redacted structured evidence.

Development

npm install
npm run check
npm pack --dry-run

Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery. CI runs on macOS, Ubuntu, and Windows with Node.js 22.19 and 24.

Local development, the skill, and the CLI never commit, tag, or publish automatically.