MoviePilot Plugin Developer

Create MoviePilot Plugin

Use this skill to build or revise MoviePilot plugins that can be developed from a local plugin source and installed into the running MoviePilot instance.

Ground Truth

• Host plugin contract: app/plugins/__init__.py, especially _PluginBase.
• Host plugin discovery, local source sync, install, reload: app/runtime/extensions/plugin_manager.py and app/adapters/external/market.py.
• Host plugin endpoints, API auth, static files, remotes, and sidebar nav: app/api/endpoints/plugin.py.
• Local development note: docs/development-setup.md.
• First identify the actual host generation from its source/version and the target plugin repository. MoviePilot V3 uses plugins.v3/ with package.v3.json; V2 uses plugins.v2/ with package.v2.json; legacy V1 uses plugins/ with package.json. Do not generate V2 paths for a V3 host.
• When working in or from MoviePilot-Plugins, read its README.md, docs/Repository_Guide.md, and the guide for the target generation: docs/Plugin_Development.md for V3, docs/V2_Plugin_Development.md for V2. For scenario-specific extensions, read the matching docs/faq/*.md.
• For V3, prefer the public app.sdk.* entry points documented by the current host and guide; do not copy old internal imports from a V2 example. Verify extension signatures against the installed host before using a template.

Task Scope

A request to create or fix a plugin authorizes relevant local source edits and validation. Reuse that authorization; it does not by itself authorize changing host configuration, installing/reloading the plugin, restarting, or publishing. Perform those steps when the user requested them or already approved their scope, honoring host confirmation requirements. Inspect auto-reload settings before editing a live watched plugin source; such edits can affect the runtime immediately and require that runtime effect to be within the authorized scope.

Code Tool Workflow

• Use execute_command(action="run") with rg and narrow globs or paths to locate plugin classes, extension points, tests, package entries, and directory contents.
• Read the relevant implementation and adjacent example before editing.
• If read_file reports truncation, continue with smaller start_line and end_line ranges until all relevant sections have been inspected.
• Before using a Python or Node.js dependency API, determine the exact installed or locked version from requirements, package manifests, lockfiles, local package source, and .pyi/.d.ts declarations. If those are insufficient, use search_web with the official documentation domain and browse_webpage to read the matching version. Do not guess API signatures from memory or mix examples from different major versions. Search the relevant package directory, .venv, or node_modules directly with rg instead of scanning the entire project without bounds.
• Pick the editing tool by scope. Use apply_patch when one logical change spans multiple files, adds new files, or deletes files: submit a single patch wrapped in *** Begin Patch / *** End Patch with *** Add File:, *** Update File:, and *** Delete File: sections; every context and removed line must match the current content exactly.
• Use edit_file for a single localized change in one file. Its old_text must identify one exact location by default; add surrounding context instead of enabling replace_all unless every match intentionally changes.
• Use write_file for one standalone new file. Existing files require overwrite=true for a full rewrite; first call read_file(include_metadata=true) and pass its sha256 as expected_sha256 when replacing previously read content.
• Use execute_command(action="run") for short validation, Git, and diagnostic commands. Use action="start" only for interactive or long-running commands, then continue through the returned session ID.
• Read the structured command result: only execution_outcome="succeeded" with exit_code=0 means a completed command passed. Inspect output on failure and output_file for a truncated log. A timeout or unknown result does not undo side effects and must not trigger a blind retry of a write.
• For background commands, resume using both output_until_seq and output_until_offset as since_seq and since_offset. Start with offset 0 for partial-chunk paging; last_seq is not a consumed position. Wait for new output in bounded intervals, and drain the remaining pages until output_complete=true for a complete log. Report any output_lost gap. An output_error after start/write/kill requires another read with a suitable byte limit, not another execution of the action.
• Do not use shell redirection or inline scripts to perform source edits or to bypass a file-tool permission error.
• When the plugin uses Vue federation, also read MoviePilot-Frontend/docs/module-federation-guide.md, MoviePilot-Frontend/docs/federation-troubleshooting.md, MoviePilot-Frontend/src/utils/federationLoader.ts, and MoviePilot-Frontend/src/pages/plugin-app.vue.
• Repository boundaries: MoviePilot owns runtime loading, API registration, events, services, data, and permissions; MoviePilot-Frontend owns plugin UI rendering, federation loading, and sidebar pages; MoviePilot-Plugins owns plugin source, icons, package indexes, and release metadata.

Pre-Flight

1. Understand the user request: plugin purpose, trigger mode, configuration, output UI, whether it needs a scheduler, API, command, workflow action, or agent tool.
2. Run the UI Mode Selection Gate before writing any UI code.
   • If the user already explicitly chose JSON config/Vuetify JSON or Vue federation, follow that choice.
   • If the plugin has any UI surface and the user has not chosen a mode, ask them to choose between the two modes below and wait for the answer before implementing UI files or schemas.
   • Do not silently default to either mode just because one seems easier.
3. Inspect existing plugins before creating a new one:
   • Local runtime examples: app/plugins/<plugin>/__init__.py
   • Market/local source candidates: call moviepilot_api with operation_id=plugin.market when the running instance is available.
   • Installed plugin candidates: use operation_id=plugin.installed; its summaries include repo_url when the source can be matched from a local plugin repository or plugin market metadata.
   • For Vue federation examples, use a current plugin from the matching generation and MoviePilot-Frontend/examples/plugin-component/.
4. Determine the target source path:
   • Query PLUGIN_LOCAL_REPO_PATHS with operation_id=config.system.get when possible.
   • If exactly one local plugin repository is configured, prefer that path.
   • If several are configured, choose the one the user named; otherwise ask which repository to use.
   • If none is configured, prepare the source in an appropriate local directory. When local installation/configuration is authorized, register it with operation_id=config.system.update with setting_key="PLUGIN_LOCAL_REPO_PATHS", the chosen source path as value, and operation="replace". A relative path such as local-plugins resolves against the MoviePilot root. Write the plugin under the chosen source; do not write directly into app/plugins/ unless the user explicitly asks for a runtime-only experiment.
5. Choose the plugin ID:
   • Class name is the plugin ID, for example MyNotifier.
   • Directory name is the class name lowercased, for example mynotifier.
   • Avoid collisions with installed or market plugins unless the user is explicitly modifying that plugin.
   • Do not hardcode the original plugin ID for data/config namespaces when the plugin may support clones; use self.__class__.__name__.

UI Mode Selection Gate

MoviePilot plugin UI has exactly two implementation modes. Make the user choose one whenever the request includes configuration, detail pages, dashboards, sidebar pages, or any other plugin UI and the mode is not already explicit.

Ask a concise question like:

这个插件 UI 用哪种方式实现？
1. JSON 配置：后端返回 Vuetify JSON，适合普通配置表单、简单详情页和轻量仪表板。
2. 联邦 UI：独立 Vue 远程组件，适合复杂交互、自定义布局、侧栏全页或多页面。

Selection rules:

• JSON config / Vuetify JSON: implement get_form(), get_page(), and get_dashboard() with JSON component schemas. No frontend build or dist/assets/remoteEntry.js is needed.
• Federation UI / Vue remote component: implement get_render_mode(), expose Vue components through Vite federation, build frontend assets into the plugin directory, and use get_sidebar_nav() only when a sidebar page is requested.
• If the plugin truly has no user-facing UI, state that no UI mode is needed and implement only the backend extension points the request requires.
• Backend-only work may proceed while waiting only if it cannot constrain or preclude either UI mode.

Local Source Layout

For a verified V3 host, use this layout for new local plugins. For V2, use package.v2.json and plugins.v2/ instead and follow its dependency contract.

<local-plugin-repo>/
├── package.v3.json
└── plugins.v3/
    └── <plugin_id_lower>/
        ├── __init__.py
        ├── pyproject.toml          # only when extra runtime dependencies are necessary
        └── ...                     # helper modules, schemas, static assets

For a Vue federation plugin, the runtime requirement is the built remote assets under the plugin directory:

plugins.v3/<plugin_id_lower>/
├── __init__.py
├── dist/
│   └── assets/
│       ├── remoteEntry.js
│       └── ...                     # JS/CSS/assets referenced by remoteEntry
├── package.json                    # optional frontend build project metadata
├── vite.config.js                  # optional frontend build config
└── src/                            # optional source, not required at runtime

Do not rely on frontend source files at runtime. If the source is kept in the plugin repository for maintainability, still build and ship the dist/assets files required by remoteEntry.js.

Only use the legacy layout when the user explicitly needs it:

<local-plugin-repo>/
├── package.json
└── plugins/
    └── <plugin_id_lower>/
        └── __init__.py

For legacy package.json entries that should work on V2, include "v2": true. For current V3 work, use package.v3.json and plugins.v3/.

Package Metadata

Add or update the package entry for the plugin ID. Keep the package version and the class plugin_version synchronized.

{
  "MyNotifier": {
    "name": "通知示例",
    "description": "根据用户配置发送示例通知。",
    "labels": "消息通知",
    "version": "1.0.0",
    "icon": "mynotifier.png",
    "author": "local",
    "level": 1,
    "system_version": ">=3.0.0",
    "history": {
      "v1.0.0": "初始版本"
    }
  }
}

Rules:

• The package object key must match the plugin class name.
• version must match plugin_version.
• name, description, icon, author, labels, and level should match the plugin class attributes when those attributes exist (plugin_name, plugin_desc, plugin_icon, plugin_author, plugin_label, auth_level).
• history should record user-readable changes for each published version.
• Use system_version when the plugin depends on a host capability introduced in a specific MoviePilot version, including new backend APIs, helpers, events, Vue federation behavior, sidebar nav, dashboard behavior, or agent tools.
• Use "release": true only when the plugin is intentionally distributed by a GitHub Release archive.
• New plugin entries should usually be appended to the package index so they appear as newer marketplace items.
• Set system_version to the actual minimum version providing the APIs used; the example is not proof that every host capability exists in 3.0.0.
• Do not add dependencies unless required. Use the host generation's manifest contract (pyproject.toml for current V3). Dependency changes require the host installation flow; hot reload alone does not install them.
• Plugin dependencies are installed into the shared MoviePilot Python environment. Do not pin or downgrade packages already provided by MoviePilot unless the user has explicitly accepted the compatibility risk.

Implementation Skeleton

Implement all abstract methods from _PluginBase. All new functions and methods need Chinese docstrings; public classes, public methods, and public functions are a hard review gate.

from typing import Any, Dict, List, Optional, Tuple

from app.plugins import _PluginBase


class MyNotifier(_PluginBase):
    """通知示例插件。"""

    plugin_name = "通知示例"
    plugin_desc = "根据用户配置发送示例通知。"
    plugin_icon = "mynotifier.png"
    plugin_version = "1.0.0"
    plugin_label = "消息通知"
    plugin_author = "local"
    plugin_config_prefix = "mynotifier_"
    plugin_order = 100
    auth_level = 1

    _enabled = False
    _message = ""

    def init_plugin(self, config: dict = None) -> None:
        """根据插件配置初始化运行状态。"""
        self.stop_service()
        self._enabled = False
        self._message = ""
        if not config:
            return
        self._enabled = bool(config.get("enabled"))
        self._message = str(config.get("message") or "")

    def get_state(self) -> bool:
        """获取插件启用状态。"""
        return self._enabled

    @staticmethod
    def get_command() -> List[Dict[str, Any]]:
        """返回插件远程命令列表。"""
        return []

    def get_api(self) -> List[Dict[str, Any]]:
        """返回插件 API 列表。"""
        return []

    def get_form(self) -> Tuple[Optional[List[dict]], Dict[str, Any]]:
        """返回插件配置表单与默认配置。"""
        return [
            {
                "component": "VForm",
                "content": [
                    {
                        "component": "VSwitch",
                        "props": {
                            "model": "enabled",
                            "label": "启用插件"
                        }
                    },
                    {
                        "component": "VTextField",
                        "props": {
                            "model": "message",
                            "label": "通知内容"
                        }
                    }
                ]
            }
        ], {
            "enabled": False,
            "message": ""
        }

    def get_page(self) -> Optional[List[dict]]:
        """返回插件详情页面。"""
        if not self._enabled:
            return None
        return [
            {
                "component": "VAlert",
                "props": {
                    "type": "info",
                    "text": self._message or "插件已启用"
                }
            }
        ]

    def stop_service(self) -> None:
        """停止插件后台服务并释放资源。"""
        return None