MoviePilot/AGENTS.md

MoviePilot AI Agent Guide

This file defines the default behavior for AI agents working in the MoviePilot repository. Unless a deeper directory provides another AGENTS.md, these rules apply to the entire repo.

1. Project Scope

• This repository contains the MoviePilot backend, CLI, MCP/API, Docker assets, and AI skills.
• The backend is based on FastAPI, with most code under app/.
• Frontend source code is not in this repository. The frontend source repository is MoviePilot-Frontend.
• This repository also includes the local CLI, database migrations, developer docs, tests, Docker scripts, and AI skills.

2. Working Principles

• Read the relevant implementation, tests, and docs before changing code. Do not infer behavior from directory names alone.
• Prefer the smallest correct change. Reuse existing functions, patterns, and naming whenever possible.
• Do not perform unrelated large refactors, mass renames, or formatting-only cleanup.
• Before adding a new abstraction, check whether it is actually reusable. If the logic fits well inside an existing function, class, or flow, keep it there.
• The worktree may contain user changes. Do not revert, overwrite, or reorganize changes you do not fully understand.
• Default to writing conclusions, validation results, and risk notes in Chinese unless the user asks otherwise.

3. Key Directories

• app/api/endpoints/: HTTP entrypoints. Handles auth, parameters, responses, and simple CRUD.
• app/chain/: Business orchestration layer for search, recognition, subscriptions, downloads, messaging flows, and similar use cases.
• app/modules/: Dynamically loaded system modules. Encapsulates pluggable downloaders, media servers, message channels, and other backend capabilities.
• app/helper/: Reusable low-level helper logic. Not a place for full business orchestration.
• app/core/config.py: Environment variables, deployment parameters, and startup-level settings.
• app/schemas/types.py: Shared enums and types such as SystemConfigKey and module categories.
• app/db/: Database models, sessions, and *_oper.py data access wrappers.
• moviepilot: Local CLI entrypoint and help text.
• database/versions/: Alembic migration scripts.
• docs/: CLI, MCP/API, and development workflow documentation.
• skills/: AI agent skills and related scripts.
• tests/: Pytest tests and a few manual test scripts.
• config/, .moviepilot.env, and *.db: Local config or runtime data. Do not modify or commit them unless the user explicitly asks for it.

4. Layering And Access Boundaries

API / Endpoint Layer

• Endpoints should only handle HTTP concerns: auth, parameter parsing, response models, streaming adaptation, and simple input validation.
• Simple list, detail, toggle, settings read/write, and pure CRUD endpoints may directly call app/db/ or an existing helper.
• If the logic coordinates multiple modules, triggers events, touches caches, or combines search, recognition, subscription, or download workflows, move it into chain.
• Prefer adding new endpoints to an existing domain file. Create a new endpoint file only when introducing a new top-level resource domain.
• After adding a new endpoint, register it in app/api/apiv1.py.

Chain Layer

• chain is the business orchestration layer shared by API, CLI, message interaction, agents, schedulers, and similar entrypoints.
• chain is responsible for composing module, helper, db, events, caches, and other stable chain capabilities.
• Inside chain, prefer calling module capabilities through run_module() or async_run_module(). Only use ModuleManager or similar helpers directly when you truly need to enumerate modules, inspect instances, or run health checks.
• chain should focus on use cases and workflows. It should not hold low-level protocol details, HTTP request objects, or page-specific parameter assembly.
• Before adding a new chain, ask whether this is a reusable business use case shared by multiple entrypoints, or a flow that coordinates multiple modules or resources. If it is just short logic for one endpoint, do not create a new chain.
• chain may call other chain classes when reusing stable domain logic, but avoid introducing new circular dependencies.

Module Layer

• module is the pluggable capability layer discovered and loaded by ModuleManager.
• Put logic in module when it represents a new downloader, media server, message channel, recognition backend, filtering backend, file-management backend, or any other capability that needs lifecycle management, priority, configuration switches, or independent testing.
• New modules should follow the existing base-class contract and implement or align with init_module(), init_setting(), get_name(), get_type(), get_subtype(), get_priority(), test(), and stop().
• A module should focus on one backend or one capability implementation. It should return domain results, not HTTP responses, and should not depend on endpoint auth or FastAPI request objects.
• chain -> module is the intended main direction. The repository contains a small number of historical module -> chain usages. Do not expand that pattern in new code. If a module needs shared business logic, prefer moving that logic up into chain or down into helper.
• Do not add direct module -> module coupling for new code. Cross-module orchestration should be handled by chain.

Helper Layer

• helper is for reusable low-level support logic such as path handling, config aggregation, site index loading, protocol wrappers, rate limiting, cache helpers, and page parsing.
• Add a new helper only when the logic is reused in multiple places, or when it is clearly a standalone low-level concern.
• If logic is used only by a single chain or a single module, prefer keeping it in the original file instead of turning helper into a dumping ground.
• If the code needs configuration switches, runtime loading, priorities, independent test entrypoints, or multi-implementation dispatch, it is probably a module, not a helper.
• helper must not become another orchestration layer. Full business workflows still belong in chain.

Preferred Call Directions

