feat: add plugin system version constraints

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 才内置或才稳定可用的系统能力，例如浏览器运行时、统一缓存、智能体工具注册等。