create-moviepilot-plugin

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.
• Plugin repository conventions: MoviePilot-Plugins uses plugins.v2/ with package.v2.json for V2 plugins; legacy or cross-generation entries may use plugins/ with package.json.
• When working in or from MoviePilot-Plugins, read its README.md, docs/Repository_Guide.md, and docs/V2_Plugin_Development.md. For scenario-specific extensions, read the matching docs/faq/*.md.

Code Tool Workflow

• Use execute_command(action="run") with rg and narrow globs or paths to locate plugin classes, extension points, tests, and package entries. Use list_directory only when inspecting one known folder or a configured remote storage backend.
• 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.
• 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: use query_market_plugins when the running instance is available.
   • Installed plugin candidates: use query_installed_plugins; its summaries include repo_url when the source can be matched from a local plugin repository or plugin market metadata.
   • For Vue federation examples, prefer current compliant plugins such as MoviePilot-Plugins/plugins.v2/agenttokens/ and the frontend example MoviePilot-Frontend/examples/plugin-component/.
4. Determine the target source path:
   • Query PLUGIN_LOCAL_REPO_PATHS with query_system_settings 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, set it before writing plugin code: update_system_settings(setting_key="PLUGIN_LOCAL_REPO_PATHS", value="local-plugins", operation="replace"). local-plugins is resolved relative to the MoviePilot root by the local plugin source loader. Create that source directory and write the plugin under it; do not write new plugin source 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

Default to V2 layout for new local plugins:

<local-plugin-repo>/
├── package.v2.json
└── plugins.v2/
    └── <plugin_id_lower>/
        ├── __init__.py
        ├── requirements.txt        # 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.v2/<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 V2-first work, prefer package.v2.json and plugins.v2/.

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": ">=2.12.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.
• Do not add dependencies unless they are actually required. If requirements.txt changes, the user must reinstall the plugin; hot reload is not enough to install dependencies.
• 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

Extension Points

Use only the extension points the requested plugin actually needs:

• Configuration: get_form() returns Vuetify form schema and default data; init_plugin() reads config; update_config() persists internal changes.
• Data: use save_data(), get_data(), del_data(), and get_data_path().
• Notification: use post_message() instead of directly calling message modules.
• APIs: return route definitions from get_api(); default auth is apikey when auth is omitted. Vue component APIs should normally use auth: "bear" and be called through the api prop passed by the frontend.
• Commands: return slash-command definitions from get_command() and dispatch through MoviePilot events.
• Services: return scheduler services from get_service() and always clean them up in stop_service().
• Dashboards: use get_dashboard_meta() and get_dashboard() for homepage widgets.
• Workflow actions: use get_actions(); action functions receive ActionContent first and return (success, action_content).
• Agent tools: use get_agent_tools(); each tool class must inherit app.agent.tools.base.MoviePilotTool.
• Custom Vue UI: implement get_render_mode() only when Vuetify schema cannot satisfy the request. Return ("vue", "<compiled-assets-path>") and include built frontend assets in the plugin directory.

Vue Federation UI

Use Vue federation only after the Pre-Flight UI decision says JSON schema is not enough. A Vue plugin must align backend methods, built files, and federation exposes.

Backend requirements:

from typing import Any, Dict, List, Tuple


@staticmethod
def get_render_mode() -> Tuple[str, str]:
    """声明插件使用 Vue 联邦组件渲染。"""
    return "vue", "dist/assets"


def get_form(self) -> Tuple[List[dict], Dict[str, Any]]:
    """Vue 模式下返回默认配置模型。"""
    return [], self._current_config()


def get_page(self) -> List[dict]:
    """Vue 模式下详情页由远程 Page 组件渲染。"""
    return []

When the plugin needs a main-layout sidebar page, also implement:

def get_sidebar_nav(self) -> List[Dict[str, Any]]:
    """声明插件在主界面左侧导航栏中的全页入口。"""
    if not self.get_state():
        return []
    return [
        {
            "nav_key": "main",
            "title": "我的插件",
            "icon": "mdi-puzzle",
            "section": "system",
            "permission": "manage",
            "order": 10,
        }
    ]

Sidebar rules:

• Sidebar entries are only aggregated for enabled plugins whose get_render_mode() returns "vue".
• section must be one of start, discovery, subscribe, organize, system; invalid values fall back to system.
• permission may be subscribe, discovery, search, manage, or admin; invalid values are ignored.
• nav_key defaults to main and must not contain /, ?, #, or spaces.
• Multiple sidebar entries are allowed; each entry needs a stable nav_key.

Frontend federation requirements:

federation({
  name: 'MyPlugin',
  filename: 'remoteEntry.js',
  exposes: {
    './Page': './src/components/Page.vue',
    './Config': './src/components/Config.vue',
    './Dashboard': './src/components/Dashboard.vue',
    './AppPage': './src/components/AppPage.vue',
    './AppPageSettings': './src/components/AppPageSettings.vue',
  },
  shared: {
    vue: { requiredVersion: false, generate: false },
    vuetify: { requiredVersion: false, generate: false, singleton: true },
    'vuetify/styles': { requiredVersion: false, generate: false, singleton: true },
  },
  format: 'esm',
})

Build requirements:

• Set Vite build.target to esnext because federation uses top-level await.
• Use cssCodeSplit: true and scoped/component-local styles where possible.
• Build with the frontend project's documented command, then keep remoteEntry.js and every JS/CSS/asset file it references under dist/assets.
• Do not add frontend runtime dependencies to the plugin Python requirements.txt; keep frontend dependencies in the frontend build project.

Component contracts:

• Page renders the plugin detail dialog and may emit action, switch, and close.
• Config renders plugin settings, receives initialConfig and api, and emits save, close, and switch.
• Dashboard receives config and allowRefresh.
• AppPage renders the main-layout sidebar page and receives api, pluginId, and navKey.
• For sidebar nav_key=main, the frontend loads ./AppPage then ./Page.
• For any other nav_key, the frontend loads ./AppPage{PascalCase(nav_key)}, then ./AppPage, then ./Page. Examples: settings -> AppPageSettings, my_tool -> AppPageMyTool.
• A single AppPage may branch on navKey, or separate AppPage{PascalCase} files may be exposed for specific entries.

Vue API calls:

• Define frontend-facing plugin APIs with auth: "bear".
• Call them with the injected API object, for example props.api.get(\plugin/${props.pluginId}/history`)`.
• Do not pass settings.API_TOKEN into Vue components for browser-side calls.

Local Install And Reload

1. After writing files in a configured local plugin repository, call query_market_plugins(query="<PluginID>", force_refresh=True) to confirm the local source is visible.
2. Install or reinstall with install_plugin(plugin_id="<PluginID>", force=True). The install flow copies the source into app/plugins/<plugin_id_lower>/.
3. If PLUGIN_AUTO_RELOAD or development mode is enabled, Python source changes in an installed local plugin can auto-sync and reload. If it is not enabled, call reload_plugin(plugin_id="<PluginID>") after editing runtime files.
4. When requirements.txt changes, reinstall with force=True; reloading alone does not install new dependencies.

Validation

• Re-read the changed files and confirm class name, directory name, package ID, and package version are consistent.
• Confirm every public class, public method, and public function has a Chinese docstring.
• Confirm every newly written function or method has a Chinese docstring, even when it is private helper code.
• For Vue federation plugins, confirm get_render_mode() returns ("vue", "dist/assets") or the actual built asset path, and that dist/assets/remoteEntry.js exists.
• For sidebar plugins, confirm the plugin is enabled, get_state() returns True, get_sidebar_nav() returns valid items, and matching AppPage exposes exist for all non-main nav_key values or a generic AppPage handles them.
• Confirm frontend-facing API routes use auth: "bear" and browser code calls them through the provided api prop.
• Keep external HTTP calls behind MoviePilot utilities and avoid real network calls in tests.
• If the plugin has non-trivial logic, add or update pytest-native tests. Plugin repositories can use app.testing.bootstrap.prepare_v2_backend() to prepare a temporary MoviePilot backend and inject <repo>/plugins.v2 into sys.path.
• Run the narrowest allowed validation for the touched area. In this repository, follow docs/rules/03-commands.md; for plugin-only repositories, follow their own documented validation commands.
• For plugin repository Python changes, use the host Python environment when possible and run at least syntax compilation for touched plugin files.
• For Vue federation changes, run the frontend project's documented typecheck and build commands when available, then verify the built assets were copied to the plugin directory.

Vue Federation Troubleshooting

• GET /api/v1/plugin/remotes?token=moviepilot should include the plugin with a URL ending in /plugin/file/<plugin_id_lower>/<dist_path>/remoteEntry.js.
• GET /api/v1/plugin/sidebar_nav should include sidebar entries for enabled Vue plugins with valid nav_key, section, and permission.
• If the console says Module name 'vue' does not resolve to a valid URL, check the federation shared config and use requiredVersion: false.
• If the console says top-level await is unavailable, set build.target to esnext.
• If dynamic import fails, check the remote file request status, the computed remoteEntry.js path, and whether the installed runtime plugin directory actually contains the built assets.
• If a sidebar page is blank, check the expose name resolution for the current nav_key and fallbacks (AppPage{PascalCase} -> AppPage -> Page).

Final Report

Report:

• Plugin ID, source path, and runtime path if installed.
• Package file changed (package.v2.json or package.json).
• UI mode used (vuetify JSON or vue federation), and for Vue plugins the exposed components and built asset path.
• Whether the plugin was installed or reloaded.
• Validation commands run, or why validation was not run.