Plugin authoring: surface DSH peer compatibility checks in the author guide｜插件开发：补充 DSH peer 兼容性说明

[Bruce-Yii]

I followed the current official plugin-author docs from Your first Harness plugin and tested the version-range decision against DSH 0.2.0-rc.2 and 0.2.1-alpha.1.

【中文摘要】我们从官方 Your first Harness plugin 入口按正常作者路径走了一遍。现在 DSH 已经会在安装和启动时强制检查 peerDependencies 中 @deepseek-ai/dsh* 的版本范围，但作者教程只告诉你依赖写在哪里，没有在这里解释版本范围会被宿主实际拦截、预发布版本怎么匹配，以及怎样做正反验证。兼容性规则本身并不缺失，问题是它没有出现在插件作者做这个决定的位置。

Context: what changed since #6683

#6683 (Sep 15, 2026) captured the earlier state accurately: peerDependencies was the only machine-readable compatibility signal, and dsh plugin add did not validate it — compatibility had to be checked offline. That was correct then; it is now outdated by product evolution, not refuted.

Current DSH enforces the contract:

• Install-time: dsh plugin add checks the package's @deepseek-ai/dsh / @deepseek-ai/dsh-* peers against the runtime version before pnpm runs — an incompatible peer refuses the operation with nothing was installed, and the refusal carries the plugin name, version, runtime version, unsatisfied peers, and the exact dsh plugin allow-version … --accept-risk remedy.
• Startup: every plugin row and bundle is checked at the composition boundaries DSH owns; a denied row is never imported (it stays disabled), a denied bundle is skipped and listed in skippedBundles.
• Exemptions: exact package@version → exact runtime grants in the profile's compatibility.json.
• Source of truth: evaluatePluginCompatibility() in packages/boot/app-boot/src/plugin-compatibility.ts matches every declared dsh peer with semver.satisfies(runtimeVersion, range, { includePrerelease: true }); documented in the App-boot README § Profiles and Plugin Manager README § Version compatibility and exemptions.

So the enforcement itself is no longer the gap. The gap is where a human author meets this contract.

Blind author-journey finding

Starting only from Your first Harness plugin and following only links a normal author naturally reaches (Basics → Framework → Reference; no repo-wide search, no community answers):

• Authors do learn the declaration shape: shared DSH packages belong in both peerDependencies and devDependencies, "as the harness packages do" — docs/user/develop/basic/publish.md.
• The first decision the path cannot support is choosing the host version range and proving it: nowhere on the author path does the text state that this range is an enforced admission contract at install/startup, nor how prerelease versions are interpreted in ranges.
• The same page says the resolution rules "do not … validate peer version ranges". That sentence is about Node module resolution, but without a nearby link to the compatibility gate, the author path does not make the launcher-side enforcement obvious. The launcher-side gate is only reachable by leaving the authoring flow's own Next steps (via Reference → Architecture → Plugin Manager README → App-boot README, or a diagnostics aside-link in the CLI reference); publish.md's Next steps never reach it.
• Consequence: the intuitive ^0.2.0 does not include 0.2.0-rc.2 under the current prerelease-aware gate — and the author journey never warns about this ordering trap.

Reproduced evidence

Minimal out-of-tree bundle (package.json with dsh.bundle, cordis.patch.yml, index.js importing defineTool from @deepseek-ai/dsh-tools), tested on isolated installs of 0.2.0-rc.2 and 0.2.1-alpha.1:

Check	Result on both hosts
dsh plugin --profile demo add ./my-plugin, peer "@deepseek-ai/dsh-tools": "^0.2.0-rc.2"	✅ accepted (exit 0); --dump-config shows the bundle layer; bounded boot prints the plugin's load marker
same manifest, deliberately incompatible peer "0.1.5-rc.3"	❌ refused: installation rejected: Plugin … is incompatible with dsh …: peerDependencies {…} + nothing was installed + exact allow-version remedy (exit 1)
trap range "^0.2.0" on the 0.2.0-rc.2 host	❌ refused — a prerelease lower bound is required for rc hosts

Range behavior under the current gate (includePrerelease: true): ^0.2.0-rc.2 matches both 0.2.0-rc.2 and 0.2.1-alpha.1. A stable lower bound such as ^0.2.0 excludes the earlier 0.2.0-rc.2 host, while DSH's explicit includePrerelease: true behavior can still admit later prereleases such as 0.2.1-alpha.1. (Under default node-semver prerelease filtering, without includePrerelease: true, ^0.2.0-rc.2 would not match the different tuple 0.2.1-alpha.1 either — exactly the confusion an author hits with no guidance.)

Independent community evidence

