SuperAPI AI Directory

plugin-fast-adapt

Coding & development

View repository

Updated 10-29 10:01

About this skill

plugin-fast-adapt

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 and runtime.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.
  • member hits, 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-log writes no files at all.
  • quick-smoke and write-gate execute 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-heal without --apply only 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-patch also only prints suggestions and does not write package.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-clone can 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