mirror of
https://github.com/l0ng-ai/openidea.git
synced 2026-11-14 16:07:52 +00:00
Muuandmuutot
c8bdfa8edd
Plugins read problems from a host-owned snapshot that records every Diagnostics event per file and producer, instead of the UI-reported Problems reports, so what a plugin sees no longer depends on window lifetime or the invoking window. Adds the problems-changed workbench event (plugin API 1.8.0, gated at needs_api 8), editor focus events for files of other windows, severity style previews in plugin settings, and lays plugin annotations on the line-end chain before code-vision hints and inline blame. Components and fixtures are rebuilt for API 1.8.0. Co-authored-by: muutot <92625353+muutot@users.noreply.github.com>
84 lines
11 KiB
Plaintext
84 lines
11 KiB
Plaintext
---
|
||
title: "API 版本与兼容"
|
||
description: "engines.openidea、插件 API 从 1.0 到 1.6 的各个版本，以及让已发布插件在新 IDE 中继续加载的规则。"
|
||
---
|
||
|
||
插件 API 只有一个版本号：[`wit/`](https://github.com/l0ng-ai/openidea/tree/main/wit) 中 WIT 包的版本（`main` 上是 `openidea:plugin@1.8.0`）。宿主的引擎版本和 SDK 的 `API_VERSION` 始终与它一致，SDK 里也带着一份完全相同的 WIT 文件。
|
||
|
||
<Note>插件系统目前是预览版。下面的兼容规则适用于已发布的 1.x 版本；`main` 上尚未发布的内容在发布前仍可能变化。</Note>
|
||
|
||
## 版本历史
|
||
|
||
| API | 随哪个版本发布 | 主要内容 |
|
||
| ----- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 1.0.0 | OpenIDEA 0.1.36 | 基础 API：命令、事件、存储、任务、项目和编辑器访问、VCS、诊断、网络与密钥、进程、声明式视图和自定义编辑器、设置、编辑器 provider、syntax provider |
|
||
| 1.1.0 | OpenIDEA 0.1.37 | `vcs.remotes`、`ui.copy-to-clipboard`、`ui.open-url`，从视图中打开项目文件的指定行 |
|
||
| 1.2.0 | OpenIDEA 0.1.38 | 后台文档索引器；选择器、输入框和确认框；插件自定义的 `when` 上下文键；项目视图中选中的文件；清单 `icon`；`viewItem.context` 菜单 |
|
||
| 1.3.0 | OpenIDEA 0.1.39 | 提交信息和提交前检查、Services 详情面板、输入时诊断、悬停、内嵌提示、语义 token、改动文件的代码操作、HTTP 端点、项目外文件（`fs.read`/`fs.write`、`project.write`、插件私有目录）、批量 `files-changed` 事件和路径过滤、工作区符号、长时间运行的进程、带按钮的通知、翻译、多页设置、文件模板变量、Web 视图 PTY、日志标签页和内容标签页 |
|
||
| 1.4.0 | OpenIDEA 0.1.40 | `net.http:`、`ipc:`、`ide.commands` 和 `database.sources` 能力；编辑器与项目快照、装饰、文本搜索、问题视图、Git log/blame/diff；输出通道；OAuth 回环；运行、终端会话、运行配置、测试结果解析和运行目标；格式化等语言功能；嵌入语言；代码片段；更多菜单位置；数据库数据源；MCP 工具 |
|
||
| 1.5.0 | OpenIDEA 0.1.41 | `Project::notify`（只在某个项目的窗口中显示通知）、`net:ask` 能力、运行目标启动前校验、运行目标按命令设置工作目录参数 |
|
||
| 1.6.0 | OpenIDEA 0.1.43 | 面向事件流插件、受容量限制且绑定项目的后台 WebSocket |
|
||
| 1.7.0 | OpenIDEA 0.1.44 | `views.open-diff`：在差异查看器中对比两段文本，例如评审中某个文件的修改前后 |
|
||
| 1.8.0 | `main` 上开发中 | `problems-changed` 工作台事件：宿主按文件保存每个生产者的诊断，注解跟着文件走，而不是跟着调用它的窗口 |
|
||
|
||
每个版本新增内容的完整列表见 [`plugins/README.md`](https://github.com/l0ng-ai/openidea/blob/main/plugins/README.md)。
|
||
|
||
## 声明所需版本
|
||
|
||
`plugin.toml` 中的 `engines.openidea` 是对插件 API 的 semver 版本要求：
|
||
|
||
```toml
|
||
engines.openidea = "^1.4"
|
||
```
|
||
|
||
- 要求与 IDE 自身的 API 版本不匹配时，IDE 拒绝安装或加载该插件包。
|
||
- 选择能覆盖你所用功能的最低版本。`^1.0` 能在所有 1.x IDE 中加载。
|
||
- 部分清单功能会强制最低版本：清单用了它们却仍兼容更旧的 API 时，安装和 `openidea-plugin check` 都会拒绝。
|
||
|
||
| 功能 | 要求 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
|
||
| `icon`、`viewItem.context` 菜单 | `^1.2` |
|
||
| `project.write`、`fs.write:`、`on-event:files-changed`；`endpoints`、`markerIcons`、`commitChecks`；provider kind `semantic-tokens`、`diagnostics`、`hover` 和 `inlay-hints`；设置的 `pages`、分组和数组；`commit.message` 菜单和子菜单；视图的 `group`、`when`、`header` 和 `location = "services"`；文件模板的 `fileName` 和 `variables` | `^1.3` |
|
||
| `net.http:`、`ipc:`、`ide.commands`、`database.sources`；`file-closed`、`settings-changed`、`input-mode-changed`、`run-exited`、`terminal-exited` 和 `content-tab-action` 事件；`runConfigurations`、`snippets`、`mcpTools`、命令 `icon`、运行检测器的 `framework`；API 1.4 的 provider kind 和嵌入语言；API 1.4 新增的菜单位置 | `^1.4` |
|
||
| `net:ask` | `^1.5` |
|
||
| `on-event:websocket-ready` 和后台 WebSocket | `^1.6` |
|
||
|
||
## 组件本身的版本
|
||
|
||
除了清单，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：
|
||
|
||
```toml
|
||
openidea-plugin = { git = "https://github.com/l0ng-ai/openidea", tag = "v0.1.40" }
|
||
```
|
||
|
||
改 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/`](https://github.com/l0ng-ai/openidea/tree/main/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 重新构建。
|