Beyond the blind author-journey test, independent community reports show why DSH peer-range selection and prerelease handling matter in practice. Some document authoring mistakes; others show expected rejections of incompatible declarations after upgrades. These reports do not establish that the author guide caused any particular mistake.

Discussion	Independent evidence	Why it matters to this docs gap
#6095	A plugin review found both declared peerDependencies ranges admit only the earliest prerelease line, excluding newer prerelease lines; the author replied in thread after the feedback.	A real plugin review surfaced a prerelease range decision that author-facing guidance could help make clearer.
#7006	A maintainer computed the actually-admitted set of every declared range across 22 published plugins instead of reading the string: five refused the newest DSH prerelease line outright — users on that line got ERESOLVE while each plugin's own tests passed — and fixed versions were published.	Shows string-level range reading is the trap, with the comparator/tuple rule behind it.
#5969	dsh-better-sidebar@0.16.1 failed install resolution: stable-bound DSH ranges such as >=0.1.2 <0.2.0-0 cannot select published prerelease siblings (ERR_PNPM_NO_MATCHING_VERSION).	Stable bounds silently exclude prerelease lines — the same trap as ^0.2.0 above.
#6134	Upgrading core 0.1.2-rc.1 -> 0.1.5-rc.1 makes plugins pinned to the older prerelease line fail to load, taking the whole profile down.	The user-visible consequence of stale/narrow declarations after a core upgrade.
#8199	On the desktop profile with 22 third-party bundles, upgrading to 0.2.0-rc.1 flagged 11 as abnormal — their peerDependencies only declared 0.1.x.	A concrete 22-bundle upgrade configuration, not an ecosystem-wide prevalence estimate or proof that every rejected range was declared incorrectly.
#8268	@nanmicoder/dsh-agent-teams@0.1.21 declares peers only up to dsh 0.1.7-rc.2, so on 0.2.0-rc.2 install prints the long incompatibility warning and startup refuses the plugin unless dsh plugin allow-version is granted.	A real third-party instance of this issue's gate behavior and its exemption remedy.

These reports do not share one root cause: some are authoring mistakes where a declared range was too narrow or silently expired against a newer published line, and some are legitimate incompatibility that the gate correctly exposes to users — not every flagged plugin has a wrong range. Across these cases, selecting and validating compatibility ranges is consequential; whether missing author-guide guidance caused any individual report is unproven.

Taken together, these reports corroborate that peer-range and prerelease compatibility affect real plugin authoring and upgrades; they do not establish a causal link to the documentation gap. The runtime gate now enforces the contract, so surfacing its rules and validation steps where authors declare and test supported host ranges remains a targeted documentation improvement.

Smallest actionable docs delta

Near the existing peerDependencies guidance in docs/user/develop/basic/publish.md:

1. One sentence: DSH peer ranges on @deepseek-ai/dsh / @deepseek-ai/dsh-* are enforced at install time and at startup; incompatible plugins are refused or not loaded.
2. One prerelease-aware example: "@deepseek-ai/dsh-tools": "^0.2.0-rc.2" — prereleases participate in range matching; ^0.2.0 excludes 0.2.0-rc.2.
3. One positive + one negative check: supported host → dsh plugin --profile demo add ./my-plugin succeeds and dsh --profile demo --dump-config shows the layer; unsupported host → the same command refuses with nothing was installed and prints the exact allow-version remedy.
4. One link to the authoritative reference: Plugin Manager README § Version compatibility and exemptions (plus App-boot README § Profiles for range semantics).

One observation (discoverability signal, not a separate complaint)

The current Agent-assisted plugin-development path was able to derive and validate the correct declaration on its own (bundled skill + host source), while the human author path did not surface the same contract — one gap, two audiences.

References

