DSH | dsh-doctor + dsh-security | 诊断与安全检查工具：40+31 项检查，含 dsh 起不来时的自救与升级前后复检

[moonquake2004]

Two open-source tools for the DSH ecosystem — a diagnostics CLI and a security-check framework. Both are ordinary npm packages; nothing here needs a patched host.

@moonquake2004/dsh-doctor — 40 checks in three groups

• env: node / pnpm / zstd presence, .env shape, node-pty native binding, storages JSON, contract anchors, .npmrc workaround, dsh in PATH, settings writability, runtime zstd stability
• profile: bundle resolvability, entry-id collisions, patch syntax, dangling file: deps, named-import/export mismatch, manifest version, client bundles, dist-tag health, provenance verifiability
• session: orphan tool calls, unclosed turns, seq continuity, unknown event types, container frame structure, header / first-frame integrity, whole-store scan, migration-refusal pre-flight

It emits the dsh-doctor/v1 envelope (name + status + exit code) so CI and support scripts consume it uniformly, and it can pull new checks from a remote catalog without a release.

@moonquake2004/dsh-security — 31 checks in four layers

• static: dependency audit, secret scan, sandbox/approval/permission resolution, entry poison, capability surface, poison patterns, patch-layer security-row overrides, !!js config-as-code, Code-Mode × sandbox mismatch, prompt-injection surface in plugin content, provenance
• runtime (from session logs): sandbox-violation primitives, privilege-escalation primitives, data exfiltration, plugin isolation, credential-store access
• lifecycle: supply-chain integrity, update integrity, reputation, release compatibility
• secrets: credential leak, PII exposure, sensitive output, session integrity

Plus optional integrations with four community tools (poison-guard, plugin-reducer, ecosystem; sandbox-audit retired after we found it was never published).

The part most people actually need: when dsh will not start

Installing an incompatible plugin, or upgrading dsh against older plugins, is the most common way to end up with a host that refuses to boot — and at that point you cannot use dsh to diagnose it. These are plain Node CLI (npx) and do not need dsh to boot:

npx @moonquake2004/dsh-doctor --boot-check --profile web        # offline load simulation: which entry fails, and how
npx @moonquake2004/dsh-doctor --quarantine <pkg> --profile web  # move it out of the boot list → dsh starts again
npx @moonquake2004/dsh-doctor --unquarantine <pkg> --profile web
npx @moonquake2004/dsh-doctor --safe-add <pkg> --profile web    # install + verify + auto-quarantine / full rollback
npx @moonquake2004/dsh-doctor --pre-upgrade --profile web       # run before upgrading dsh
npx @moonquake2004/dsh-doctor --post-upgrade --profile web      # after: diff + load simulation + fix commands

--boot-check imports each enabled entry in a subprocess and classifies the failure (missing export / not installed / native ABI / module format / hang) — that is exactly what a boot does, so it is an explicit opt-in flag rather than default behaviour. --quarantine edits only the profile's boot list (it never deletes packages) and always writes a timestamped backup first.

What this work surfaced

Everything below has a reproduction in the linked thread, not just a claim:

• A session log's first frame must be exactly one header line, and violating it blocks dsh web startup — one report had it happen three times in five days (Corrupt session log (first frame is not the header) blocks `dsh web` startup and session listing #6651). Our own whole-store scan used to call such a log "healthy"; we treated that as a bug in our tool and fixed it.
• Session-format drift silently disabled several runtime checks — they matched fields that had moved, so the report read "clean" while the layer was blind. We now drive the installed migration chain itself instead of pattern-matching it.
• !!js is evaluated in the host process at load via new Function("ctx","expr"," with (ctx) { return eval(expr) }"), outside the agent sandbox. Two plugins on our machine use it; we published a dossier and opened an issue upstream.
• A profile manifest with a name but no version throws in the package inventory as soon as a loose local module is resolved (Bug: versionless profile manifests break DeepSeek requests for local modules #6667) — and the manifest the harness itself generates has exactly that shape.

Interop and posture

• We implement and consume the dsh-doctor/v1 envelope, and follow the v1 vocabulary alignment for check names and severities (💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719). What we could not verify is published as unverified.
• Both repos have a SECURITY.md and GitHub private vulnerability reporting enabled. We treat false negatives (a check that silently stops matching after a field moves) and high-noise false positives as vulnerabilities of the tool — both end with the operator ignoring it.

Honest limits: most checks are static/offline; we cannot verify Windows-specific behaviour from macOS (CI now runs Ubuntu + Windows × Node 22/24, which immediately found a real Windows-only bug in one check); the runtime checks read the latest settled session, so they deliberately do not judge the session you are in right now.

Counterexamples, wrong-verdict reports and corrections are the most useful thing you can send. Check lists and sources: dsh-doctor · dsh-security

---

中文版 / ZH

这是给 DSH 生态做的两个开源工具：一个诊断 CLI、一个安全检查框架。都是普通的 npm 包，不需要改动宿主。

@moonquake2004/dsh-doctor —— 40 项检查，三组

• env（环境）：node/pnpm/zstd 是否就位、.env 形态、node-pty 原生模块、storages JSON、契约锚点、.npmrc workaround、dsh 是否在 PATH、settings 可写性、运行时 zstd 稳定性
• profile（配置）：bundle 可解析性、entry id 冲突、patch 语法、file: 依赖悬空、命名导入/导出缺失、manifest 版本、client 产物、dist-tag 健康度、来源可验证性
• session（会话）：孤儿工具调用、未闭合回合、seq 连续性、未知事件类型、容器帧结构、会话头/首帧完整性、全库扫描、迁移拒载预检

输出统一采用 dsh-doctor/v1 信封（检查名 + 状态 + 退出码），便于 CI 与支持脚本消费；新检查可从远程目录拉取，无需发版。

@moonquake2004/dsh-security —— 31 项检查，四层

• 静态：依赖审计、密钥扫描、沙箱/审批/权限解析、entry 投毒、能力面、投毒模式、patch 层覆盖安全行、!!js 配置即代码、Code Mode × 沙箱错配、插件内容里的提示注入面、来源可验证性
• 运行时（读会话日志）：沙箱逃逸原语、提权原语、数据外泄、插件隔离、宿主凭据库访问
• 生命周期：供应链完整性、更新完整性、信誉、发布兼容性
• 机密：凭据泄露、PII 暴露、敏感输出、会话完整性

另含对四个社区工具的可选集成（poison-guard、plugin-reducer、ecosystem；sandbox-audit 因"从未发布到 npm"被我们退役）。

大多数人真正需要的那部分：dsh 起不来时怎么办

装了个不兼容的插件，或升级 dsh 后与旧插件不兼容，是最常见的"宿主拒绝启动"来源——而那时你已经没法用 dsh 自己来诊断。下面这些是普通 Node CLI（npx 直跑），不需要 dsh 能启动：

npx @moonquake2004/dsh-doctor --boot-check --profile web        # 离线模拟装载：哪条 entry 炸、炸在哪类
npx @moonquake2004/dsh-doctor --quarantine <包名> --profile web  # 摘出启动列表（先备份）→ dsh 可以起来了
npx @moonquake2004/dsh-doctor --unquarantine <包名> --profile web
npx @moonquake2004/dsh-doctor --safe-add <包名> --profile web    # 装完即验；坏了自动隔离 / 必要时整体回滚
npx @moonquake2004/dsh-doctor --pre-upgrade --profile web       # 升级 dsh 前记基线
npx @moonquake2004/dsh-doctor --post-upgrade --profile web      # 升级后：对比 + 装载模拟 + 修复命令

--boot-check 会在子进程里真的去 import 每条启用的 entry，并归类失败原因（缺导出 / 没装全 / 原生 ABI 不匹配 / 模块格式 / 顶层卡死）——这正是"启动"本身的语义，所以它是显式开关而非默认行为。--quarantine 只改 profile 的启动列表（从不删除任何包），且必定先写带时间戳的备份。

这轮工作暴露出的东西

下面每一条都在对应帖子里有复现，不只是结论：

• 会话日志的第一个 zstd 帧必须恰好只有一行（头行），违反它会直接阻断 dsh web 启动——有报告 5 天内遇到 3 次（Corrupt session log (first frame is not the header) blocks `dsh web` startup and session listing #6651）。我们自己的全库扫描此前会把这种日志报成"健康"，我们把那当作我们工具自己的 bug 修掉了。
• 会话格式漂移曾让多项运行时检查静默失效：它们匹配的字段已经搬走，于是报告显示"干净"，而那一层其实是瞎的。现在我们改为驱动已装的迁移链本身，而不是模式匹配它。
• !!js 是在宿主进程内、沙箱之外于加载期求值的（new Function("ctx","expr"," with (ctx) { return eval(expr) }")）。本机有两个插件在用它；我们发布了分析档并向上游提了 issue。
• profile manifest 有 name 但没有 version，会在解析到"游离本地模块"时让 package inventory 抛错（Bug: versionless profile manifests break DeepSeek requests for local modules #6667）——而 harness 自己生成的 manifest 恰恰是这个形状。

互通与安全姿态

• 我们实现并消费 dsh-doctor/v1 信封，检查名与严重度遵循 v1 词汇表对齐（💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719）。我们没能验证的内容，一律标注为未验证。
• 两个仓库都有 SECURITY.md，并已开启 GitHub 私有漏洞报告。我们把假阴性（检查因字段搬走而静默失配）与高噪声假阳性都当作工具的漏洞——两者的终点都是"用户开始忽略它"。

如实说明边界：多数检查是静态/离线的；我们在 macOS 上无法验证 Windows 特有行为（CI 现已覆盖 Ubuntu + Windows × Node 22/24，加上的第一次就抓出一个真实的"仅 Windows"缺陷）；运行时检查读的是最近一个已停止写入的会话，因此有意不去评判你正在进行的这一场。

最有用的反馈是反例、误判报告与纠正。 检查清单与源码：dsh-doctor · dsh-security

Live demo（输出原文照抄，未编辑）

在 macOS / Node 24 的一个一次性临时 profile 上跑出，复现的正是社区真实遇到的那一类失败：插件导入了一个已被移除的导出。

$ npx @moonquake2004/dsh-doctor --boot-check --profile web
装载模拟（…/profiles/web）：检查 1 条 entry，失败 1 条
  ✗ [at-file-broken] at-file → at-file-broken
      missing-export: SyntaxError: The requested module '@deepseek-ai/dsh-settings' does not provide an export named 'settingsNamespace'
      修复方向：插件比所装的 @deepseek-ai/* 旧/新：把该插件升级到匹配版本（或降级核心）
      先起来：npx @moonquake2004/dsh-doctor --quarantine at-file-broken

$ npx @moonquake2004/dsh-doctor --quarantine at-file-broken --profile web
✓ 已隔离 at-file-broken（启动列表现为 0 项；原始 package.json 已备份）
  重启 dsh，然后用 --boot-check 复查；要放回：--unquarantine at-file-broken

$ npx @moonquake2004/dsh-doctor --boot-check --profile web
装载模拟（…/profiles/web）：检查 0 条 entry，失败 0 条
  ✓ 所有可探测 entry 均可导入——启动失败若仍发生，问题多在配置合并或原生环境，请贴 --json 输出

三条命令，dsh 又能起来了——原始 package.json 已备份、一行命令可撤销。然后你可以从容地升级那个插件。

同一流程的英文版（English version of the same flow）

$ npx @moonquake2004/dsh-doctor --boot-check --profile web
Load simulation (…/profiles/web): 1 entry checked, 1 failed
  ✗ [at-file-broken] at-file → at-file-broken
      missing-export: SyntaxError: The requested module '@deepseek-ai/dsh-settings' does not provide an export named 'settingsNamespace'
      Fix: the plugin is older/newer than the installed @deepseek-ai/* — upgrade it (or downgrade the core)
      Get running first: npx @moonquake2004/dsh-doctor --quarantine at-file-broken

$ npx @moonquake2004/dsh-doctor --quarantine at-file-broken --profile web
✓ quarantined at-file-broken (boot list now 0 entries; original package.json backed up)
  Restart dsh, then re-check with --boot-check; to restore: --unquarantine at-file-broken

如实说明：诊断消息目前是中文（英文输出模式在待办上）；上面第二段是把同一份输出译出来方便阅读，命令行实际打印的是中文。若你要英文输出，欢迎在 issue 里说一声——这也是判断优先级最直接的方式。

升级前记一次基线（真实 profile，未编辑）

$ npx @moonquake2004/dsh-doctor --pre-upgrade --profile web
✓ 已记录升级前基线（/Users/…/.dsh/profiles/web）
  核心版本: 0.1.5-rc.1 | bundle 16 个 | entry 15 条
  下一步：升级 dsh，然后运行
    npx @moonquake2004/dsh-doctor --post-upgrade --profile web

---

一个具体例子：一条社区评论怎样删掉了我们的一个误报

介绍帖里说"我们把误报当漏洞"是个主张；这里给一个有编号、有日期的实例，因为它就发生在本贴的评论区。

1. 提案与提醒。 @ciceroyang 在本贴提议增加一个检查（已装插件声明的 host peer 范围 vs 实际提供的核心版本），并附了一条提醒：DSH 生态几乎全在预发布上，而 strict semver 的预发布规则要求"比较器与被判版本处于同一 [major,minor,patch] 元组"才允许匹配，于是在全员 rc 的生态里会产生误报 —— >=0.1.0-rc.5 <0.2.0 应当接受 0.1.5-rc.2，字面规则却会拒绝。

2. 我们用真 node-semver 复核，他说得对：

satisfies('0.1.5-rc.2', '>=0.1.0-rc.5 <0.2.0')      → false   ← 应接受（字面规则误报）
satisfies('0.1.5-rc.2', '>=0.1.0-rc.5 <0.1.0-rc.7') → false   ← 一致（确实越界）
satisfies('0.1.5-rc.2', '>=4.0.0')                   → false   ← 应记"未知"

3. 而我们的代码正是这样写的。 dsh-security 的 SP5 判定"插件声明的核心范围是否接受实际安装的核心"时，直接调 satisfies(..., { includePrerelease: false }) —— 因此它会把一个健康的插件报成"不支持当前核心"。这不是别人的坑，是我们自己的：SECURITY.md 里我们把"误报健康环境（用户因此开始忽略工具）"明确列为工具的漏洞，而它正发生在同一时刻我们发出去的版本里。

4. 改法（两条一起，避免两个组件用不同语义）：

• checkRange 改为三态 + rc 规则：区间含任何预发布比较器 → 按数值判定（接受 0.1.5-rc.2，拒绝越界者）；纯 release 区间面对预发布安装版本 → unknown；SP5 只对 unsatisfied 生成发现，unknown 既不算兼容也不报。
• 他提议的检查落成 P19（dsh-doctor profile 组，默认运行即覆盖，不必带 --security），并逐条照做他列的坑：只取 @deepseek-ai/*、host 版本跟随软链接（file:/dev 安装与共享镜像根都是软链接，用 lstat 风格会误报）、作用域名按第一段斜杠切、三态。他自己的真实案例现在可复现：dsh-win32 声明 >=0.1.0-rc.5 <0.1.0-rc.7 而实际提供 0.1.5-rc.2 → 报出。

5. 回归测试里有两条是"不得误报"（正是上面第 2 步的第一、三行），另有一条确认真实越界仍要报。dsh-security@0.4.5、dsh-doctor@0.4.23 已发布。

我们为什么把这个写进介绍帖：一个工具的检查质量取决于它愿不愿意承认自己报错过。这条规则不是我们想出来的，是我们写错、被社区纠正、然后改对的；把它记在公开处，比任何"高准确率"的说法都更能说明你拿到的东西是怎么维护的。规则与用例的原始实现见 @ciceroyang 的仓库（本贴评论区有链接），P19 的代码注释里也标注了出处。

---

如果只带走两条命令

前面讲了能力，这里只留"明天就能用上"的部分。

① 装插件时直接用它来装 —— 不要让"装完才发现起不来"发生：

npx @moonquake2004/dsh-doctor --safe-add <包名> --profile <profile名>

装完立刻验证；坏了自动隔离它、dsh 照样能起来；隔离也救不回则整体回滚——最坏情况只是一次无害的失败尝试。

② 升级 dsh 前记一次基线 —— 升级是最容易"升完就起不来"的时刻：

# 升级前（此时 dsh 还跑得好好的）
npx @moonquake2004/dsh-doctor --pre-upgrade --profile <profile名>

# …在这里升级 dsh…

# 升级后：自动对比核心版本与插件变化，并跑装载模拟
npx @moonquake2004/dsh-doctor --post-upgrade --profile <profile名>
#   想一步到位让 dsh 先起来：加 --auto-quarantine

已经起不来了？ 三条命令，同样不需要 dsh 能启动：

npx @moonquake2004/dsh-doctor --boot-check --profile <profile名>       # 点名哪条 entry 炸、炸在哪类
npx @moonquake2004/dsh-doctor --quarantine <包名> --profile <profile名>  # 先备份再摘出启动列表 → 重启即可
npx @moonquake2004/dsh-doctor --unquarantine <包名> --profile <profile名>

一条经验法则：在重启 dsh 之前跑一次 --boot-check。此时 dsh 还活着，你能顺手把问题处理掉；等它起不来再查，代价总是更高。

---

If you take away two commands

① Install through it, so "installed it, now nothing boots" stops happening:

npx @moonquake2004/dsh-doctor --safe-add <pkg> --profile <name>

It verifies immediately after installing; on failure it quarantines the offender (dsh still starts); if even that cannot save it, it rolls back to the pre-install manifest. Worst case becomes a harmless failed attempt.

② Record a baseline before upgrading dsh — the moment breakage is most likely:

# before (while dsh still runs)
npx @moonquake2004/dsh-doctor --pre-upgrade --profile <name>

# …upgrade dsh here…

# after: diffs the core version and plugin changes, then runs the load simulation
npx @moonquake2004/dsh-doctor --post-upgrade --profile <name>
#   add --auto-quarantine to get dsh running in the same command

Already broken? Three commands, and again none of them needs dsh to boot:

npx @moonquake2004/dsh-doctor --boot-check --profile <name>        # names the failing entry and its class
npx @moonquake2004/dsh-doctor --quarantine <pkg> --profile <name>  # backs up, then removes it from the boot list
npx @moonquake2004/dsh-doctor --unquarantine <pkg> --profile <name>

One rule of thumb: run --boot-check before restarting dsh. While it is still running you can fix things calmly; after it refuses to start, every step costs more.

[ciceroyang]

这套覆盖面很实用,尤其 --boot-check / --quarantine 这类「dsh 起不来时还得能诊断」的命令——那正是诊断工具最容易失效的时刻。

给 remote catalog 提一个候选检查(你们的 profile 组里似乎没有):已装插件声明的 host peer 范围 vs 磁盘上实际安装的 host 版本。这类不匹配是升级后无法启动的常见原因之一,而且可以完全离线判定。

规则要点(踩过的坑都在这):

1. 取每个已装插件的 peerDependencies,只保留 @deepseek-ai/*;
2. 依次解析 host 版本:<profile>/node_modules/<name>/package.json → <DSH_HOME>/profiles/node_modules/<name>/package.json,跟随软链接(dev/file: 安装的插件与 root 层复用都是软链接,用 lstat 风格会误报);
3. 作用域名按第一段斜杠切(@scope/name 是两段);
4. 三态:兼容 / 不兼容 / 未知(*、未声明、无法解析);未知不能当作兼容;
5. rc 语义(DSH 全在预发布上,这步最容易做错):如果比较器组里出现任何预发布比较器,就按数值判定——>=0.1.0-rc.5 <0.2.0 应当接受 0.1.5-rc.2,>=0.1.0-rc.5 <0.1.0-rc.7 应当拒绝它;只有纯 release 区间(如 >=4.0.0)面对预发布安装版本时才应记为未知。strict semver 的字面规则会把第一种也判成不满足,那是误报,而误报健康 profile 比不报更糟。

一个真实案例:dsh-win32@0.17.8 声明 @deepseek-ai/dsh-subprocess-local >=0.1.0-rc.5 <0.1.0-rc.7,当前 CLI 装的是 0.1.5-rc.2 → 明确不满足;而安装时没有任何警告(我已把它按 bug 报了 #6680,机制是 profile 的 pnpm 配置 autoInstallPeers: false 且 host 由 CLI 共享根层提供,pnpm 没有可解析的 peer 目标)。

我这边把同一套规则实现成了单个检查(ciceroyang/peer_range,约 80 行含 semver 子集,零依赖,MIT,https://github.com/ciceroyang/dsh-doctor ),如果你想收进 catalog 或直接移植,规则与回归用例都在里面;不想收也完全没问题,把规则写进你们的检查集就是它的价值所在。

[moonquake2004]

这条提醒正好命中我们自己的一个 bug —— 谢谢，这是本次讨论里最有价值的一条反馈。

你说的 strict semver 误报，我们确实踩了。 我们的安全层（dsh-security SP5）判定"插件声明的核心范围是否接受实际安装的核心"时，直接调的是
satisfies(version, range, { includePrerelease: false })。用装在本机的那份 node-semver 逐例复核你的三种情形：

satisfies('0.1.5-rc.2', '>=0.1.0-rc.5 <0.2.0')      → false   ← 按你的规则应当接受：我们把健康插件报成"不支持当前核心"
satisfies('0.1.5-rc.2', '>=0.1.0-rc.5 <0.1.0-rc.7') → false   ← 这条一致（确实越界）
satisfies('0.1.5-rc.2', '>=4.0.0')                   → false   ← 我们当时会当成"不兼容"，而按你的规则应记未知

第一行就是我们 SECURITY.md 里明确定义为漏洞的那一类：误报健康环境——它的终点是用户开始忽略这个工具。你把规则写出来的时候，我们正把这条错误实现发上 npm。

已经改成你描述的三态 + rc 规则（并逐例对齐）：

• checkRange 返回 satisfied / unsatisfied / unknown；只有 unsatisfied 才是发现，unknown 既不算兼容也不报；
• 区间里出现任何预发布比较器 → 按数值判定（includePrerelease: true）：接受 0.1.5-rc.2，拒绝 >=… <0.1.0-rc.7；
• 纯 release 区间面对预发布安装版本 → unknown；
• 加了 3 条回归：两条"不得误报"的（正是上面第一、三行），一条确认越界仍要报。

你的检查我们实现进了 profile 组（如你所说，它该在默认运行里，而不是只在 --security 下）——dsh-doctor 的 P19，逐条照做了你列的坑：只取 @deepseek-ai/*、host 版本按 profile node_modules → 共享镜像根解析且跟随软链接、作用域名两段、三态、rc 规则。用你的真实案例验过：

✗ P19（warn）插件声明的 host peer 范围不接受实际安装的核心版本（1 处，共核对 1 条 peer 声明）：
    win32-plugin 声明 @deepseek-ai/dsh-subprocess-local >=0.1.0-rc.5 <0.1.0-rc.7，但实际提供 0.1.5-rc.2

以及两条"不得误报"：>=0.1.0-rc.5 <0.2.0 配 0.1.5-rc.2 → 通过；>=4.0.0 / * → 记未知，并在 detail 里说明"有 N 条无法判定，按未知处理未计入"。

关于 ciceroyang/peer_range：我们移植了规则而没有把包 vendor 进来——dsh-doctor 的一个卖点是零依赖、且要在宿主安装树不完整时仍能跑（正是"dsh 起不来"的场景），所以带了一份自足的 semver 子集（^ ~ > >= < <= = 与 || 组）。这份实现的存在归功于你的规则与用例，代码注释里写明了出处，你仓库的链接也留在本贴里，谁想直接看原始实现都能找到。

顺带回答你关于 catalog 的一点：我们的远程 catalog 是数据驱动的（探针类型 + 正则/JSON/文件判定），像 peer 范围这种需要逻辑的检查进不了 catalog，只能落在内置检查集里——所以它现在是内置的 P19，随版本发布。

（两处修复均已发版：dsh-security@0.4.5（rc 语义）、dsh-doctor@0.4.23（P19）；测试 263 + 150 全绿。）

[ciceroyang]

既然现在生态里有两份独立实现(你们的 peerRangeState、我们的 satisfiesRange),我把之前只是提议的差异测试真的做了——规则里没钉死的地方会立刻显形。

方法:从我们的生态快照里取 1639 条「精确范围 × 已装版本」逐条比对。脚本可复用,任何导出 peerRangeState(或返回 {state})的模块都能跑:

node scripts/range-difftest.mjs --other <module.mjs> --corpus compat.json

https://github.com/ciceroyang/dsh-doctor/blob/main/scripts/range-difftest.mjs

结果:58/1639 判定不同,9 类形态,两个方向都有。机制很明确,两类:

A. 部分版本被当成不可解析(31 条:我们 satisfied / 你们 unsatisfied)

parseVer 只接受 X.Y.Z,于是 <1、<5、<4、<2 这类简写解析失败 → 整组失败:

• >=0.1.0-rc.5 <1 vs 0.1.5-rc.2 → 我们 satisfied,你们 unsatisfied;
• >=4.0.1 <5 vs 4.0.2 → 同上;
• >=4.0.0 <5 vs 4.0.2 → 同上。

这一类会让 P19 误报健康的声明(而它报 warn),和你们刚在 SP5 修掉的是同一类问题、不同来源。修法:partial 补 0(<1 → <1.0.0,>=4 → >=4.0.0)。

B. 预发布降级的位置(35 + 2 条,两个方向)

现在的规则是在失败之后判断 !hasPre && ver.pre.length → unknown,成功路径不看这个条件。于是:

• ^0.0.1 vs 0.1.5-rc.2:数值上就越界(>0.0.2),但你们记 unknown → 漏报真实的过时声明(35 条);
• >=4.0.0 / ^1.2.3 vs 4.1.0-rc.1 / 1.2.4-rc.1:数值上在区间内,但 strict semver 因缺同 tuple 预发布比较器而排除 → 你们 satisfied,我们 unknown(2 条)。

建议按两次判定合并,而不是在失败路径上打补丁:

strict  = 严格 semver(includePrerelease: false)
numeric = 数值判定(includePrerelease: true)

strict 满足                → satisfied
numeric 满足、strict 不满足 → unknown     // 唯一的预发布歧义来源
numeric 不满足             → unsatisfied // 与预发布无关,就是越界

这样 A 与 B 同时消失,也与 #1719 里「未知不得折叠成任一确定态」一致。

两句说明

1. 这不是挑错——我们自己的第一版(0.6.0)有同类问题:把「没有同 tuple 预发布比较器」一律记未知,于是 >=0.1.0-rc.5 <1 这种健康声明被记未知;0.6.1 改成「组里出现任何预发布比较器就数值判定」才修好。手写 semver 就是这样,所以差异测试值得常态化。
2. 脚本支持 --fail-on-divergence,可以在你们 CI 里当守卫——先对齐规则,再打开它。你们的 P19 与我们的 --lint-peers 用的是同一条规则,两边对齐之后,插件作者在哪一侧看到的结论都会一致。

快照每周更新,随时可复跑:https://github.com/ciceroyang/dsh-doctor/releases/tag/ecosystem-compat

[ciceroyang]

把上一条里的规则写成了文档,方便你们(或任何第二实现)直接对齐而不必从对话里拼:

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

含:解析顺序(跟随软链接 / 作用域名两段 / 内置与相对路径排除)、三态语义、以及那张 strict/numeric 两次判定 的合并表和你我踩过的四个角落(>=0.1.0-rc.5 <0.2.0 必须接受 0.1.5-rc.2;^0.0.1 不得因预发布降级为未知;>=4.0.0 对 4.1.0-rc.1 记未知;<1/>=4 这类部分版本必须可解析)。文末标了出处与促成它的那条误报报告。

等 P19/规则的修改落地后,我这边用 scripts/range-difftest.mjs 再跑一次同一份语料,把分歧数报给你们做验收——目标是把 58 降到 0。

[moonquake2004]

跑完你的 harness，两条语料都是 0 分歧：

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

（修复前是 58 处，全部落在你点名的四个角落。）

但过程中发现一处规范与实现不一致，建议先钉住再让别人对齐 —— 因为它正是产生分歧的地方：

文档表格写的是

strict satisfied              -> compatible
numeric satisfied, strict not -> unknown
numeric not satisfied         -> incompatible

而你的实现（satisfiesGroup）实际是：

数值判定决定 true/false；只有当被判版本是预发布、且该组不含任何预发布比较器时才是 null（unknown）。

两者对旗舰用例给出相反的结论：>=0.1.0-rc.5 <0.2.0 配 0.1.5-rc.2，按表格是 unknown，按实现是 compatible。你的后果清单（"accepts 0.1.5-rc.2"）与实现一致，与表格相反。差分测试比对的是实现，所以我们按实现对齐——但一个照着表格字面实现的第三方，恰好会在这两行上产生分歧（我们首轮 2 处分歧就是这两条）。建议把表格改成实现的口径，或明确标注哪一个是规范性的。

另外两个角落我们也补齐了：部分版本（<1 / >=4 缺失段补 0 后必须可解析——此前我们把它们解析失败当成不满足，会把健康声明报成 incompatible）、以及 ^0.0.1 不得因预发布降级为未知（那是真越界）。

我们把一致性做成了回归测试：plugin/test/peer-range-conformance.test.mjs 直接从已发布源码里抽取函数来跑你那 13 条语料（否则测的是测试自己），外加四个角落逐条钉住、以及"未知的三种来源不得折叠成确定态"。这样它随包发布，任何重构破坏一致性都会在 CI 红。

最后采纳了你的一条生态发现：503 仓库里 162 个声明了 bundle 却完全未声明 host 范围——按你的规则 1 那是"无信息"，不能读成兼容。P19 现在会在 detail 里如实计数（我们本机：78 条声明已核对 / 26 条未知 / 5 个 bundle 未声明），但不生成发现：声明与否是作者的选择，消费者该做的只是别把它读成"已核对"。

已发版 dsh-doctor@0.4.25（对齐你实现）、0.4.26（未声明计数）。你跑 range-difftest 若在我们这边还有任何分歧，直接把输出贴过来，我按条修——现在两边应该都是 0，从 0 再往外找才是真正的发现。