版本兼容性

这一页讲「我的插件能不能在目标环境跑起来」怎么判断。分三件事：后端看 contractsRange，前端看构建产物里的清单版本字段，SDK 与工具链要求同版本。

当前发行版和完整兼容矩阵见发版说明。本页只解释判断方法，不重复维护发行记录。

后端宿主契约版本范围（`contractsRange`）

后端宿主有一个契约版本；插件在后端源清单 fh2-plugin.json 里声明自己兼容的范围（构建时进入 dist/plugin.json），装载时比对，不在范围内则拒绝装载。

值的写法：

contractsRange: "<比较式> [<比较式> ...]"   // 多个比较式用空格连接（AND）
比较式: (">=" | ">" | "<=" | "<" | "=" | "==") + 三段数字版本

不支持 ^、~、||、通配符和预发布号。

留空表示不检查：能装，但失去一层保护，不建议省略。

装载失败会明确提示契约不符。处理方式：先由部署方升级兼容的后端运行环境，再发布插件包。新包使用新清单字段而运行环境仍是旧版本时，也会被拒绝装载。

源清单 fh2-plugin.json 不写任何版本兼容字段；manifestVersion、engines、buildInfo 由 fh2-plugin build 写进 dist/fh2-plugin.json。

安装时宿主校验这些字段：清单版本不一致 → MANIFEST_INVALID；宿主版本不在 engines 声明的范围 → ENGINE_INCOMPATIBLE。

所以只发布构建产物，不要手写或手改这些字段。

插件 SDK 与工具链必须使用同一版本。版本不一致时 fh2-plugin validate / generate 报 FH2_SDK_VERSION_MISMATCH，应按开发者工具的依赖配置升级配套版本。

升级时两个包一起升，保持一致。

组合	结果
源清单直接交给宿主安装	拒绝：缺工具链写入的构建字段
构建产物的清单版本与宿主不一致	`MANIFEST_INVALID`
宿主版本不在 `engines` 范围	`ENGINE_INCOMPATIBLE`
前端权限声明了但当前宿主没有该能力	安装可成功；运行时 `get()` 返回 `undefined`，按能力缺失降级
后端新字段 + 旧宿主	严格解析拒装：先升级宿主再发包
旧式模板的后端清单装生产宿主	拒装：清单格式不同（见后端清单）

公共 ID、错误码、事件名、已有字段语义不原地修改；先新增并双栈支持，再标废弃，经迁移窗口后才移除。

「目录里存在」不等于「当前宿主可用」：新增能力不要求插件升级，但插件必须处理拿不到的情况（见能力目录）。

后端各运行实例应装载同一份插件资产（同版本、同资产指纹），由部署方确认装载一致，避免部分实例运行旧版。

现象	原因与处理
后端包装载报契约不符	`contractsRange` 不含宿主契约版本；调整范围，或先升级宿主
`validate` 报 `FH2_SDK_VERSION_MISMATCH`	SDK 与工具链版本不一致；统一到同一版本
安装报 `MANIFEST_INVALID`	用了手工改动或缺构建字段的产品；用 `fh2-plugin build` 重新产出
新包在旧环境装不上	严格解析 + 新字段：先升级宿主进程，再发插件包