• Preferred direction: endpoint/CLI/agent/command -> chain -> module/helper/db
• Allowed direction: chain -> chain, as long as the reused logic is stable and does not introduce cycles.
• Cautious direction: endpoint -> db/model/oper/helper, only for simple queries, simple CRUD, or input normalization.
• Avoid for new code: module -> chain, module -> module, helper -> chain, helper -> endpoint.

5. Where New Capabilities Should Go

• Scenario: adding a new business workflow such as search, recognition, subscription, download orchestration, or message interaction. Action: prefer app/chain/ so API, CLI, agents, and schedulers can share the same orchestration logic.
• Scenario: adding a new downloader, media server, message channel, or other pluggable backend integration. Action: put it in app/modules/. If this introduces a new module category or subtype, also check app/schemas/types.py and related schemas.
• Scenario: adding a new public HTTP API. Action: put it in app/api/endpoints/, register it in app/api/apiv1.py, and add auth, schemas, docs, and tests. Move complex logic into chain.
• Scenario: adding a new low-level utility, parser, config reader, or protocol wrapper. Action: put it in app/helper/, but only if it is not a one-off implementation and not a full business use case.
• Scenario: adding a deployment-level, environment-level, or startup-time config such as ports, paths, proxies, switches, keys, or third-party service addresses. Action: put it in ConfigModel or Settings inside app/core/config.py.
• Scenario: adding a runtime business config, user-editable rule, or persistent system option. Action: prefer SystemConfigKey plus SystemConfigOper. Do not scatter raw string keys.
• Scenario: a config change should automatically reload a long-lived object. Action: add CONFIG_WATCH, on_config_changed(), and get_reload_name() where appropriate on the related chain, module, helper, or manager class.
• Scenario: adding a few dozen lines of private logic inside one chain or module. Action: prefer a private function or private method in the same file. Do not create a new helper by default.

6. Code And Comment Requirements

• Preserve the existing code style. Do not introduce a new abstraction layer without a clear payoff.
• The repository already uses short docstrings for many public classes and methods. For new public classes and methods, follow the local style of the surrounding file.
• Comments and docstrings should default to Chinese. If the surrounding file is already consistently in English, match the local style.
• Comments should explain why the code is written that way and what non-obvious constraints exist, such as edge cases, compatibility reasons, call ordering, cache or reload semantics, and external system limitations.
• Do not write line-by-line translation comments. Do not comment obvious assignments, branches, or straightforward calls.
• For complex notes, place the comment above the code block instead of using long end-of-line comments.
• When changing code, update or remove stale comments so the documentation stays aligned with the implementation.
• Do not add TODO or FIXME without context. Only keep one if it is genuinely useful and cannot be addressed as part of the current task.
• Do not add noisy comments like "change starts here", "change ends here", or "this is important".

7. Dependency And Environment Conventions

• Target Python version is 3.11+. Current CI uses Python 3.12.
• The dependency source file is requirements.in.
• requirements.txt is the lock file generated by pip-compile requirements.in. Do not maintain it manually.
• Install dependencies with pip install -r requirements.txt.
• When adding or upgrading dependencies:
  1. Update requirements.in
  2. Run pip-compile requirements.in
  3. Run the relevant tests and security checks

8. Coupled Updates

• When fixing a bug, prefer adding a test that reproduces it. When adding a feature, prefer the smallest useful test coverage.
• When changing CLI behavior, also check and update moviepilot, docs/cli.md, and related tests.
• When changing MCP or REST API behavior, exposed tools, or AI interaction behavior, also check and update docs/mcp-api.md, related skills/*/SKILL.md files or scripts, and related tests.
• When changing development workflow, dependency management, or security-check procedures, also update docs/development-setup.md.
• When changing database structure, add an Alembic migration under database/versions/. Do not update models without a migration.
• When changing user-visible config, defaults, or initialization flow, also check related docs, help text, setup or init flows, and tests.
• When adding a new skill, follow the existing skills/<name>/SKILL.md structure, keep the YAML front matter, and prefer script paths relative to the SKILL.md file.

9. Validation Requirements

• Run at least the tests directly related to the change, for example pytest tests/test_xxx.py.
• If the change affects common modules, startup flow, CLI, or agent runtime behavior, expand the validation scope.
• After Python code changes, at minimum ensure the change does not introduce new error-level issues in pylint app/.
• When changing CLI behavior, validate the relevant help output such as moviepilot help or the specific subcommand help.
• When changing dependencies, also run pip-compile requirements.in and safety check -r requirements.txt --policy-file=safety.policy.yml.
• If the task only changes documentation, explicitly say that tests were not run. Do not claim checks that were not executed.

10. Commit And Release Conventions

• Only create a commit when the user explicitly asks for one.
• Prefer Conventional Commits such as feat: ..., fix: ..., and docs: ....
• This is not just stylistic. The release workflow uses Conventional Commits to categorize changelog entries.
• Do not casually change version numbers, release settings, or Docker release flow unless the task explicitly involves them.

11. Output Requirements

• Result summaries should focus on three things: what changed, how it was validated, and what risks remain.
• Do not write vague summaries. Do not describe unexecuted checks as completed.
• If there is compatibility impact, config migration risk, or user-data risk, call it out explicitly.