插件声明 DSH 版本兼容性范围，加载器自动校验并拒绝不兼容插件

[lbn2011]

[Feature Request] 插件声明 DSH 版本兼容性范围，加载器自动校验并拒绝不兼容插件

Category: Ideas 💡

---

现状

DSH 目前采用 everything-is-a-plugin 架构，插件通过 Cordis 加载。但插件和 DSH 核心之间没有显式的版本约束机制：

• 插件无法声明自己兼容哪些 DSH 版本
• 加载器不会在加载前检查版本兼容性
• 升级 DSH 后，不兼容的插件要么静默失败，要么导致 Cordis 进程崩溃
• 插件作者也无法通过 CI 自动检测版本兼容性

建议方案

允许插件在 cordis.yml（或 package.json）中显式声明兼容的 DSH 版本范围，加载器在进入 LOADING 阶段前用 semver.satisfies() 进行校验，不满足则拒绝加载并输出明确的错误日志。

配置方式

方案 A（推荐）：在 cordis.yml 中声明

# cordis.yml
name: my-awesome-plugin
version: 1.2.0

# 新增字段：声明兼容的 DSH 版本范围
dshCompatibility: "^0.1.0"
# 也可以写更严格的范围
# dshCompatibility: ">=0.1.2 <0.2.0"

方案 B（备选）：在 package.json 中声明

{
  "name": "my-awesome-plugin",
  "dsh": {
    "compatibleVersions": "^0.1.0"
  }
}

加载器行为

1. 读取当前运行环境的 DSH 版本（例如 0.1.3-alpha.1）
2. 读取插件声明的 dshCompatibility 范围
3. 调用 semver.satisfies(currentDSHVersion, declaredRange)
4. 若不满足：
   • 拒绝加载该插件
   • 明确告知原因

收益

1. 快速失败：将"运行时莫名其妙不工作"转化为"启动时明确的版本冲突错误"
2. 降低调试成本：不再需要二分法注释代码来定位版本问题
3. 生态健壮性：强制插件作者关注版本兼容性，减少 DSH 升级导致的生态大面积崩溃
4. 向后兼容：未声明 dshCompatibility 的旧插件默认视为兼容所有版本，零破坏性变更
5. CI 集成：插件作者可以在 CI 中自动检测 DSH 新版本是否兼容

开放问题

1. 配置位置：大家倾向放在 cordis.yml 还是 package.json？我个人倾向 cordis.yml，因为这是 Cordis 插件的元数据配置中心。
2. 未声明时的默认行为：默认 *（全兼容）还是默认 当前主版本？建议初期为 *，后续 DSH 1.0 后可收紧。
3. Alpha/Beta 版本处理：semver 默认对 pre-release 版本匹配较严格（^0.1.0 通常不匹配 0.1.3-alpha.1）。是否需要加载器在比较时自动剥离 pre-release 标签？
4. 严格模式 vs 警告模式：是否提供 --strict-compat 启动参数？默认 Warning 但允许加载，开启后直接拒绝？
5. 插件市场/目录集成：未来是否可以在插件目录中自动展示兼容性信息？

---

[argszero]

Strong proposal — and it's the exact gap behind a family of real crashes in this ecosystem. The current reality is: the loader has zero version-compat knowledge (I checked vendor/loader/src + app-boot — no semver.satisfies, no declared-range check anywhere on the load path). Plugins can and do break the whole tree on upgrade with nothing actionable in the message.

Three things I'd sharpen before locking the design, drawn from the failures your proposal would have caught:

1. Declaring a range is only useful if the loader checks the actual installed plugin, not just the bundle. The sharpest crash we've seen is #5450: a plugin's peer range >=0.1.0-rc.5 <0.2.0 silently resolved to an old line, so the plugin tree froze an old-shaped service and a newer consumer called a method that no longer existed (cache.hydratePrepared is not a function). The pre-release tuple rule (an rc comparator only matches the same [major,minor,patch], per node-semver) means >=0.1.0-rc.5 silently excludes 0.1.2-rc.1 — so the "declared range" was technically satisfied but the run was against the wrong line. A compat gate must compare against what's actually resolved/installed, and the error must name the real version pair.

2. Pre-release matching is the sharp edge. Your open question #3 is the critical one. ^0.1.0 does NOT match 0.1.3-alpha.2 by default (semver pre-release excludes non-matching tuples). If DSH ships as 0.1.x-alpha/rc (its whole public history so far), a plugin declaring ^0.1.0 either:

• silently blocks all prereleases (plugin never loads in dev builds), or
• requires the loader to strip pre-release tags before comparing (which then makes ^0.1.0 match 0.1.3-alpha.2 — the common dev-path behavior you'd want).
  Decide this explicitly; it changes the answer for every plugin. I'd recommend comparing on the stripped base version with an explicit pre-release compatible flag, defaulting to tolerant, because the ecosystem currently runs almost entirely on prereleases.

3. cordis.yml vs package.json (your question #1). I'd put the author-declared intent in the plugin's own package.json (it's the package's contract, deduplications-friendly, and CI can read it without parsing a config). cordis.yml is the mount config — it describes how a specific profile assembles entries, and in a bundle the plugin is often mounted by the host, not self-declared. Keeping "which versions am I compatible with" next to name/version in package.json is the natural home and plays best with your CI-integration benefit (#5). The loader can then read it from the resolved package metadata at load time.

The default-when-absent answer (your question #2) is also load-bearing: this ecosystem is pre-1.0 and the public API is explicitly pre-stable, so defaulting to * (tolerant) is right today — but it means the gate is advisory, not protective, until 1.0. That's an honest tradeoff to put in the feature description: a compat gate only protects users once authors actually declare ranges, so it must ship with tooling that makes declaring cheap (a codemod to add the field, or a CI nudge when a DSH release ships).

I'm speaking as a plugin author who has shipped six @argszero/cordis-plugin-* packages against this unstable API — the "silent break on upgrade" is the single most common complaint, and a compat gate + clear pre-release rule is exactly the right first-class fix. Happy to validate the semver-matching semantics against a real plugin matrix if you draft the loader predicate.