docs: update AGENTS.md to clarify repository structure and guidelines

AGENTS.md

@@ -6,104 +6,147 @@
 
 - 本仓库是 MoviePilot 的后端、CLI、MCP/API、Docker 与 AI skills 仓库。
 - 后端基于 FastAPI，主要代码位于 `app/`。
-- 前端源码不在本仓库，前端源仓库是 `MoviePilot-Frontend`；本仓库中的 `public/` 仅视为前端构建产物目录。
-- 本仓库还包含：
-  - 本地 CLI 入口：`moviepilot`
-  - 数据库迁移：`database/versions/`
-  - 测试：`tests/`
-  - 开发与接口文档：`docs/`
-  - AI skills：`skills/`
+- 前端源码不在本仓库，前端源仓库是 `MoviePilot-Frontend`；
+- 本仓库还包含本地 CLI、数据库迁移、开发文档、测试、Docker 相关脚本与 AI skills。
 
 ## 2. 工作原则
 
 - 先阅读相关实现、测试和文档，再修改代码；不要凭目录名猜行为。
 - 采用最小正确改动，优先复用现有函数、模式与命名。
 - 不做与当前任务无关的大规模重构、批量重命名或样式清扫。
+- 新增抽象前先判断是否真的会被复用；能放在现有函数、现有类、现有链路中的，不要额外拆层。
 - 工作区可能存在用户未提交修改；不要回滚、覆盖或整理你未理解的内容。
 - 默认使用中文输出结论、验证结果和风险说明。
 
 ## 3. 关键目录说明
 
-- `app/`：后端业务代码与启动流程，运行入口为 `app/main.py`
-- `moviepilot`：本地 CLI 启动脚本与帮助文本
-- `database/versions/`：Alembic 迁移脚本
-- `docs/`：CLI、MCP、开发流程等文档
-- `docker/`：镜像构建与容器启动脚本
-- `skills/`：可供 AI agent 使用的 skills 定义和脚本
-- `tests/`：pytest 测试与少量手动测试脚本
-- `config/`、`.moviepilot.env`、`*.db`：本地配置或运行数据，除非用户明确要求，否则不要修改或提交
+- `app/api/endpoints/`：HTTP 接口入口，处理鉴权、参数、响应和少量简单 CRUD。
+- `app/chain/`：业务编排层，承接搜索、识别、订阅、下载、消息交互等用例。
+- `app/modules/`：动态加载的系统模块层，封装下载器、媒体服务器、消息渠道及其他可插拔能力。
+- `app/helper/`：可复用的低层辅助逻辑，不承载完整业务编排。
+- `app/core/config.py`：环境变量、部署参数、启动级配置。
+- `app/schemas/types.py`：`SystemConfigKey`、模块类型、枚举等共享类型定义。
+- `app/db/`：数据库模型、会话和 `*_oper.py` 数据访问封装。
+- `moviepilot`：本地 CLI 入口与帮助文本。
+- `database/versions/`：Alembic 迁移脚本。
+- `docs/`：CLI、MCP/API、开发流程等文档。
+- `skills/`：可供 AI agent 使用的 skills 定义和脚本。
+- `tests/`：pytest 测试与少量手动测试脚本。
+- `config/`、`.moviepilot.env`、`*.db`：本地配置或运行数据，除非用户明确要求，否则不要修改或提交。
 
-## 4. 不要手工修改的内容
+## 4. 分层与访问边界
 
-- `__pycache__/`、`.mypy_cache/`、`.ruff_cache/`、`venv/`、`.runtime/`、`build/`、`dist/`
-- Cython 或平台相关编译产物，例如 `app/helper/sites.cpython-*.so`
-- 本地数据库、日志、缓存、cookie、token、环境文件
-- `version.py`，除非任务明确是发版、对齐版本或用户明确要求修改版本号
-- `public/` 中的构建产物，除非任务明确是更新前端发布资源
+### API / Endpoint 层
 