• Historical context: 插件 × harness 兼容性:声明规则、每周生态快照与两个实现的对齐(从 #4792 拆出) #6683
• Author-path packaging page: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md (rendered: https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish)
• Range semantics / startup admission: https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/app-boot/README.md#profiles
• Install-time gate / exemptions: https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-manager/README.md#version-compatibility-and-exemptions
• Implementation: https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/app-boot/src/plugin-compatibility.ts

[argszero]

This is a good catch and the enforcement facts check out against master. I measured the range semantics before answering, and one result moves the recommendation: DSH's gate and pnpm read a prerelease range the same way, and npm is the one that disagrees.

Which predicate the gate uses

packages/boot/app-boot/src/plugin-compatibility.ts:77:

semver.satisfies(runtimeVersion, requirement, { includePrerelease: true })

includePrerelease only ever adds matches, so the gate is the permissive reading. Measured here (Node 26.5.0, semver@7.8.5; host already carrying @deepseek-ai/dsh-tools@0.2.0-rc.2, plugin declaring "@deepseek-ai/dsh-tools": ">=0.1.7-alpha.1 <0.2.0", tarball spec):

consumer	verdict on that range/host
DSH gate	admits
pnpm 11.13.1, profile-shaped project (auto-install-peers=false)	admits — no warning at all; pnpm peers check → No peer dependency issues found
npm, into a project that already has the runtime	refuses — ERESOLVE … peer @deepseek-ai/dsh-tools@">=0.1.7-alpha.1 <0.2.0" from …

Control on the same setup with an exactly-wrong peer (0.1.2-rc.1): pnpm prints [WARN] Issues with peer dependencies found, npm prints ERESOLVE. So pnpm's check did run, and its silence above is agreement with the gate, not a missing check.

One further npm behaviour, same range, project with no runtime present: the install reports success and auto-installs @deepseek-ai/dsh-tools@0.1.7-rc.2 — a different line from the one the author supports. The same misreading, without the error.

Admitted sets over all 31 published @deepseek-ai/dsh-tools versions

range	gate admits	plain semver admits
^0.2.0	1 (0.2.1-alpha.1)	0
^0.2.0-rc.2	2 (0.2.0-rc.2, 0.2.1-alpha.1)	1 (0.2.0-rc.2)
>=0.1.7-alpha.1 <0.2.0	6 (…0.2.0-rc.1, 0.2.0-rc.2)	4 (…0.1.7-rc.2)
>=0.1.7-alpha.1 <0.2.0 || >=0.2.0-rc.1 <0.2.0	6	6 — identical
>=0.1.2 <0.2.0-0	12	0

Over a 17-version × 10-range matrix, no case where plain admits and the gate refuses; 56 cases the other way, every one a prerelease version. The two readings can therefore only disagree in one direction, and ^0.2.0 is stronger than "excludes the rc host": its admitted set is empty for anyone resolving with plain semver, while the gate would still admit it on the alpha host.

Two sentences I would add to your delta

Your four items are the right ones. Both additions are about which reader:

1. The prerelease rule is a property of the checking implementation, not of the range: the gate and pnpm admit >=0.1.7-alpha.1 <0.2.0 on a 0.2.0-rc.2 host, while npm refuses the same pair.
2. Give the rule, not only an example: declare a range whose admitted set is the same under both readings, which in practice means one explicit union segment per line — >=0.1.7-alpha.1 <0.2.0 || >=0.2.0-rc.1 <0.2.0. That is the form I use for our own plugins, for exactly this reason.

Also worth one line on the page: this is checkable without re-deriving the semantics — getDshRuntimeVersion() and evaluatePluginCompatibility() are exported from @deepseek-ai/dsh-app-boot (packages/boot/app-boot/src/index.ts:22), so an authoring check can call the gate's own function.

Tooling

Your item 3 is the part a documentation page can only describe. I am packaging the author-side version — given a plugin directory and a host version, it reports each declared dsh peer range's admitted set under the gate predicate and under plain semver, flags the ones where the two disagree, and names the range form that makes them agree — and will report back in this thread.

Scope of the measurements

Plain projects with tarball specs, pnpm 11.13.1 and npm on Node 26.5.0 — not a real profile. dsh plugin add hands its install to pnpm, so the npm column is what an author's own dev checkout hits (the peerDependencies + devDependencies pair publish.md prescribes) and what a user hits installing outside a profile; it is not what a profile does.

[argszero]

The compatibility gap now has an installable form: @argszero/dsh-peer-range-audit@0.1.0

Follow-up to the reply above. What that reply measured by hand is now a package anyone can call, so an author writing or reviewing a @deepseek-ai/dsh-* peer range can get the two admitted sets without reproducing the probe.

• npm: https://www.npmjs.com/package/@argszero/dsh-peer-range-audit
• source: https://github.com/argszero/dsh-peer-range-audit

One line of usage — mount it (it ships a bundle patch, dsh.bundle.patch: ./cordis.patch.yml), then call the tool:

peer_range_audit {}

With no arguments inside a profile it audits the dsh peer ranges of the plugins that profile mounts; pass manifests (parsed package.json objects) or requirements (bare ranges) for anything else, and versions (e.g. from npm view @deepseek-ai/dsh-agent versions --json) to test a ladder instead of the running version alone. For each declared range it prints the set the gate admits, the set plain semver admits, the divergence, and whether admission of the running version rests on the gate's prerelease reading alone.

It is deliberately read-only, and it deliberately does not propose a replacement range: a synthesized range can be wider than the one it replaces and still look like a fix, so the honest output of a set comparison is the two sets plus the rule that produces them.

Three measured facts it encodes, from the same probe behind the reply above:

• Direction. Over the 31 published versions, nothing is admitted by plain semver and refused by the gate; the gate is a strict superset, and every divergence observed was a prerelease.
• The gate's reader is the profile's reader. pnpm is the profile's installer and agrees with the gate — a clean install on the same range — while npm's resolver raises ERESOLVE. So the plain column describes a dev checkout or an out-of-profile install, not what a profile does.
• A union of one segment per line is what dissolves the divergence. >=0.1.7-rc.2 <0.2.0 || >=0.2.0-rc.2 <0.2.1 names each line's own prerelease floor, so plain semver admits both; the single-segment >=0.1.7-alpha.1 <0.2.0 admits both lines under the gate only. The package holds itself to that shape: test/packaging.spec.mjs asserts that no line it claims needs includePrerelease.

Verification behind the release: 51 unit and integration assertions (npm test), 15 defect-injection arms, all caught (npm run test:inject), and the suite run against both claimed lines by pinning each line's whole peer closure — 23 harness packages per line, with every pin read back after install (npm run test:probe-lines).

If the author guide wants a concrete, checkable recommendation to point at rather than the two-set explanation, the union-of-segments shape and the rule "plain semver must admit every line you claim" are the two that can be checked from the outside — and this tool prints both.

[Bruce-Yii]

Thanks for taking the time to measure this and turn the findings into a tool. My original repro focused on the DSH gate; the difference between profile installs and an author's own npm checkout is an important part of the author experience that I hadn't covered. I especially like that the audit shows both admitted sets without silently proposing a wider compatibility range. The per-line examples and the exported gate check make the documentation suggestion much more concrete. Really appreciate the careful follow-up and the published package.

…

On Thu, 08 Oct 2026 17:42:41 -0700, argszero ***@***.***> wrote: The compatibility gap now has an installable form: @***@***.*** Follow-up to the reply above. What that reply measured by hand is now a package anyone can call, so an author writing or reviewing a @deepseek-ai/dsh-* peer range can get the two admitted sets without reproducing the probe. - npm: ***@***.***/dsh-peer-range-audit - source: https://github.com/argszero/dsh-peer-range-audit One line of usage — mount it (it ships a bundle patch, dsh.bundle.patch: ./cordis.patch.yml), then call the tool: peer_range_audit {} With no arguments inside a profile it audits the dsh peer ranges of the plugins that profile mounts; pass manifests (parsed package.json objects) or requirements (bare ranges) for anything else, and versions (e.g. from npm view @deepseek-ai/dsh-agent versions --json) to test a ladder instead of the running version alone. For each declared range it prints the set the gate admits, the set plain semver admits, the divergence, and whether admission of the running version rests on the gate's prerelease reading alone. It is deliberately read-only, and it deliberately does not propose a replacement range: a synthesized range can be wider than the one it replaces and still look like a fix, so the honest output of a set comparison is the two sets plus the rule that produces them. Three measured facts it encodes, from the same probe behind the reply above: - Direction. Over the 31 published versions, nothing is admitted by plain semver and refused by the gate; the gate is a strict superset, and every divergence observed was a prerelease. - The gate's reader is the profile's reader. pnpm is the profile's installer and agrees with the gate — a clean install on the same range — while npm's resolver raises ERESOLVE. So the plain column describes a dev checkout or an out-of-profile install, not what a profile does. - A union of one segment per line is what dissolves the divergence. >=0.1.7-rc.2 <0.2.0 || >=0.2.0-rc.2 <0.2.1 names each line's own prerelease floor, so plain semver admits both; the single-segment >=0.1.7-alpha.1 <0.2.0 admits both lines under the gate only. The package holds itself to that shape: test/packaging.spec.mjs asserts that no line it claims needs includePrerelease. Verification behind the release: 51 unit and integration assertions (npm test), 15 defect-injection arms, all caught (npm run test:inject), and the suite run against both claimed lines by pinning each line's whole peer closure — 23 harness packages per line, with every pin read back after install (npm run test:probe-lines). If the author guide wants a concrete, checkable recommendation to point at rather than the two-set explanation, the union-of-segments shape and the rule "plain semver must admit every line you claim" are the two that can be checked from the outside — and this tool prints both. — Reply to this email directly, [view it on GitHub](#9194?email_source=notifications&email_token=CHDJZC6CL74ZPOHQRWXJIN35TAYADA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYGI2TSNRWUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-18825966), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/CHDJZC2OROFZEERUFGEDVND5TAYADAVCNFSNUABJKJSXA33TNF2G64TZHMYTGMZTGA3DKMBZGE5UI2LTMN2XG43JN5XDWMJQHE3TSMBRHCQXMAQ). You are receiving this because you authored the thread.