feat: add plugin system version constraints

README.md

@@ -42,6 +42,7 @@ MoviePilot-Plugins/
 - MoviePilot 会优先读取 `package.v2.json` 中与当前版本标识匹配的插件定义。
 - 如果某个插件不在 `package.v2.json` 中，但其 `package.json` 条目声明了 `"v2": true`，则会作为“兼容 V2 的默认插件”继续显示和安装。
 - `package.v2.json` 中的插件代码通常放在 `plugins.v2/<plugin_id_lower>/`；`package.json` 中的插件代码通常放在 `plugins/<plugin_id_lower>/`。
+- 插件如果依赖特定主系统版本，可在条目中增加 `system_version`，格式参考 pip 依赖版本范围，例如 `">=2.12.0,<3"`；未定义该字段时不做主系统版本检查。
 - 插件目录名必须是插件类名的小写形式，插件主类必须定义在对应目录的 `__init__.py` 中。
 - 插件市场里看到的版本、图标、作者、权限级别，都来自 `package.json` / `package.v2.json`；运行时真正生效的类属性来自插件代码中的 `plugin_*` 字段，两者必须保持同步。
 
@@ -100,6 +101,7 @@ MoviePilot-Plugins/
 - `package.json` / `package.v2.json` 中的 `version` 必须与插件类中的 `plugin_version` 保持一致，否则用户会看到错误的升级提示。
 - `name`、`description`、`icon`、`author`、`level` 建议与插件类属性保持一致，避免插件市场展示与实际运行信息不一致。
 - `history` 用于展示插件更新日志，建议每次发布都补齐一条可读变更说明。
+- `system_version` 用于声明插件可安装的 MoviePilot 主系统版本范围，格式参考 pip 依赖版本约束；例如插件依赖 v2.12.0 新增能力时填写 `">=2.12.0"`。
 - 需要走 GitHub Release 压缩包分发的插件，请在对应索引条目中增加 `"release": true`，并确保仓库中的发布工作流能够定位到对应目录。
 
 

docs/FAQ.md

@@ -18,3 +18,4 @@
 - [14. 如何在插件中通过消息持续与用户交互？](./faq/14-message-interaction.md)
 - [15. 如何在插件中使用系统级统一缓存？](./faq/15-use-system-cache.md)
 - [16. 如何在插件中注册智能体工具？](./faq/16-register-agent-tools.md)
+- [17. 如何限定插件可安装的 MoviePilot 主系统版本？](./faq/17-limit-moviepilot-version.md)

docs/Repository_Guide.md

@@ -90,6 +90,7 @@ V2 优先插件索引文件。MoviePilot 在 V2 环境下会优先读取这里
 - `icon`：图标文件名或完整 HTTP URL
 - `author`：作者
 - `level`：用户可见级别
+- `system_version`：可安装的 MoviePilot 主系统版本范围，格式参考 pip 依赖版本约束，例如 `">=2.12.0,<3"`
 - `history`：更新日志
 - `release`：是否使用 GitHub Release 压缩包发布
 - `v2`：默认索引中的插件是否兼容 V2
@@ -104,12 +105,14 @@ MoviePilot 当前的插件版本选择逻辑可以概括为：
 2. 优先检查 `package.v2.json` 中是否存在该插件
 3. 若不存在，再检查 `package.json`
 4. 只有当 `package.json` 中对应条目显式声明 `"v2": true` 时，才会作为 V2 兼容插件继续使用
+5. 如果条目声明了 `system_version`，安装、更新检测和本地插件同步会继续检查当前 MoviePilot 主程序版本是否落在该范围内；未声明则不检查
 
 这意味着：
 
 - 同一个插件若在 `package.v2.json` 中已有专用实现，就不要再依赖 `package.json` 中的兼容声明做“隐式覆盖”。
 - 新写的 V2 专用插件，优先放 `plugins.v2/`，并把元数据写入 `package.v2.json`。
 - 真正跨版本共用一套实现时，再使用 `package.json + "v2": true` 的方式。
+- 依赖宿主新增能力的插件需要同步声明 `system_version`，否则旧版 MoviePilot 仍可能看到更新入口但安装后无法加载。
 
 ## 5. 与宿主仓库的协作边界
 

docs/V2_Plugin_Development.md