-说明：`setup.py` 会编译 `app/**/*.py`（排除 `app/main.py`），普通后端改动通常不需要同步重建二进制产物，除非任务明确要求交付编译结果。
+- endpoint 只处理 HTTP 相关内容：鉴权、参数解析、响应模型、流式输出适配、简单输入校验。
+- 简单列表、详情、开关读写、纯 CRUD 型接口，可以直接调用 `app/db/` 或已有 `helper`。
+- 涉及跨模块调度、事件发送、缓存、搜索识别下载联动、复杂业务判断时，应该下沉到 `chain` 层。
+- 新增接口优先放进现有领域文件；只有出现新的顶层资源域时，才新增 endpoint 文件。
+- 新增 endpoint 后要同步注册到 `app/api/apiv1.py`。
 
-## 5. 依赖与环境约定
+### Chain 层
 
-- 目标 Python 版本为 `3.11+`；当前 CI 使用 Python `3.12`
-- 依赖源文件是 `requirements.in`
-- `requirements.txt` 是通过 `pip-compile requirements.in` 生成的锁定文件，不要手工维护内容
-- 安装依赖使用：`pip install -r requirements.txt`
+- `chain` 是业务编排层，服务于 API、CLI、消息交互、agent、调度器等多个入口。
+- `chain` 负责组合 `module`、`helper`、`db`、事件、缓存和其它稳定的 `chain` 能力。
+- 在 `chain` 内优先通过 `run_module()` / `async_run_module()` 触发模块能力；只有确实需要枚举模块、取实例、做健康检查时，再直接使用 `ModuleManager` 或相关 helper。
+- `chain` 应聚焦用例与流程，不应承载底层协议细节、HTTP 请求对象或页面参数拼装细节。
+- 新增 `chain` 前先判断：这是不是一个会被多个入口复用的业务用例，或者需要协调多个模块/多种资源。如果只是单个 endpoint 的短逻辑，不要新建 `chain`。
+- `chain` 之间可以复用，但要避免新增环依赖。
+
+### Module 层
+
+- `module` 是可插拔能力实现层，通过 `ModuleManager` 动态发现和加载。
+- 适合放在 `module` 的内容：新下载器、新媒体服务器、新消息渠道、新识别/过滤/文件管理类系统能力，或任何需要启停、优先级、配置开关、独立测试的实现。
+- 新增 `module` 时，应遵循现有基类约定，实现或对齐 `init_module()`、`init_setting()`、`get_name()`、`get_type()`、`get_subtype()`、`get_priority()`、`test()`、`stop()` 等接口。
+- `module` 应聚焦单一后端或单一能力实现，返回领域结果，不返回 HTTP 响应，不感知 endpoint、鉴权或 FastAPI 请求对象。
+- `chain -> module` 是主路径。仓库中存在少量历史性的 `module -> chain` 反向依赖；新增代码不要继续扩大这种模式。若模块也需要复用一段业务判断，优先上移到 `chain` 或下沉到 `helper`。
+- 不要新增 `module -> module` 的直接耦合；多模块协同应由 `chain` 组织。
+
+### Helper 层
+
+- `helper` 适合承载可复用的低层支撑逻辑，例如路径处理、配置聚合、站点索引读取、协议客户端包装、限流、缓存辅助、页面解析等。
+- 只有当逻辑会被多处复用，或本身就是一个独立的低层问题时，才新增 `helper`。
+- 如果逻辑只在一个 `chain` 或一个 `module` 内使用，优先留在原文件中，避免把 `helper` 变成杂物箱。
+- 如果一段代码已经需要配置开关、运行时装载、优先级、独立测试入口或多实现分发，它更像 `module`，而不是 `helper`。
+- `helper` 不应演变为新的业务编排层；完整业务流程仍应放在 `chain`。
+
+### 推荐调用方向
+
+- 首选方向：`endpoint/CLI/agent/command -> chain -> module/helper/db`
+- 允许方向：`chain -> chain`，前提是复用稳定领域能力且不引入环依赖。
+- 谨慎方向：`endpoint -> db/model/oper/helper`，仅限简单查询、简单 CRUD 或输入校正。
+- 避免方向：`module -> chain`、`module -> module`、`helper -> chain`、`helper -> endpoint`。
+
+## 5. 新增能力如何落点
+
+- 场景：新增一个搜索、识别、订阅、下载、消息交互之类的业务流程。
+  处理：优先放到 `app/chain/`，让 API、CLI、agent 或调度器复用同一套编排逻辑。
+- 场景：新增一个下载器、媒体服务器、消息渠道或其他可插拔后端接入。
+  处理：放到 `app/modules/`；如涉及新的模块类别或子类型，同步检查 `app/schemas/types.py` 与相关 schema。
+- 场景：新增一个对外 HTTP API。
+  处理：放到 `app/api/endpoints/`，注册 `app/api/apiv1.py`，补齐鉴权、schema、文档和测试；复杂逻辑下沉到 `chain`。
+- 场景：新增一个低层通用工具、解析器、配置读取器或协议包装。
+  处理：放到 `app/helper/`；前提是它不是一次性逻辑，也不是完整业务用例。
+- 场景：新增一个部署级、环境级、启动前确定的配置项，例如端口、路径、代理、开关、密钥、第三方服务地址。
+  处理：放到 `app/core/config.py` 的 `ConfigModel` / `Settings`。
+- 场景：新增一个运行时业务配置、用户可编辑规则、系统持久化选项。
+  处理：优先使用 `SystemConfigKey` + `SystemConfigOper`，不要散落裸字符串 key。
+- 场景：配置变更后需要自动重载长生命周期对象。
+  处理：在对应 `chain`、`module`、`helper` 或管理类上补 `CONFIG_WATCH`、`on_config_changed()`、必要时补 `get_reload_name()`。
+- 场景：只是在一个 `chain`/`module` 内多出几十行私有逻辑。
+  处理：优先提炼为当前文件内的私有函数或私有方法，不要默认新建 `helper`。
+
+## 6. 代码与注释要求
+
+- 保持现有代码风格，不引入没有明确收益的新抽象层。
+- 仓库当前风格中，大量类和方法使用简短 docstring；新增公开类、公开方法时，优先沿用所在文件的现有风格。
+- 注释和 docstring 默认使用中文，若文件周边已经稳定使用英文，则与周边保持一致。
+- 注释要解释“为什么这样做”以及“不直观的约束”，例如边界条件、兼容性原因、调用顺序、缓存/重载语义、外部系统限制。
+- 不要写逐行翻译式注释，不要解释显而易见的赋值、分支或简单调用。
+- 复杂注释优先写在代码块之前，避免长篇行尾注释。
+- 修改代码时，同步更新或删除已经过时的注释；不要留下与实现不一致的说明。
+- 不要加入无上下文的 TODO/FIXME；只有在当前任务无法一并处理、且这条备注对后续维护确实有帮助时才保留。
+- 不要添加“修改开始/修改结束”“这里很重要”之类没有信息密度的注释。
+
+## 7. 依赖与环境约定
+
+- 目标 Python 版本为 `3.11+`；当前 CI 使用 Python `3.12`。
+- 依赖源文件是 `requirements.in`。
+- `requirements.txt` 是通过 `pip-compile requirements.in` 生成的锁定文件，不要手工维护内容。
+- 安装依赖使用：`pip install -r requirements.txt`。
 - 新增或升级依赖时：
   1. 先修改 `requirements.in`
   2. 再执行 `pip-compile requirements.in`
   3. 最后补跑相关测试与安全检查
 
