生态实测:9,873 个插件里 553 起工具名冲突会导致启动失败,以及三个可以消除它们的小改动

[anweat]

背景

我扫描了 GitHub 上 12,630 个 dsh 相关仓库,其中 9,873 个是真实插件(带 package.json#dsh 声明、cordis.patch.yml,或含实际注册调用)。分析是静态的:用与 dsh 相同的 applyEntryPatches 算法重放各插件的补丁,再从源码/构建产物提取注册调用点。

完整数据、方法与可复现脚本:https://github.com/anweat/dsh-ecosystem-conflicts

结果里有一个结构性问题,我想先确认理解是否正确,再提三个具体的小改动。

一、生态整体站在了 host 平面

插入到根的 entry 行:9,216    插入到分组下:0

没有任何一个第三方插件挂在分组下。

而出厂架构把模型可见的行放在 agent 平面。定量佐证:web-app 在根上禁用的 24 行,22 行在 standard 预设里重新挂上(例外只有 hmr 和 tool-str-replace-editor)。dsh-agent-presets 也会对未加入预设的 agent 告警,说它"解析自空的全局层"。

也就是说全局层设计上应该是空的,而整个生态都挤在里面。我理解这不是生态不守规矩,而是两个平面的存在没有被插件作者感知到。

二、由此产生的冲突

类型	组数	牵涉包	运行时后果
工具名撞车	553	855	tools.register 抛错 → 启动失败
entry id 撞车	452	1042	上层补丁只能定位到其中一个
孤儿补丁	89	87	一行 stderr 后跳过 → 静默失效
配置行争用	77	381	补丁整体替换 config → 静默丢字段
keyed 槽争用	62	226	UI 条目被遮蔽
撞官方工具名	28	77	同样 启动失败
single 槽争用	24	303	只有一个能渲染

最挤的工具名:country_info 84 个包、element_info 55、bash 44、memory_search 37。

最挤的 entry id 全是基础设施:storage 29、storage-json 29、storage-domain 29、agent-presets 26、code-runtime 25 —— 插件在各自重新插入宿主本该提供的东西。

另外:2,622 个包同时注册一个 UI 槽位和一个 HTTP 路由,即所有人都在手搓"一个面板 + 喂它数据的端点"。这是最高频的组合,断层第一。

三、大部分可以在插件侧解决

我在一个独立克隆里做了机制验证(33 项断言全部通过,脚本在上面仓库的 experiments/):

• isolate 是 loader 的一等 entry 选项,cordis:group + isolate 能让 shim 拦在消费者和真服务之间,纯配置声明,零上游改动
• 工具名冲突可以靠 scope 分层解决,view() 已有"近的遮蔽远的"语义,不需要改名,链序即优先级
• tools.guard() 免疫 waterfall 短路,所以自定策略是顺序无关的

所以我不打算请求大的架构改动。但有三处配置层确实够不到,想提出来讨论。

四、三个具体的小改动

1. 事件监听的数值优先级

EventOptions 目前只有 prepend?: boolean(二元),而 1,951 个插件在干预回合或工具管线(agent/pre-step 513、tools/pre-execute 349、llm/stream 256)。顺序 = 注册顺序 = 激活顺序,配置层不可声明。

更麻烦的是 waterfall 的短路语义:任何监听器不调 next() 就静默截断整条链,349 个包共用 tools/pre-execute,其中任一个早注册并短路,下游全废。

建议:EventOptions 增加 priority?: number,派发前稳定排序。register() 现在已经在 unshift/push 二选一,改成有序插入即可。

2. 短路可观测(改动最小)

不改变任何语义,只在监听器短路时发一个诊断信号(或 dev 模式记录)。现在这类失效没有任何痕迹,插件作者无从排查。

3. BootPluginRow 携带 priority

客户端槽位本身有完整的 priority 遮蔽语义,但 BootPluginRow 只有 { id, inject, immediately },客户端 loader.create({ name }) 没有配置缝。结果是前端冲突只能"二选一禁掉一个",而不是分层让位。

建议:BootPluginRow 扩展 priority?: number,主机侧清单生成时写入,客户端透传。改动集中在 packages/client/modules。

五、说明与征求意见

数据的局限我在仓库 README 里列明了:路由部分是 503 个仓库的抽样且 37% 静态不可判定;路由争用以分叉为主而非独立撞车。被列入 data/conflicts.json 不代表对该插件的评判——主因是结构性的,大多数插件单独使用都正常。

主要想先确认:上面对两个平面的理解是否正确?如果我理解错了,后面的结论都要重来。

第 3 项如果有兴趣,我可以先做一个本地原型验证可行性。

---

English summary

I analyzed 12,630 dsh-related repositories, of which 9,873 are real plugins. Method, data, and reproducible scripts: https://github.com/anweat/dsh-ecosystem-conflicts

Structural finding: 9,216 entry rows insert at the root, zero insert under a group. The shipped design puts model-facing rows on the agent plane — 22 of the 24 rows web-app disables at the root are re-mounted in the standard preset — so the global layer is meant to be empty, yet the whole ecosystem registers there.

Consequences: 553 tool-name collisions + 28 against shipped tools (both throw at registration → boot failure), 452 entry-id collisions, 89 orphan patches that fail silently, 77 contended config rows. The most contended entry ids are all infrastructure (storage, agent-presets, code-runtime) — plugins each re-inserting what the host is supposed to provide.

Most of this is fixable plugin-side: isolate as a loader entry option lets a shim sit between consumer and service with no upstream change, and scope layering resolves tool names without renaming anything the model sees. 33 assertions verifying this are in experiments/.

Three things the config layer cannot reach:

1. EventOptions numeric priority (currently binary prepend; 1,951 plugins intervene in the turn/tool pipeline, and any waterfall listener can silently cut the chain)
2. Observability when a waterfall listener short-circuits (no semantic change, diagnostics only)
3. BootPluginRow carrying priority, so client-side slot conflicts can shadow instead of forcing an all-or-nothing disable

Mainly want to confirm the two-plane reading is correct before building on it.

[anweat]

补一组量化结果,把上面第 4 节的三个请求从"提议"变成有具体收益的提案。

我写了一层纯裁决函数(零 harness 依赖,可离线回放),对全部扫描语料重放了一遍。代码和数据都在 https://github.com/anweat/dsh-ecosystem-conflicts/tree/master/arbitration

语料

9,617 条记录 / 8,540 个去重包名 / 52,301 个贡献 / 1,201 个争用格。

现状(全部同装)

581 个格会让注册表抛错,牵涉 896 个包(10.5%)。 任一个就足以让整个组合启动失败。

裁决后

结局	包数	占比	含义
intact	6,614	77.4%	全部贡献保持原目标
adapted	1,123	13.1%	有分层/改名/隔离,功能完整
degraded	803	9.4%	前端半被丢弃
共存	7,737	90.6%

裁决动作:layer 581、rename 453、drop-client 90、report-only 77。

成对共存更贴近实际——没人会装 9,617 个插件,但装两个撞车的插件天天发生。取样 4,000 对今天会互相炸的组合,3,941 对(98.5%)裁决后可共存,59 对(1.5%)仍有前端功能损失。

两个我觉得值得单独指出的结论

1. 581 起工具名冲突全部解为 layer,没有一个需要改动模型可见的名字。 scope 分层 + 链序裁决就够了,view() 现有的"近的遮蔽远的"语义直接可用。这也意味着工具名命名空间这类改动是不必要的——我不打算提。

2. 剩余的功能损失 100% 集中在前端。 drop-client 90 个动作、9.4% 的包降级,全部来自客户端平面没有配置缝:BootPluginRow 只有 { id, inject, immediately },而槽位本身有完整的 priority 遮蔽语义。

也就是说上面第 4 节第 3 项(BootPluginRow 携带 priority)能消掉的就是这 9.4%——从"二选一禁掉一个插件"变成"只有那个槽位让位"。这是三个请求里唯一有明确量化收益的,如果只能选一个改动,我会选它。

---

English

Follow-up with numbers. I wrote a pure arbitration function (no harness dependency, replayable offline) and ran it over the whole corpus — code and data at https://github.com/anweat/dsh-ecosystem-conflicts/tree/master/arbitration

Corpus: 9,617 records / 8,540 distinct package names / 52,301 contributions / 1,201 contended cells.

Today, everything installed: 581 cells would make a registry throw, involving 896 packages (10.5%). One is enough to fail the boot.

After arbitration: 77.4% intact, 13.1% adapted (layered/renamed/isolated, function complete), 9.4% degraded (browser half withheld) — 90.6% coexisting.

Pairwise: of 4,000 sampled pairs that are mutually fatal today, 98.5% coexist after arbitration.

Two conclusions worth separating out:

1. All 581 tool-name conflicts resolve to layer — not one needs a name the model sees to change. Scope layering plus declared chain order suffices; view()'s existing nearer-shadows-farther semantics do the work. So a tool-name namespace change is not needed, and I am not proposing one.

2. Every remaining functional loss is on the client plane — 9.4% of packages degrade purely because BootPluginRow carries { id, inject, immediately } and nothing else, while the slot registry itself already has full priority-shadowing semantics. Request 3 above is exactly what closes that 9.4%: an all-or-nothing plugin disable becomes one seat yielding. Of the three, it is the only one with a measured payoff — if only one change were possible, that is the one I would pick.

[anweat]

再补一次结果:把裁决真正跑起来了,而且规模测试发现了一个我读源码时没看出来的冲突类别。

代码与数据仍在 https://github.com/anweat/dsh-ecosystem-conflicts

全语料对真注册表的实测

不是离线重放,是把整个语料灌进真的 ToolRuntime:用真 dsh-scope 铸 896 个 scope 排成一条链,执行 7,164 次工具注册。

裁决 71ms | 排链 48ms | 铸 896 scope 114ms | 7,164 次注册 1,188ms
注册抛错 0        agent 可见工具 5,589        工具名重复 0
争用工具 553 | 解析到非赢家 0 | 缺失 0

553 个争用工具全部解析到裁决赢家,全部保持原名,全局层保持为空。 这些组合今天任意两个装在一起就会让启动失败。

规模测试发现的:保留名是一个独立的冲突类别

有一个包注册了名为 run_code 的工具,注册表无条件拒绝——原话是 "reserved for the Code Mode presentation transport and cannot be registered or shadowed"。

scope 分层对它无效。 它不是"这一层被占了",而是任何层都拒绝。这和其余 553 起工具名冲突是不同性质的东西,而我此前把它们归成了一类。裁决现在单独建模为 drop(赢家 <reserved>),因为诚实的答案是谁都拿不到这个名字。

这个类别只有把全语料灌进真注册表才会暴露;读源码时我见过那段代码,但没意识到它是独立类别,合成的两插件用例也永远碰不到。

两个纠正了我们自己假设的发现

这两条会约束这个方向上的任何设计,所以单独列出:

1. 挂 agent/created 做否决太晚了。 会让启动失败的注册发生在 loader 应用 entry 时,那时还没有任何 agent。实测时间线:

["gatekeeper:apply","registry:provide","apply:pkg-a","register:bash","apply:pkg-b"]
                                                                          ↑ 这里抛错

整个组合根本没启动到有 agent 的阶段。守门员必须读 entry list——它在那些 fiber 应用之前就已完整,而且冲突从中即可预测。

2. 一个预设就是一个 scope。 mount() 把 agent 绑到单一常驻 key,所以两个争同一名字的插件不能共处一个预设——它们会像在根上一样撞。要分层就得每个插件一个 scope,建在常驻挂载之上;standingKeyFor(id) 恰好提供了这个可能(它"组合插件但不启动 agent、session 或 turn")。

与三个改动请求的关系

上面第 4 节的三项,现在都有了对应的实测数字:

• 第 1、2 项(事件优先级与短路可观测):补充一条,我原先判断"事件顺序基本不可治"是错的。实测 prepend: true 稳拿头位(且全生态无人使用),前哨兵/尾哨兵可以检测短路,tools.guard() 免疫短路。真正需要上游的只剩"编排第三方之间的顺序",其余可在插件侧做到。
• 第 3 项(BootPluginRow 携带 priority):仍是三项中唯一有明确量化收益的。全量裁决后 90.6% 的包可共存,剩余 9.4% 的功能损失 100% 来自客户端平面——因为 BootPluginRow 只有 { id, inject, immediately },前端冲突只能整包禁用而不能让位。

---

English

Follow-up with the arbitration actually running, and one conflict class that only a full-scale run revealed.

Full corpus against the real registry — not an offline replay: 896 real scopes on one chain via real dsh-scope, 7,164 tool registrations into the real ToolRuntime.

arbitration 71ms | chain planning 48ms | 896 scopes 114ms | 7,164 registrations 1,188ms
registration throws 0     agent-visible tools 5,589     duplicate names 0
contended tools 553 | resolved to a non-winner 0 | missing 0

All 553 contended tools resolve to the arbitrated winner, under their original names, with the global layer left empty.

Scale found a class reading the source did not. One package registers run_code, which the registry refuses unconditionally — "reserved … and cannot be registered or shadowed". Scope layering does not apply: reserved is not "taken in this layer", it is refused everywhere. Arbitration now models it separately (drop, winner <reserved>), because the honest answer is that nobody gets the name.

Two findings that corrected our own assumptions, since they constrain any design here:

1. An agent/created veto is too late. The failing registrations happen at loader apply, before any agent exists — the composition never reaches the agent stage at all. A gatekeeper must read the entry list, which is complete before those fibers run and from which the conflict is predictable.
2. A preset is one scope. mount() binds an agent to a single standing key, so two plugins contending for a name cannot share a preset. Layering needs a scope per plugin above the standing mount, which standingKeyFor(id) makes possible.

On the three requests: I should correct myself on ordering — I had said event order was largely untreatable, and that was wrong. prepend: true reliably takes the front seat (and nothing in the ecosystem uses it), a front/rear sentinel pair detects a short-circuit, and tools.guard() survives one. What genuinely needs upstream is only ordering among third parties. Request 3 remains the one with a measured payoff: after arbitration 90.6% of packages coexist, and 100% of the remaining functional loss is on the client plane, purely because BootPluginRow carries no priority.

[anweat]

第 3 项(BootPluginRow 携带 priority)我做了一个能跑的原型,并把它值多少量化了出来。

补丁与实验:https://github.com/anweat/dsh-ecosystem-conflicts/blob/master/experiments/bootpluginrow-priority.patch

原型:两个文件,37 行

packages/client/modules/src/client/manifest.ts   BootPluginRow.priority(可选 + 校验)
packages/client/runtime/src/client/slots.ts      seedPriorities + 注册时的默认值

第二处接在 _register 里 registrant 已有的盖章旁边——那里本来就在从调用方 fiber 推导身份,再推导一个默认 rank 是同一件事:

const seeded = registrant === undefined ? undefined : this._defaultPriority.get(registrant)
const erased = {
  ...options,
  ...(registrant !== undefined ? { registrant } : {}),
  ...(options.priority === undefined && seeded !== undefined ? { priority: seeded } : {}),
}

纯增量:插件自己声明的 priority 永远压过清单默认;没有 seed 的组合行为与改动前逐字节一致(这两条都有断言)。

它买到了什么

同一份语料、同一套裁决,只把"客户端争用座位"的补救从"撤下整个插件的前端半"换成"普通遮蔽":

                              intact   adapted   degraded
  现状(清单无 rank)             6,618     1,122        804
  有 BootPluginRow.priority     6,618     1,925          1

  降级包数   804 → 1   (803 个包,占语料 9.4%)
  共存率     90.6% → 100.0%

剩下的那 1 例是保留名(run_code),任何 rank 都救不了。客户端平面今天造成的全部功能损失,就是这一个缺失字段。

行为验证

原型在真 SlotRegistry 上跑的断言(12/12):

• 今天:两个插件抢同一个 single 座位 → 第二个被拒,只能整包取舍
• 有 rank 后:第二个不再被拒,两个条目都在册,渲染的只有 rank 最低的那个
• 让位不等于失能:输掉那个座位的插件,它在别处的条目照常渲染
• 显式 priority 压过清单默认
• 未 seed 时按原样抛错

第三条是这个改动的实质:今天的取舍粒度是"整个插件",有 rank 之后是"那一个座位"。

---

English

I built a working prototype of request 3 and measured what it buys. Patch: https://github.com/anweat/dsh-ecosystem-conflicts/blob/master/experiments/bootpluginrow-priority.patch

Two files, 37 lines. BootPluginRow.priority (optional, validated) plus a per-registrant default the slot service applies when a registration sets none — seated next to the registrant stamp _register already derives from the calling fiber. Strictly additive: an explicit priority still wins, and an un-seeded composition behaves exactly as before. Both asserted.

Same corpus, same arbitration, only the client-seat remedy changed from withholding a plugin to an ordinary shadow:

                              intact   adapted   degraded
  today (no manifest rank)      6,618     1,122        804
  with BootPluginRow.priority   6,618     1,925          1

  degraded    804 → 1   (803 packages, 9.4% of the corpus)
  coexisting  90.6% → 100.0%

The one remaining degraded package is the reserved-name case, which no ranking fixes. Everything else the client plane costs today is this single missing field.

Behaviour verified against the real SlotRegistry (12/12): a second plugin claiming a single seat is no longer refused; both entries are on the ledger and only the lowest rank renders; the plugin that loses that seat keeps its entries elsewhere; an explicit priority overrides the manifest default; and without seeding it throws exactly as it does today.

That third point is the substance of the change: today the unit of resolution is a whole plugin, and with a rank it is one seat.