docs: restructure AGENTS.md and add docs/rules agent documentation system (#5830)

AGENTS.md

@@ -1,153 +1,103 @@
-# MoviePilot AI Agent Guide
+# AGENTS.md
 
-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.
+This file is the primary instruction set for all AI agents and LLMs working in this repository. Local documentation takes precedence over general training data. You must follow this file and the rule documents it references.
 
-## 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.
+## Task-to-Documentation Mapping
 
-## 2. Working Principles
+Before executing any task, identify the domain and load the corresponding document.
 
-- 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.
+### Architectural Decisions
+* **Primary Reference:** `docs/rules/05-architecture.md`
+* **Required Constraints:** Respect layer boundaries and dependency flow. Do not introduce circular dependencies. Verify the correct layer for any new capability before implementing.
 
-## 3. Key Directories
+### Business Logic and Design Patterns
+* **Primary Reference:** `docs/rules/04-design-patterns.md`
+* **Required Constraints:** Use the project's established Module, Chain, Event, and Oper structural patterns. Do not introduce abstractions the project has not adopted.
 
-- `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/plugins/`: Directory where plugins are installed and managed.
-- `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.
+### Coding Standards and Style
+* **Primary Reference:** `docs/rules/06-code-styles.md`
+* **Required Constraints:** Match the style of the surrounding file. Type annotations, Pydantic models, and async/await usage must all conform to the documented standards.
 
-## 4. Layering And Access Boundaries
+### Identifiers and Naming
+* **Primary Reference:** `docs/rules/07-naming-conventions.md`
+* **Required Constraints:** All filenames, class names, function names, and constants must follow the project's taxonomy. No arbitrary abbreviations or mixed casing styles.
 
-### API / Endpoint Layer
+### Comments and Documentation
+* **Primary Reference:** `docs/rules/08-comment-styles.md`
+* **Required Constraints:** All public classes and methods require Chinese docstrings. Comments must explain the *why*, not restate the code.
+* **⚠️ MANDATORY GATE:** Code that is missing proper Chinese docstrings on public interfaces is **REJECTED** at review. No exceptions.
 
-- 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`.
+### External Communication and Interfaces
+* **Primary Reference:** `docs/rules/09-external-response.md`
+* **Required Constraints:** All third-party HTTP requests must go through `RequestUtils`. Response formats must use the project's standard schemas. Error handling must follow the per-layer conventions.
 
-### Chain Layer
+### Data and Persistence
+* **Primary Reference:** `docs/rules/10-data-and-persistent.md`
+* **Required Constraints:** Any database model change requires a matching Alembic migration. Runtime configuration must be managed via `SystemConfigKey` + `SystemConfigOper`. Raw string keys are forbidden.
 
-- `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.
+### Quality and Security
+* **Primary Reference:** `docs/rules/11-quality-and-security.md`
+* **Required Constraints:** All code changes must pass the relevant pytest tests and pylint checks. Dependency changes require a passing safety scan.
 
-### Module Layer
+### Commands and Development Workflow
+* **Primary Reference:** `docs/rules/03-commands.md`
+* **Required Constraints:** Only suggest or execute commands documented in that file. Do not assume tool defaults or global flags.
 
-- `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
+## Agent Execution Rules
 
-- `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`.
+### Pre-Flight Check
 
-### Preferred Call Directions
+Before generating any code or proposing changes, you must:
 
-- 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`.
+1. Identify the task domain (architecture / business logic / coding style / naming / comments / external interfaces / data / quality).
+2. Load the corresponding document from `docs/rules/`.
+3. Explicitly verify that your proposed solution does not violate the following three mandatory constraints:
+   - **Naming Conventions (07):** Are all files, classes, functions, and constants named correctly?
+   - **Architecture Boundaries (05):** Is the code placed in the correct layer? Are all call directions valid?
+   - **Comment Standards (08):** Do all new public classes and methods include Chinese docstrings?
 
-## 5. Where New Capabilities Should Go
+### Implementation Guidelines
 
-- 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.
+* **Pattern Adherence:** Avoid generic boilerplate. If `04-design-patterns.md` defines a project-level pattern for a scenario, you are required to use it.
+* **Documentation Standards:** Docstring style for any new function or module must match `08-comment-styles.md`.
+* **⚠️ MANDATORY GATE:** Public classes, methods, and functions without proper Chinese docstrings are **REJECTED**. No exceptions.
+* **Command Reliance:** Only suggest commands listed in `03-commands.md`. Do not rely on inferred tool defaults.
+* **Minimal Change Principle:** Prefer the smallest correct change. Do not perform unrelated refactors, mass renames, or formatting-only cleanup.
+* **Output Language:** Summaries, validation results, and risk notes default to Chinese unless the user requests otherwise.
 
-## 6. Code And Comment Requirements
+### Conflict Resolution
 
-- 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".
+If existing code appears to contradict the documentation:
 
-## 7. Dependency And Environment Conventions
+1. Stop implementation immediately.
+2. Identify the specific file and line of the contradiction.
+3. Prompt the user: "The documentation in `[File]` requires Pattern A, but the current implementation uses Pattern B. Which is the current standard?"
 
-- 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
+## Coupled Update Rules
 
-- 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.
+When modifying the following, you must also update the listed artifacts:
 
-## 9. Validation Requirements
+| Changed Content | Must Also Update |
+|---|---|
+| CLI behavior | `moviepilot` entrypoint, `docs/cli.md`, related tests |
+| MCP / REST API, exposed tools | `docs/mcp-api.md`, `skills/*/SKILL.md`, related tests |
+| Dev workflow, dependency management, security checks | `docs/development-setup.md` |
+| Database model schema | New Alembic migration under `database/versions/` |
+| User-visible config or init flow | Related docs, help text, setup/init flows, tests |
+| New skill | Follow `skills/<name>/SKILL.md` structure, keep YAML front matter |
 
-- 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
+## Primary Entry Point
 
-- 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.
+For the full documentation map and cross-references, refer to:
 
-## 11. Output Requirements
+**[Documentation Hub Index](./docs/rules/README.md)**
 
-- 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.
+*Last Updated: 2026-05-25*