-## 6. 代码与文档修改规则
+## 8. 联动修改规则
 
-- 保持现有代码风格，不引入没有明确收益的新抽象层。
-- 注释保持克制，只解释不直观的逻辑或边界条件。
 - 修复 bug 时，优先补一个能复现问题的测试；新增功能时，优先补最小覆盖测试。
-- 变更 CLI 行为时，同时检查并更新：
-  - `moviepilot`
-  - `docs/cli.md`
-  - 相关测试
-- 变更 MCP/REST API、工具暴露或 AI 交互行为时，同时检查并更新：
-  - `docs/mcp-api.md`
-  - `skills/` 中相关 `SKILL.md` 或脚本
-  - 相关测试
-- 变更开发流程、依赖管理或安全检查方式时，同时更新 `docs/development-setup.md`
-- 涉及数据库结构变化时，补充 `database/versions/` 迁移脚本；不要只改模型不改迁移
+- 变更 CLI 行为时，同时检查并更新：`moviepilot`、`docs/cli.md`、相关测试。
+- 变更 MCP/REST API、工具暴露或 AI 交互行为时，同时检查并更新：`docs/mcp-api.md`、相关 `skills/*/SKILL.md` 或脚本、相关测试。
+- 变更开发流程、依赖管理或安全检查方式时，同时更新 `docs/development-setup.md`。
+- 涉及数据库结构变化时，补充 `database/versions/` 迁移脚本；不要只改模型不改迁移。
+- 变更用户可见配置、默认值或初始化流程时，同时检查相关文档、帮助文本、setup/init 流程和测试。
+- 新增 skill 时，遵循现有 `skills/<name>/SKILL.md` 结构，保留 YAML front matter，并优先使用相对 `SKILL.md` 的脚本路径描述。
 
