跳转到主要内容
插件 API 只有一个版本号：wit/ 中 WIT 包的版本（main 上是 openidea:plugin@1.5.0）。宿主的引擎版本和 SDK 的 API_VERSION 始终与它一致，SDK 里也带着一份完全相同的 WIT 文件。
插件系统目前是预览版。下面的兼容规则适用于已发布的 1.x 版本；main 上尚未发布的内容在发布前仍可能变化。

​
版本历史

每个版本新增内容的完整列表见 plugins/README.md。

​
声明所需版本

plugin.toml 中的 engines.openidea 是对插件 API 的 semver 版本要求：
  • 要求与 IDE 自身的 API 版本不匹配时，IDE 拒绝安装或加载该插件包。
  • 选择能覆盖你所用功能的最低版本。^1.0 能在所有 1.x IDE 中加载。
  • 部分清单功能会强制最低版本：清单用了它们却仍兼容更旧的 API 时，安装和 openidea-plugin check 都会拒绝。

​
组件本身的版本

除了清单，IDE 还会读取组件构建时所针对的 API 版本：组件所有 openidea:plugin/* 导入和导出中的最高版本，也就是编译时所用 SDK（或 WIT 文件）的版本。
  • 组件的主版本不同，或次版本比 IDE 实现的更新时，安装和 openidea-plugin check 会拒绝它，并提示更新 IDE 或用较旧的 SDK 重新构建。
  • 它们还会把组件与 IDE 实际链接一次。如果组件导入了 IDE 在同一版本下没有的函数（用未发布的 WIT 构建），同样会被拒绝。
  • check 会打印这个版本：code: dist/plugin.wasm (…, plugin API 1.4)。
所以，请针对你想支持的最旧 IDE 版本的 SDK 来构建。openidea-plugin new 生成的插件依赖工具所在版本 tag 的 SDK：
改 tag 就能针对更新的 API 构建。从 main 构建的组件使用的是未发布的 API，无法在已发布的 IDE 中加载。 在插件市场索引中，每个版本的 engine 是清单的要求再收窄到组件的 API（例如 ^1.0, ^1.4）。一个插件可以同时列出多个版本，每个 IDE 会得到它能加载的最新版本；一个都加载不了时，插件显示为不兼容，并说明所需的 API。

​
兼容规则

wasmtime 按 semver 链接组件：导入 openidea:plugin/x@1.0.0 的组件可以链接到定义了 @1.4.0 的宿主。但函数类型必须完全一致，所以已发布的 1.x 只能增加：
  1. 已发布的类型和签名永不改变。 不加 record 字段、不加 variant 或 enum 分支、不改名、不加参数。新功能用新类型和新函数。会持续增长的集合（补全类型、图标、事件类型等）用字符串表示；会增长的 variant 都有一个 other 分支，携带类型名和 JSON 数据，让旧插件和旧 IDE 能原样传递。
  2. 宿主 interface（导入）可以增加函数和 interface。 旧组件不会导入它们。
  3. 插件 interface（导出）一旦发布就不再增加函数。 插件侧的新功能放进新 interface，对应新的可选 world。
  4. 宿主检查每个组件的 API 版本，如上所述。
  5. 一个版本号贯穿 wit/、宿主和 SDK。
  6. 1.x 调用是同步的，文档整体传递。 WASI 0.3 异步组件计划在 2.0 引入，宿主中的适配层会让 1.x 插件继续运行。
这些规则有自动检查：
  • sdk/rust/openidea-plugin/tests/api_frozen.rs 把 wit/ 与最新已发布版本的快照 sdk/rust/openidea-plugin/tests/api/released/（当前为 1.4.0）比较，所有已发布的 interface、类型、函数和 world 都必须原样存在。
  • crates/ide-plugin/tests/api_compat.rs 检查各处版本一致、SDK 的 WIT 副本一致，以及模拟的下一个次版本宿主仍能链接所有已发布组件，而不同主版本的宿主不能。
  • 如果 wit/ 的版本没有对应快照，发布流程会拒绝发布。

​
旧清单

0.1 格式的清单（openidea-api = "0.1"）中的贡献仍能加载，但 0.1 的代码不再运行，需要用 1.x SDK 重新构建。