插件 × harness 兼容性:声明规则、每周生态快照与两个实现的对齐(从 #4792 拆出)

[ciceroyang]

从 #4792 拆出来的独立话题。那边原本是「官方要不要做插件市场」,兼容性调查越长越偏,axetroy 提醒得对,所以把这条线移到这里。

问题

插件在 package.json 的 peerDependencies 里声明它依赖哪些 @deepseek-ai/* host 包与范围——这是目前唯一机器可读的兼容性信号。但:

• dsh plugin add 不校验它(profile 的 pnpm 配置 autoInstallPeers: false,host 包来自 CLI 共享根层、不在 profile 依赖图中,pnpm 没有可解析的 peer 目标),装进去也没有任何警告 → Bug: dsh plugin add 会静默安装 host peer 范围无法满足的插件(dsh-win32 实测,零 warning) #6680;
• 于是声明与实际是否一致,只能靠离线比对。

规则(已写成文档,欢迎第二实现对齐)

https://github.com/ciceroyang/dsh-doctor/blob/main/docs/host-peer-declarations.md

要点:解析顺序(profile node_modules → 共享根层、跟随软链接、作用域名两段、排除内置/相对路径);三态「兼容 / 不兼容 / 未知」,未知不得当作兼容;以及最容易做错的预发布合并规则:strict 满足 → 兼容;numeric 满足而 strict 不满足 → 未知;numeric 不满足 → 不兼容(部分版本 <1/>=4 必须可解析)。

生态快照(每周自动刷新,可直接引用)

• 摘要:https://github.com/ciceroyang/dsh-doctor/releases/download/ecosystem-compat/compat-summary.md
• 原始 JSON:https://github.com/ciceroyang/dsh-doctor/releases/download/ecosystem-compat/compat.json

最近一版(503 个仓库):305 个插件声明了 host peer,201 全兼容、61 含未解析/无法判定、43 至少有一条区间不包含当前 host;另有 162 个插件有 bundle 却完全没写 host 范围。

作者自查(一行)

node doctor.mjs --lint-peers .

退出码 0 全部覆盖 / 1 至少一条不覆盖 / 2 没装 DSH(绝不静默通过)。快照里那些不覆盖的声明,大多是 ^0.0.1 这类版本线过时或精确锁死旧版本,改一行即可。

两个实现正在对齐

现在生态里有两份独立实现(@moonquake2004/dsh-doctor 的 peerRangeState 与本仓库的 satisfiesRange)。我用 scripts/range-difftest.mjs 在 1639 条真实声明上比对,发现 58 条判定不同,已把机制与合并规则发在 #6678;对齐后我会用同一份语料复跑并把结果贴在这里(目标 0 分歧)。

candidate(变更前判定)那一类的契约草案在 #1719。

—— 这条线之后就在本贴更新。

[moonquake2004]

对齐已完成，两条语料都是 0 分歧 —— 从 #6678 那条线移到这里收口。

$ node scripts/range-difftest.mjs --other <our impl>.mjs --corpus compat.json
cases: 1639 | divergences: 0        # 13 条边界语料同样 0（修复前 58）

我们这边改动落在 dsh-doctor@0.4.25（判定对齐）+ 0.4.26（未声明计数），并把它做成了随包发布的回归测试：plugin/test/peer-range-conformance.test.mjs 直接从已发布源码里抽取 peerRangeState 来跑你那 13 条边界语料（而不是重新实现一份，否则测的是测试自己），外加四个角落逐条钉住。任何重构破坏一致性都会在 CI 红。

但请先修一处表述——它就在本贴的规则摘要里，也与文档表格一致、与你的实现相反：

"strict 满足 → 兼容；numeric 满足而 strict 不满足 → 未知；numeric 不满足 → 不兼容"

按这行，旗舰用例 >=0.1.0-rc.5 <0.2.0 配 0.1.5-rc.2 应判 未知；而你的实现（satisfiesGroup）判 兼容（该组是预发布感知的），你的后果清单也写"accepts 0.1.5-rc.2"。差分测试比对的是实现，所以我们按实现对上了——但照本贴摘要或文档表格字面实现的第三方，会恰好在这两行产生分歧（我们首轮 2 处分歧就是这两条）。建议把摘要与表格改成实现的口径：数值判定决定 true/false；唯一的 unknown 是「被判版本是预发布、且该组不含任何预发布比较器」。

另外两点小补充（都来自落地）：

1. 我们采纳了快照里的"有 bundle 却完全没写 host 范围"（你那 162 个）——按规则 1 那是"无信息"，不能读成兼容。P19 现在会如实计数（本机：78 条声明已核对 / 26 条未知 / 5 个 bundle 未声明），但不生成发现：声明与否是作者的选择，消费者该做的只是别把它读成"已核对"。
2. 关于 --lint-peers 的退出码设计（0/1/2，没装 DSH 时绝不静默通过）——这个我完全赞同，也是我们这边对 --boot-check 的同一要求：宿主起不来时才是它最该工作的时刻。

之后你每周刷新快照时，如果愿意把新语料跑一遍我们的实现，结果直接贴这里即可；有分歧我按条修。也欢迎把 @moonquake2004/dsh-doctor 列为 conforming implementation——现在两边应该都是 0，从 0 再往外找才是真正的发现。