-## 7. Skills 相关约定
+## 9. 验证要求
 
-- 新增 skill 时，遵循现有 `skills/<name>/SKILL.md` 结构，保留 YAML front matter（如 `name`、`version`、`description`）。
-- skill 内引用脚本时，优先使用相对 `SKILL.md` 的路径描述。
-- 如果 skill 对应的 CLI/API 行为变化，必须同步更新 skill 文档，避免文档与实际能力脱节。
+- 至少运行与当前改动直接相关的测试，例如：`pytest tests/test_xxx.py`。
+- 影响公共模块、初始化流程、CLI 或 agent 运行时时，扩大测试范围。
+- Python 代码改动后，至少确认不会为 `pylint app/` 引入新的错误级问题。
+- 变更 CLI 时，至少验证相关帮助输出，例如：`moviepilot help` 或对应子命令帮助。
+- 变更依赖时，补跑：`pip-compile requirements.in` 与 `safety check -r requirements.txt --policy-file=safety.policy.yml`。
+- 如果本次只修改文档，明确说明未运行测试即可；不要伪造验证结果。
 
-## 8. 验证要求
-
-- 至少运行与当前改动直接相关的测试，例如：`pytest tests/test_xxx.py`
-- 影响公共模块、初始化流程、CLI 或 agent 运行时时，扩大测试范围
-- Python 代码改动后，至少确认不会为 `pylint app/` 引入新的错误级问题
-- 变更 CLI 时，至少验证相关帮助输出，例如：`moviepilot help` 或对应子命令帮助
-- 变更依赖时，补跑：
-  - `pip-compile requirements.in`
-  - `safety check -r requirements.txt --policy-file=safety.policy.yml`
-
-如果本次只修改文档，说明未运行测试即可；不要伪造验证结果。
-
-## 9. 提交与发布约定
+## 10. 提交与发布约定
 
 - 只有在用户明确要求提交时才创建 commit。
-- commit message 优先使用 Conventional Commits，例如：`feat: ...`、`fix: ...`、`docs: ...`
+- commit message 优先使用 Conventional Commits，例如：`feat: ...`、`fix: ...`、`docs: ...`。
 - 这样做不是形式要求；仓库的发布流水线会按 Conventional Commits 生成 changelog 分类。
 - 不要顺手修改版本号、发布配置或 Docker 发布流程，除非任务明确涉及这些内容。
 
-## 10. 常见任务提示
-
-- 新增 API 或工具：同时检查路由、鉴权、schema、文档、测试
-- 新增 CLI 子命令：同时检查帮助文本、参数解析、文档、测试
-- 新增数据库字段：同时检查模型、迁移、默认值与兼容路径
-- 新增 agent/LLM 能力：同时检查 `skills/`、MCP/API 暴露、提示词行为与交互测试
-
 ## 11. 输出要求
 
-- 结果说明聚焦三件事：改了什么、怎么验证的、还有什么风险
-- 不写空泛总结，不把未执行的检查写成“已完成”
-- 若发现兼容性影响、配置迁移风险或用户数据风险，必须明确指出
+- 结果说明聚焦三件事：改了什么、怎么验证的、还有什么风险。
+- 不写空泛总结，不把未执行的检查写成“已完成”。
+- 若发现兼容性影响、配置迁移风险或用户数据风险，必须明确指出。