@@ -177,11 +177,14 @@ class MyPlugin(_PluginBase):
     "version": "1.0.0",
     "icon": "Moviepilot_A.png",
     "author": "your-name",
+    "system_version": ">=2.12.0",
     "level": 1
   }
 }
 ```
 
+`system_version` 是可选字段。插件依赖某个 MoviePilot 主系统版本才提供的能力时再声明，格式参考 pip 依赖版本范围；不声明时宿主不会做主系统版本检查。
+
 ## 4. `_PluginBase` 的核心能力
 
 V2 插件的核心宿主基类是 `MoviePilot/app/plugins/__init__.py` 中的 `_PluginBase`。开发时需要优先理解它暴露出来的扩展点。

docs/faq/17-limit-moviepilot-version.md

@@ -0,0 +1,26 @@
+# 17. 如何限定插件可安装的 MoviePilot 主系统版本？
+
+如果插件依赖某个 MoviePilot 主程序版本才提供的后端接口、前端能力、事件字段或运行时模块，应在对应的 `package.json` / `package.v2.json` 条目中增加 `system_version` 字段。
+
+```json
+{
+  "MyPlugin": {
+    "name": "我的插件",
+    "version": "1.0.0",
+    "system_version": ">=2.12.0"
+  }
+}
+```
+
+字段规则：
+
+- `system_version` 的格式参考 pip 依赖版本范围，也就是 PEP 440 specifier，例如 `">=2.12.0"`、`">=2.12.0,<3"`、`"~=2.12"`。
+- MoviePilot 当前版本号带 `v` 前缀也可以正常比较，因此 `>=v2.12.0` 和 `>=2.12.0` 都能解析；文档和索引中推荐写不带 `v` 的形式。
+- 未定义 `system_version` 时，宿主不做主系统版本检查，保持旧插件兼容。
+- 如果当前主系统版本不满足范围，插件市场会显示不兼容提示，安装和更新都会被拒绝。
+
+发布插件时，建议在以下场景补充该字段：
+
+- 插件调用了新版本才存在的后端 API、helper、chain、module 或事件字段。
+- 插件的 Vue 远程组件依赖新版本前端才支持的加载、侧栏、仪表板或渲染行为。
+- 插件换用了新版本 MoviePilot 才内置或才稳定可用的系统能力，例如浏览器运行时、统一缓存、智能体工具注册等。

package.v2.json

@@ -700,6 +700,7 @@
     "icon": "agentresourceofficer.png",
     "author": "liuyuexi1987",
     "level": 1,
+    "system_version": ">=2.12.0",
     "history": {
       "0.2.72": "影巢自动登录兜底流程改用 CloakBrowser，移除插件对 Playwright 浏览器调用的直接依赖。",
       "0.2.71": "新增流媒体推荐：聚合 Netflix、Disney+、Apple TV+、Prime Video 四大平台，基于 TMDB discover 按热度/评分推荐本月上新、近期热门电影和剧集；结果页改为只读列表，仅支持显式前缀触发。",
@@ -982,6 +983,7 @@
     "icon": "Wecom_A.png",
     "author": "RamenRa",
     "level": 2,
+    "system_version": ">=2.12.0",
     "history": {
       "v2.0.1": "修复企业微信后台页面语言未稳定切换为中文导致无法匹配配置按钮的问题。",
       "v2.0.0": "V2 专用大版本改用 CloakBrowser 启动企业微信浏览器流程，默认插件不再声明 V2 兼容。",
@@ -1006,6 +1008,7 @@
     "author": "thsrite",
     "level": 2,
     "release": true,
+    "system_version": ">=2.12.0",
     "history": {
       "v3.0.0": "V2 专用大版本的浏览器仿真改用 CloakBrowser 获取页面，默认插件不再声明 V2 兼容。",
       "v2.0.3": "增加启用浏览器仿真功能发送请求",
@@ -1024,6 +1027,7 @@
     "icon": "contract.png",
     "author": "DzAvril",
     "level": 1,
+    "system_version": ">=2.12.0",
     "history": {
       "v2.0.0": "V2 专用大版本的渲染模式改用 CloakBrowser 获取站点页面，默认插件不再声明 V2 兼容。",
       "v1.4.1": "增加站点猪猪",