dsh-substrate (plugin)

dsh-substrate

2026-09-07：可安装插件的当前版本范围与验收见 pnpm compatibility。npm alpha.2～.5 使用内嵌 Include 的 app-boot 补丁；源码矩阵、独立 loader 实验与真正安装后的验证分别记录。

A conflict-resolution substrate for the DeepSeek Harness plugin ecosystem, and the measurements it is built on.

The ecosystem has a structural problem: 9,216 root inserts and 0 group inserts across 9,873 scanned plugins, while the shipped design keeps the global layer empty. Every plugin author sees only their own row, so every plugin inserts into the one layer it can see, and they land on top of each other. Installing all of them makes 581 registry cells throw, and any one of those is a boot failure.

The substrate adds the missing stage: a pass with a global view, between composition and boot.

  arbitrate ── decide who holds each contended seat
  adapt ───── emit the patch layer, plan the scope chain, rewrite routes
  contract ── publish what plugin authors cannot currently discover

Result

all plugins installed together   581 cells throw, 896 packages involved (10.5%)
after arbitration                90.6% coexist
+ one upstream field             100.0% coexist

booted for real, 2,768 packages · 11,911 tool registrations
  without the substrate          654 registration failures, boot fails
  with the substrate             boots · 0 duplicate names · 648 scopes

这个仓库的目标是变得不必要

DSH 还没有正式版本。它今天缺的东西——客户端槽位的 rank、令牌的导出面、名册变更的转发——都是官方迟早会自己补上的,每补上一样这里就该少一块。衡量标准不是功能多完整,而是还剩多少没被上游吸收。全部落地时,这里应该只剩测量管线。

运行时历史研究基线为 dsh-v0.1.1-rc.2-5-g50854a854f;安装修复按 loader 精确版本选择 1.0.6、1.0.7 或已审计的 app-boot 补丁。alpha.5 之后的发布适配见 后续版本验收，早期逐标签覆盖及完整启动限制见 alpha 适配记录。机制证据与安装兼容范围分别记录;重验和删除已被上游吸收的兜底代码的原则见 ADAPTATION.md。

Layout

substrate/	the substrate itself — arbitration, adapters, contracts (251 assertions)
pipeline/	the ecosystem scanner and the baseline catalog generator
experiments/	mechanism experiments against a real harness checkout (160 assertions)
e2e/	the whole thing booted: corpus packages on a real shipped profile
plugin/	the installable plugin — contract and what was actually tested
patches/	the one distributable fix — why pnpm patch and not a preload or a fork
docs/	design notes and Discussion drafts
ADAPTATION.md	跟哪个版本、每次更新怎么重验、什么时候该删代码而不是修测试

Product shape

The Web card is a read-only compatibility surface, not a patch toggle. It reports the exact installation, target version, and repair phase, then hands an explicit command to an external process. dsh-substrate repair --apply validates again, stages the version-locked patch, runs pnpm install in the real DSH installation workspace, and verifies the installed file; a restarted Host is the only thing allowed to call the repair verified. --revert follows the same transaction in reverse.

This split is intentional: a plugin already running inside DSH must not reinstall the process hosting it, and “declaration written”, “dependency relinked”, and “new process loaded” are different facts.

Install

Install the compatibility card into the DSH Web profile, then restart DSH:

dsh plugin --profile web add @anweat/dsh-substrate@^0.1.2

The card reports the exact installation and repair state. Run the write transaction outside DSH, then restart DSH again so a new Host can verify the loaded code:

npx --yes @anweat/dsh-substrate@0.1.2 repair --home "<DSH_HOME>"
npx --yes @anweat/dsh-substrate@0.1.2 repair --home "<DSH_HOME>" --apply --yes

To undo it, run npx --yes @anweat/dsh-substrate@0.1.2 repair --home "<DSH_HOME>" --revert --yes, then restart DSH. Version 0.1.0 requires --legacy-peer-deps immediately after --yes when invoked through npx; later releases remove that workaround.

The repair supports @deepseek-ai/cordis-plugin-include@1.0.6 and 1.0.7, plus exact @deepseek-ai/dsh-app-boot builds 0.1.2-alpha.2 through alpha.5, 0.1.2-rc.1, 0.1.3-alpha.2, and 0.1.5-alpha.1. It fixes duplicate loader entry IDs. Service-name and tool-name collisions occur later in boot and still require host composition with service realms and tool scopes. See the packaged installation guide, post-alpha.5 acceptance, and browser coexistence verification.

Develop

npm install
npm test                              # substrate suite, no checkout needed
npm run baseline -- <dsh-checkout>    # regenerate the known-component catalog

experiments/ and e2e/ need a harness checkout; see experiments/EXPERIMENTS.md.

The four layers

L1 — vocabulary. Ten contribution kinds split into exclusive and additive. A conflict is only counted where the runtime makes it one: a single/keyed seat, a registry that throws, a config row two layers both rewrite. list/chain seats are additive by construction and are counted, never flagged.

L2 — arbitration. A pure function from contributions to decisions, with five remedies. All 581 tool-name conflicts resolve to layer; not one requires renaming something a model can see.

L3 — adaptation. Patch emission, scope-chain planning, route realm proxying, preset emission, and the boot-time tools shim that puts a config-mounted plugin into a scope.

L4 — contracts. The design-token vocabulary and the panel scaffold: the two things plugin authors cannot discover today.

What is upstream's to fix

Four requests, two with working prototypes.

BootPluginRow.priority	37-line prototype. Degraded 804 → 1 (9.4% of the corpus); coexistence 90.6% → 100.0%
a token export surface	contract implemented. Its first run found 10 real defects in the shipped client
ui-theme as a platform seed word	argued, not built
forward roster changes to the dev channel	located to two lines; deliberately not prototyped, because acting on the frame needs browser-side reconciliation and half a fix is not one

Honesty about the evidence

• The e2e plugin bodies are synthetic; their registrations are not. A plugin's business logic cannot make a registry throw, its registration set can, and that is what the corpus records. A pass means the composition mounts, never these plugins work.
• 37% of route registrations pass a non-literal path and are statically undecidable. Route findings are a sample of 503 repositories, not the full corpus.
• The shipped-tool catalog over-derives on purpose. A tool registered behind config is not statically decidable, and the two errors are not symmetric: a name wrongly believed taken costs one plugin a scope, a name wrongly believed free costs the composition its boot.
• Being named in the data is not a judgement about a plugin. The dominant cause is structural, and most of these packages work fine alone.

Published measurements and the arbitration replay: https://github.com/anweat/dsh-ecosystem-conflicts