Main entry point for DSH plugin upgrade adaptation. Each of the three lanes handles one thing; determine intent first, then act:
| Lane | When to take this lane | Which document to read |
|---|---|---|
| Adaptation upgrade | Host released a new version, plugin errors, need to verify whether a package or API still exists, need to run a performance health check on a plugin | sub-skills/adapt/SKILL.md |
| Create plugin | No plugin yet and need to write one from scratch, or need a just-written plugin to pass the health-check gate | sub-skills/build/SKILL.md |
| Environment and startup failures | Plugin installed but not taking effect, client stuck on loading, host won't start | sub-skills/diagnose/SKILL.md |
Do not read all three at once. Use the table above to decide which lane to take and read only that document; when crossing lanes (e.g., after upgrading, also add a birth certificate), then add the second document. All commands below are executed in the skill root directory; scripts locate themselves by the absolute path of their own file, so you can also run them directly from any directory with node <技能根>/scripts/<脚本>.mjs , no need to cd first.
There are only two authoritative sources: the version information in the npm registry, and the deepseek-harness repository's docs/upgrade-guide/. Do not rely on manually maintained upgrade cards, and do not mirror the full official documentation. The guide takes the managed snapshot of the repository's default branch (after release, the official side will still complete same-version entries), and the release tag is only a frozen slice, used only as a fallback when the branch snapshot is unavailable and marked frozen. That kind of knowledge snapshot inevitably lags (upstream pre-release cadence is one every 1.7 to 2.8 days), whereas "whether a package still exists" is more reliably tested against the host's node_modules.
One-command orchestration (recommended entry)
node scripts/run.mjs <插件目录> [--target <版本>] [--from <版本>] [--no-clone] [--no-smoke] [--no-typecheck] [--no-log] [--real-smoke] [--strict]
Runs environment→version pinning→guide→scan→health check→smoke test→typecheck in one command, produces a unified JSON report and writes a local run log. Exit codes: 0 clean, 2 for critical/high hits, red typecheck, or a genuine cold-start failure; with --strict , "scan didn't run" and "guide didn't cover the target version" also exit with 2. The report's scan.coverage states which version this round's guide covers: when not scanned or coverage is incomplete, the screen will explicitly say "cannot be treated as checked clean", no longer passing off "0 hits" as clean. Scan window,--real-smoke, and run log (run-log.mjs list/show/sanitize/doctor) details are in sub-skills/adapt/SKILL.md. The first stop for "plugin errors / installed but not taking effect" is node scripts/run-log.mjs doctor, which cross-checks the run log and the host startup log side by side.
Skill surface sync (optional)
This repository by default watches no downstream. To mirror the skill surface to another skill directory, give it explicitly:
node scripts/sync-skill.mjs --dest <下游技能目录> --check # 只查漂移(退出码 1 = 有漂移)
node scripts/sync-skill.mjs --dest <下游技能目录> # 同步
The sync surface is fixed to the files that skill readers will actually use:SKILL.md、README.md、README.en.md、references/**、scripts/**、sub-skills/**,package.json is not included in the skill surface.--dry-run only prints without writing to disk; after sync completes, it prints the suggested downstream commit command (only add the sync path to prevent accidental inclusion), and does not commit automatically.
Cross-lane discipline
- Zero hits does not mean no problems, it only means "didn't hit anything within the range covered by the official guide". The guide only records breaking changes the official side deems necessary to notify, and does not cover all possibilities. First check
scan.coverage.complete: when not scanned or the target version is not covered, zero hits is unknown, not clean. - For hits, first check whether they are false positives. Anchor matching has several layers of noise reduction (rules and empirical basis in
references/heuristics.md), but symbols with the same name can still collide, e.g.path.resolve()in the plugin andruntime.resolve()in the guide. How to judge: look at the code context at the hit location and confirm whether the symbol really comes from the host API. memberhits, if the symbol is the guide's "migration target" it will not appear. The plugin has already been adapted using the new API notes, and the report was noise.- Investigate one plugin deeply at a time. When the host has just been upgraded and the whole batch of plugins needs to be gone through, first use the upstream plugin-fleet-sweep for a broad screening, then take the problematic ones back to the adaptation lane one by one for deep investigation. Batch handles breadth; this skill handles depth.
- The tool does not ship with a timer. The upstream watcher
guide-sync --check's exit codes are semantic (1 = new version available, 0 = no action needed, 2 = determination failed); whether to hook it up to cron, launchd, or agent polling is up to the user.
Security boundaries
- Read-only by default:
env-doctor、code-scan、plugin-audit、seams、log-doctor、run-logwrites no files at all. quick-smokeandwrite-gateexecute plugin code(dynamically importing the entry module). Only run it against your own or reviewed code; do not run it against directories of unknown origin. The execution surface is limited to within the Node process, but plugin code can in theory do anything Node can do.- Self-heal defaults to dry-run:
env-healwithout--applyonly reports; even with it, it moves rather than deletes (into~/.dsh/.trash/<日期>/)。 - Does not modify DSH itself, and does not touch the configuration and profile declarations under
~/.dsh. - Does not automatically modify plugin code: it only reports hits and the official fix;
plugin-audit --peer-patchalso only prints suggestions and does not writepackage.json。 - Network is used only for the "fetch official source" step: determining versions reads npm's dist-tags, and fetching the guide clones the official repository. Both have timeouts and report errors explicitly rather than silently skipping; dist-tags has a 1-hour cache, and on network failure it degrades to the old cache and marks it stale; clone failures caused by the upstream tag not being pushed are recorded in a 1-hour negative cache (invalidated as soon as dist-tags changes), and no repeated fetching occurs during that period; the guide preferentially reuses an existing local clone, and
--no-clonecan skip it. - Logs stay on the local machine only, containing local paths and usernames; before sending externally you must
sanitize。
Read on demand (outside the lane)
| Scenario | What to read |
|---|---|
| Old plugins not covered by the official guide | references/legacy-migration-sop.md |
| Scan noise-reduction rules and empirical basis | references/heuristics.md |
| Add a commit-time gate to the plugin's own repository | references/ci-snippet.md |
Self-check
npm test
178 assertions, covering the scanner not producing false positives (same-named words in comments and strings do not count as hits), not missing hits, version windows and real semver determination, target-shape determination, guide source anchors, guide branch snapshots and the coverage-unknown state, seam query dual-source conclusions, cross-checking of run logs and host logs, each tier of one-click orchestration (including --strict), smoke verification (including interception of undeclared inject contracts and exports-only entry points), four-dimensional audit (including peer patching), enablement diagnostics (host half and client half), the four states of ghost hosts and the source of disk times, tsconfig paths false greens (including extends and JSONC), the three blind spots of the environment layer, the authoring scaffold and health gate, log diagnostics, downstream sync, release preflight rules (version consistency/tag/package contents/npm status), cross-platform simulation, diagnostic output slimming, CLI help and unknown arguments, the doc assertion count and skill-surface description length gate, and scanning performance regression. Self-check has zero network and zero external dependencies, and can run on any machine.
Pre-commit gate:git config core.hooksPath .githooks(one-time) Enable the pre-commit hook; the self-check runs automatically on commit, so forgetting to sync after changing the source of truth gets caught at that moment.
Script list
The scripts are a toolbox shared by all three lanes, all under the skill root's scripts/ , not split by lane.
| Script | Responsibility |
|---|---|
run.mjs |
One-click orchestration of the full flow + write local run logs |
run-log.mjs |
Run log viewing (list/show) and sanitized export (sanitize), log cross-check (doctor) |
env-doctor.mjs |
Probe the local DSH environment: version, overlay, shared-farm dangling symlinks, two-layer patch, plugins, processes, ghost hosts (process generations), tsconfig paths false greens, host-half and client-half enablement readiness;--brief omits patch line originals (about 94% size reduction) |
env-heal.mjs |
Overlay old-package self-healing (dry-run by default) |
guide-sync.mjs |
Determine the target version + fetch the official upgrade guide: the default branch managed snapshot refreshes on a 1-hour TTL; tag snapshots only serve as an offline fallback and are marked frozen |
code-scan.mjs |
Scan plugin code and match official change anchors (with guide file and line number sources) |
seams.mjs |
Seam query: dual-source conclusions for a package name or API symbol in the guide anchor table and the local host |
quick-smoke.mjs |
In-memory Cordis smoke test, including Mock fallback disclosure |
plugin-audit.mjs |
Four-dimensional performance architecture health check, optionally combined with official guide cross-referencing |
log-doctor.mjs |
Parse ~/.dsh/logs/ host failures |
scaffold.mjs |
Five-form plugin scaffold |
write-gate.mjs |
Authoring health gate: hard gates are judged automatically; soft metrics are passed through for discretionary review |
sync-skill.mjs |
Skill-surface sync and drift check |
release-check.mjs |
Pre-release preflight: version consistency,v<版本> tag, whether npm has already published,npm pack required files and bundled extras, self-check, workspace; read-only, does not auto-tag or publish |
cli.mjs |
npm bin entry (npx plugin-fast-adapt), forwards to run.mjs |
self-test.mjs |
Self-check |
lib/ |
Scanner, guide parsing, run logs, client-half determination, host module probing, release rules |