MoviePilot v3 架构设计深度解读:分层结构、核心模式与启动生命周期

原创2026-09-22 22:20:522,187 阅读
文章标签:后端工作流自动化任务调度AI AgentMCP 服务AI 技能插件系统认证鉴权人工智能

MoviePilot v3 架构设计深度解读:分层结构、核心模式与启动生命周期

本文基于仓库中的 docs/architecture-overview.md 编写,面向希望深入理解 MoviePilot v3 内部结构的开发人员。全文以架构总览文档为骨架,并结合 app/ 下的实际源码实现进行佐证,帮助读者掌握分层结构、核心包职责、模块间调用关系、典型业务流程与启动生命周期。

导读

MoviePilot 是一个聚焦影视自动化核心流程的系统,实现了订阅、搜索、下载、文件整理、元数据刮削、媒体库刷新与消息通知的全流程自动化。v3 版本以“单向依赖的模块化单体”为目标,通过组合根(Composition Root)、Port/Adapter 依赖倒置、Oper 数据访问层与 AI Agent 子系统重塑了整体架构。读完本文,你将掌握 v3 的六层分层模型、四大核心设计模式(Module / Chain / Event / Oper)、启动生命周期中各项 initializer 的执行顺序,以及架构治理测试如何把边界约束变成机器门禁。


一、系统概述与外部入口

MoviePilot 后端基于 FastAPI,前端基于 Vue 3(独立仓库维护)。系统对外暴露三类访问面:

  • REST API:宿主业务端点统一走 app/api/,使用统一的 Response 响应封装;
  • MCP 工具调用端点:/api/v1/mcp,供外部智能体以 JSON-RPC 方式调用;
  • OpenAI / Anthropic 兼容协议端点:面向 LLM 生态客户端。

此外系统内置 AI Agent,支持以自然语言操控媒体库的订阅、搜索与下载。在 app/factory.py 的 create_app() 中可以看到这些端点的实际装配:openapi.json 挂载在 API_V1_STR 前缀下,MCP 与 OpenAI/Anthropic 兼容路径的错误响应由 _native_ai_error_response() / _mcp_jsonrpc_error_response() 单独按协议原生格式处理,不经过统一的 Response 包装。

从外部视角看,系统的整体拓扑如下图所示(原文 architecture-overview.md 的 system overview 图):

flowchart LR
    subgraph 外部["外部入口"]
        Web["Vue 3 前端"]
        Msg["消息渠道<br/>Telegram / WeChat / Slack ..."]
        ExtAgent["外部智能体<br/>MCP / Skills"]
    end

    subgraph 后端["MoviePilot 后端(FastAPI)"]
        API["REST API / MCP / 兼容协议"]
        Core["核心引擎<br/>Chain / Application / Module / Plugin / Agent"]
        Persist["持久化端口 / Oper"]
    end

    subgraph 外部服务["外部生态"]
        Site["PT 站点 / 索引器"]
        DL["下载器<br/>qBittorrent / Transmission ..."]
        MS["媒体服务器<br/>Emby / Plex / Jellyfin ..."]
        Meta["元数据源<br/>TMDB / Douban / Bangumi ..."]
        LLM["LLM 提供商"]
    end

    DB[("PostgreSQL / SQLite<br/>+ Alembic 迁移")]

    Web -->|HTTP| API
    Msg -->|Webhook / 轮询| Core
    ExtAgent -->|JSON-RPC| API
    API --> Core
    Core -->|通过应用端口 / Oper| Persist
    Persist --> DB
    Core <--> Site
    Core <--> DL
    Core <--> MS
    Core <--> Meta
    Core <--> LLM

外部渠道(Telegram / WeChat / Slack 等)通过 Webhook 或轮询进入核心引擎;外部智能体通过 MCP JSON-RPC 与 API 层交互;核心引擎对外连接 PT 站点、下载器、媒体服务器、元数据源与 LLM 提供商;持久化统一收敛到 PostgreSQL / SQLite,并配套 Alembic 迁移。


二、整体分层架构

2.1 六层职责划分

MoviePilot v3 以单向依赖的模块化单体为目标。历史包 app/core、app/helper、app/utils 已不存在物理目录,仅作为旧插件的虚拟兼容导入根保留(由 app/runtime/compat/ 精确映射)。分层图表达了职责关系与运行时调用方向,不等同于 Python 静态 import 图——通过 Port 注入的调用会与具体 Adapter 的静态依赖方向相反。

flowchart TB
    subgraph 入口层["入口层 Entrypoints"]
        ApiPkg["app/api<br/>REST / MCP 端点"]
        AgentPkg["app/agent<br/>AI Agent 运行时"]
        Monitor["app/monitor<br/>目录监控"]
        Workflow["app/workflow<br/>工作流"]
        Scheduler["app/scheduler/<br/>定时任务职责包"]
        CLI["app/cli<br/>命令行"]
        PluginPkg["插件运行时目录<br/>app/plugins/*(副本/覆盖层)"]
    end

    subgraph 编排层["编排层"]
        Chain["app/chain<br/>Chain 用例编排"]
        App["app/application<br/>聚焦应用服务"]
    end

    subgraph 能力层["能力层"]
        Modules["app/modules<br/>可插拔后端模块"]
        Db["app/db<br/>模型 + Oper 数据访问"]
        Schemas["app/schemas<br/>传输模型与枚举"]
    end

    subgraph 契约层["契约层"]
        Domain["app/domain<br/>纯业务语义"]
        Runtime["app/runtime<br/>进程级运行时契约"]
    end

    subgraph 底层["底层机制"]
        Foundation["app/foundation<br/>无状态原语"]
        Adapters["app/adapters<br/>技术 I/O 适配"]
    end

    subgraph 组合根["组合根 / 边界"]
        Startup["app/startup<br/>Composition Root"]
        Sdk["app/sdk<br/>插件稳定导入面"]
        Compat["app/runtime/compat<br/>旧导入路径与符号映射"]
    end

    ApiPkg --> Chain
    AgentPkg --> App
    Monitor --> Chain
    Workflow --> Chain
    Scheduler --> Chain
    CLI --> Chain
    PluginPkg --> Sdk

    Chain -->|run_module 分发| Modules
    Chain -->|Application service / 命名数据端口| App
    App -->|运行时调用 Protocol / 持久化端口| Db

    Modules --> Domain
    App --> Domain
    App --> Runtime
    Chain --> Runtime
    Domain --> Schemas
    Domain --> Foundation
    Runtime --> Foundation
    Adapters --> Domain
    Adapters --> Foundation
    Startup -->|构造并注入| Adapters

    Startup -.注入/装配.-> Runtime
    Startup -.注入/装配.-> App
    Startup -.注入/装配.-> Modules
    Sdk -.门面转发.-> App
    Compat -.惰性映射.-> Sdk
    Compat -.精确别名.-> App
    Compat -.精确别名.-> Db
    Compat -.精确别名.-> Foundation
    Compat -.精确别名.-> Adapters

各层要点如下:

  • 入口层:API、Agent 运行时、目录监控、工作流、定时任务、CLI 与插件运行时目录,只负责“接收入口信号”,不承载业务实现;
  • 编排层:app/chain/ 承载被多入口共享的用例编排,app/application/ 提供聚焦应用服务(识别、过滤、通知、RSS、站点、下载器等);
  • 能力层:可插拔模块、数据库模型与 Oper、传输模型与枚举;
  • 契约层:app/domain/ 是纯业务语义(媒体上下文、识别解析、站点状态、磁力语义、NFO 刮削),app/runtime/ 是进程级运行契约;
  • 底层机制:app/foundation/ 是零依赖的无状态原语,app/adapters/ 是全部技术 I/O 的具体实现;
  • 组合根与边界:app/startup/ 是唯一组合根,app/sdk/ 是插件稳定导入面,app/runtime/compat/ 负责旧路径的精确映射。

2.2 持久化调用路径

当前正式目标和已完成参考切片的持久化调用路径可概括为:

入口(API / Agent / CLI / Scheduler / Workflow)
        -> Chain 或 Application 用例
        -> 命名 Port / Protocol
        -> db/adapters 创建短生命周期 Session/UoW
        -> db/oper 与 db/models

Chain 的持久化能力由 startup 构造 ChainRuntimeContext 并在 ChainBase 实例化时显式注入;Agent manager、memory、tool 与 scheduler 共享同一个 AgentDataContext。需要跨进程恢复或 commit 后可靠执行的业务副作用进入 app/application/outbox.py 定义的 Outbox 端口,由 app/db/adapters/outbox.py 实现;app/runtime/tasks.py 的 TaskRegistry 只负责进程内任务所有权、取消与有限等待,不承担 durable queue 语义。

2.3 依赖方向规范

原文 architecture-overview.md 给出了完整的依赖方向表,这里节选最核心的规则:

方向 状态
入口层 → Chain / Application / 注入 Port 允许(按工作流复杂度选择;不得直接构造 Oper)
Chain → Module 仅允许通过 run_module 方法名分发,禁止直接 import 模块内部
Chain → Agent 实现 禁止;只能经 app/application/agent.py 门面
Application → Domain / Runtime / 注入的 Port 允许;不得直接依赖具体 DB/Oper/Adapter
DB Adapter → Application 持久化 Protocol / Oper / UoW 允许;这是依赖倒置的实现方向
Module → Module / Chain 禁止(跨模块编排一律进 Chain)
Adapter → Application / runtime.extensions / sdk / compat 禁止
Domain → Runtime / Adapter / Application / DB 禁止
Foundation → 任何其他 app 包 禁止
任何形成模块级循环依赖的 import 禁止(延迟导入也不被接受)

注意:完整宿主 SCC 与 Application/Chain 具体 Adapter 直连已经使用“生成事实 + 人工 policy 门禁”;其余尚未机器化的规则仍按优化清单补齐,不能把表中每一行都理解为当前已经被 CI 全量证明。


三、核心包职责速查

原文给出了一张完整的包职责表,这里保留全部内容并按需补充源码细节:

包 职责 代表性文件
app/foundation/ 无状态、无配置、无 I/O 的底层原语:反射/动态导入、加密、DOM、单例、文本、URL、版本比较 reflection.py、crypto.py、singleton.py
app/domain/ 纯 MoviePilot 业务语义:媒体上下文、识别解析、站点状态解释、磁力语义、NFO 刮削 context.py、metainfo.py、meta/、scraper.py
app/runtime/ 进程级运行机制:配置、进程拓扑、事件、完整日志、缓存契约与内存后端、运行依赖 profile 与原生载荷激活检测、任务所有权、执行/关联上下文、并发、调度、限流、本地化、GC、重启状态 config.py、events.py、event/、dependencies/、tasks.py、execution.py、correlation.py、log.py、cache.py
app/runtime/extensions/ 模块 / 插件 / 配置化服务 / 托管资源的发现、注册与生命周期适配;管理器归入对应主题包,旧插件路径只由 Compat 精确映射 module/manager.py、plugin/manager.py、service.py
app/runtime/compat/ 仅标准库的精确旧模块、包与符号导入路由;不是业务实现,也不是通用 re-export 层 manifest.py、imports.py
app/adapters/network/ 通用 HTTP、浏览器、DNS、Cloudflare、IP 传输机制 http.py、browser.py
app/adapters/cache/ Redis 与文件缓存的具体实现 backends.py、redis.py
app/adapters/system/ OS/文件/进程/stdio/显示/包安装/Rust 加速适配 host.py、resource.py、fsproxy.py
app/adapters/external/ 命名外部生态:插件市场、CookieCloud、OCR、IP 归属、MP Server、微信加密 market.py、server.py、wechat.py
app/adapters/web/ Web 技术适配:动态插件路由注册、认证依赖和 OpenAPI 重建;不承载插件路由用例 plugin/routes.py
app/adapters/observability/ 可选观测技术适配;核心层只依赖 runtime/observability 定义的窄端口 otel.py
app/application/ 读取配置/持久化状态的聚焦应用服务:识别、过滤、通知、RSS、站点、下载器、媒体服务器、存储、整理规则、可靠副作用等;同一主题拆成子包 recognition.py、rules.py、rss.py、outbox.py、site/、subscription/、plugin/
app/application/chain/ Chain 运行时上下文、跨领域数据端口和 durable event 命令;将组合根注入的能力以命名 getter 暴露给 Chain context.py、data.py、events.py
app/application/subscription/ 订阅深度冻结 DTO、typed query/write/staging Repository,以及新增、查询、变更、删除、媒体身份与搜索用例 contract.py、write.py、mutation.py、delete.py、identity.py、search.py
app/application/plugin/ 插件市场、安装、运行时端口、文件夹操作和动态路由用例;具体 FastAPI 路由适配器在 adapters 层 catalog.py、install.py、runtime.py、folders.py、routes.py
app/application/messaging/ 渠道回环入口、消息渲染/路由、命令交互会话、插件按钮回调、Agent 消息桥接 ingress.py、message.py、router.py、agent.py
app/application/security/ 认证、授权、Cookie、Passkey、OTP/二次认证、SSRF 与 URL/路径安全 auth.py、url.py、twofactor.py
app/chain/ 跨入口复用的用例编排:订阅、搜索、下载、整理、媒体、消息等 Chain subscribe/、search.py、transfer/
app/modules/ 可插拔后端:下载器、媒体服务器、元数据源、消息渠道、索引器、存储 qbittorrent/、emby/、telegram/、themoviedb/
app/db/ SQLAlchemy 模型、表级 Oper、会话/UoW 与 Application 持久化适配器;Model 只接受显式 Session,不拥有事务提交 models/、oper/、adapters/、uow.py
app/schemas/ Pydantic 传输模型、枚举(ModuleType、EventType、SystemConfigKey 等) types.py、context.py
app/api/ FastAPI 主端点、鉴权依赖、统一 Response 响应封装;动态插件端点不走此统一包装 apiv1.py、endpoints/、response.py
app/adapters/web/plugin/ FastAPI 动态插件路由的技术适配:注册/移除、认证依赖、OpenAPI 重建;保留插件原生响应结构 routes.py
app/agent/ AI Agent:稳定 Manager 门面、会话/生命周期/后台任务 owner、单 Agent 编排器、运行时、工具、中间件、LLM、记忆、技能、策略 manager.py、session.py、lifecycle.py、tasks.py、orchestrator.py
app/startup/ 唯一组合根:跨层装配、领域初始化、声明式生命周期排序与重启策略 composition/、initializers/、lifecycle/
app/sdk/ 面向新插件的稳定导入面(网络、缓存、日志、浏览器等);_legacy/ 只承载旧插件行为适配薄门面 network.py、browser.py、cache.py、_legacy/
app/monitor/ 源目录监控 → 触发整理 watcher.py、dispatcher.py
app/workflow/ 工作流引擎 —
app/plugins/ 插件运行时副本/覆盖目录,由插件管理器加载;不是官方插件源码或宿主架构实现 —

补充说明:app/runtime/dependencies/ 是一个同名能力包——profile.py 只负责解释器 ABI 对应的依赖组,native.py 只负责已加载原生发行包的快照与变更检测。包根不重复导出实现,宿主直接导入职责子模块;旧的平级 dependencies.py 与 native_dependencies.py 已退出规范实现。


四、启动与生命周期

4.1 组合根与 lifespan 时序

app/startup/ 是全应用唯一的组合根,负责向低层注入依赖、编排初始化/关停顺序、决定重启策略。低层模块不允许反向 import startup。启动时序如下(原文 sequence 图):

sequenceDiagram
    participant Main as app/main.py
    participant Factory as app/factory.py
    participant Life as startup/lifecycle.py
    participant Init as 各 initializer
    participant FastAPI as FastAPI 主循环

    Main->>Factory: 导入并创建 FastAPI 实例
    Factory->>Factory: create_app():异常处理器 / CORS / 本地化中间件
    Factory->>Init: register_api_app(app) 注入插件路由服务
    Factory-->>Life: lifespan 绑定到 app
    Main->>FastAPI: Server.run() 触发 lifespan 启动

    Life->>Life: configure_cache_dependencies()<br/>(必须先于业务模块导入)
    Life->>Life: 显式创建并发布文件日志 writer
    Life->>Init: prepare_database() + revision/head 校验
    Life->>Init: configure_default_user_agent(注入 UA)
    Life->>Init: configure_domain_dependencies(领域层依赖注入)
    Life->>Init: get_engine() / get_global_async_engine() 预热 + fail-fast
    Life->>Init: check_connection_budget() 连接预算核算
    Life->>Init: init_routers(app) 注册 API 路由
    Life->>Init: init_modules()(app/startup/initializers/modules.py)发现并初始化模块,返回 HostRuntime
    Life->>FastAPI: app.state.host_runtime = HostRuntime
    Life->>Life: 显式启动共享消息队列
    Life->>Init: init_plugins() / init_scheduler() / init_monitor()
    Life->>Init: init_command() / init_workflow()
    Life->>Init: replay_pending_transfers()(后台回放未整理文件)
    Life->>Life: 发布 database_ready + lifecycle_ready
    Life->>FastAPI: yield,交还控制权
    Note over Life,FastAPI: 运行期……
    FastAPI->>Life: 收到停止信号
    Life->>Init: 逆序关停:工作流→命令→监控→定时器→插件→消息队列→模块
    Life->>Life: 关闭共享异步 HTTP 连接池
    Life->>Life: 关闭并释放当前 lifespan 的日志 writer

在 app/main.py 中可以看到生产入口的实现:MoviePilotServer 继承 uvicorn.Server,在优雅退出前发布应用协作停止标志(runtime_stop_state.stop_system());run_api_server() 根据 DEV 与 API_WORKERS 决定走 Uvicorn reload / 多 worker(supervisor 模式) 还是 单进程生产模式。而在 app/factory.py 中,create_app() 完成异常处理器、CORS、本地化中间件、ResponseAPIRoute 路由类与插件动态路由服务的装配,并把 lifespan 绑定到 FastAPI 实例。

4.2 关键设计点

原文总结了以下关键设计点,均可在源码中印证:

  • 缓存装配先于业务导入:缓存装饰器会在业务模块 import 时创建后端,因此 configure_cache_dependencies() 在生命周期最顶部执行(对应 initializers/cache.py)。
  • Uvicorn 入口分流:生产单 worker 使用带协作停止语义的 MoviePilotServer;开发 reload 和安全模式多 worker 使用 app.factory:create_app import string/factory,由 supervisor 创建应用实例;app.factory:app 继续保留给既有 ASGI supervisor 和测试使用。
  • 数据库准备唯一入口:建表、迁移、迁移前备份与 Alembic head 校验统一由 lifespan 最早的“数据库准备”组件执行(见 lifecycle/init.py 中的 prepare_database_component()),app.main 不再主动迁移;主程序、外部 supervisor、factory 和 TestClient 因而共享同一 fail-fast 语义。
  • 引擎预热 fail-fast:同步/异步数据库引擎在单线程期完成首次创建,避免调度器放出大量线程后再创建引擎导致连接锁竞争。
  • 类型化请求装配:startup/composition/context.py 的 frozen slots HostRuntime 是 lifespan 内唯一宿主上下文;API、Scheduler、Chain 从 HostRuntime.configuration 获取 frozen 配置快照;startup/composition/runtime.py 是 HostRuntime、全部命名领域 Runtime 与旧 ApiDataPorts 投影的唯一构造/发布 owner;startup/composition/chain.py 集中构造无参 Chain 兼容上下文,并延迟绑定旧 Transfer command 与壁纸 Chain,避免组合根导入环;startup/composition/security.py、network.py、agent.py 分别统一装配认证、网络应用端口与 Agent 数据对象。
  • 安全模式:MOVIEPILOT_SAFE_MODE 会跳过插件、定时器、监控器、命令与工作流,用于故障自救。
  • Scheduler 同名职责包:旧 app/scheduler.py 单体已退役,拆分为 catalog.py(作业目录和计划投影)、execution.py、bridge.py、progress.py、registry.py、reconcile.py 与 lifecycle.py;startup/initializers/scheduler.py 构造业务 Chain 一次,组成 frozen SchedulerServices 后注入。
  • 进程拓扑:全功能 V3 强制 API_WORKERS=1,避免每个 worker 重复启动插件和后台控制面;安全模式可临时使用多 worker 诊断,但不是正式扩容方案。app.main 中的 validate_process_topology() 会拒绝“reload 与多 worker 同时启用”的非法组合。
  • 健康语义:/health/live 只确认进程和事件循环可响应;/health/ready 仅在数据库到达当前 head 且生命周期完成后返回 200,启动失败或关停阶段返回 503;两者不公开路径、revision、插件和异常详情。
  • 关停隔离:每个关停步骤由 run_shutdown_step 独立捕获异常,保证后续资源仍有机会释放;TaskRegistry、事件投递屏障、插件和模块资源按生命周期清单中的 owner 顺序收口。

五、核心设计模式

5.1 Module 模式:可插拔后端

app/modules/ 下每个目录是一个可插拔后端(下载器、媒体服务器、消息渠道、元数据源、索引器、存储等),均继承 _ModuleBase 并实现统一契约:

flowchart LR
    subgraph 契约["_ModuleBase 契约"]
        A["get_name / get_type / get_subtype"]
        B["init_setting():返回控制开关的配置项"]
        C["init_module():初始化"]
        D["test():连通性测试"]
        E["stop():停止"]
    end

    MM["ModuleManager<br/>(发现 + 注册 + 生命周期)"]
    MM -->|扫描 app/modules/* 一级子包| M1["qbittorrent"]
    MM --> M2["transmission"]
    MM --> M3["emby / plex / jellyfin"]
    MM --> M4["telegram / wechat / slack ..."]
    MM --> M5["themoviedb / douban / bangumi ..."]
    MM --> M6["indexer / subtitle / filter ..."]

要点:

  • 模块由 runtime/extensions/module/manager.py 发现并管理生命周期;app/modules/_base/ 承载各模块族的共享模板基类(下载器、媒体服务器、消息渠道)。
  • 模块开关由 init_setting() 声明的配置项决定(如 DOWNLOADER = "qbittorrent")。
  • 模块之间、模块到 Chain 的直接依赖被禁止,跨模块编排一律由 Chain 完成。
  • 渠道/存储的管理操作遵循统一契约:channel_manage(channel, action, **params) / storage_manage(storage, action, **params),结果统一为 {"success", "message", "data"} 形态,Chain 与端点只做透传。

5.2 Chain 模式:用例编排

app/chain/ 承载被 API、CLI、Agent、调度器、Webhook 等多入口共享的业务用例。所有 Chain 继承 ChainBase,Chain 访问模块只能通过方法名分发。在源码 app/chain/base.py 中可以看到 run_module() 的实际实现——它委托给 _module_dispatcher.dispatch();run_module_strict() 传播 provider 异常;async_run_module() 支持同步/异步方法混合调用:

flowchart TB
    Entry["API / CLI / Agent / 调度器 / Webhook"]
    C["SearchChain / SubscribeChain /<br/>DownloadChain / TransferChain ..."]
    Base["ChainBase<br/>run_module / async_run_module"]
    MM["ModuleManager 分发"]
    P["插件模块(同名方法优先)"]
    M1["模块 A"]
    M2["模块 B"]

    Entry --> C --> Base
    Base -->|先查询插件实现| P
    Base --> MM
    MM --> M1
    MM --> M2
  • run_module("method_name", **kwargs) 会遍历所有实现了该方法的模块并聚合结果;插件若实现了同名方法可获得优先响应。
  • runtime/extensions/module/contracts.py 为宿主已观察到的方法提供显式参数与返回合同;兼容期只诊断旧插件签名差异,不改变插件优先级、短路和自由返回语义。
  • 大型稳定 Chain 使用同名目录包治理:包根只保留稳定公开类,Facade 只组合职责 owner;TransferChain、SubscribeChain、DownloadChain 与 SearchChain 的旧单体文件均不得复活或以 source.py 留存;搜索状态由 application/search/state.py 唯一拥有。
  • app/chain/ 中下划线前缀文件(_recognition.py、_messaging.py、_interaction.py、_music.py、_transfer.py)是 ChainBase 的功能域 Mixin,不是独立 Chain。
  • 需要斜杠命令交互的 Chain 继承 InteractionChainMixin,只实现 _interaction_handler。

5.3 Event 模式:跨切面事件

EventManager(app/runtime/events.py)提供进程级事件总线,用于解耦跨切面反应(整理完成后刷新媒体库、配置变更后重载模块、消息分发等)。宿主内建 EventType / ChainEventType 均在事件注册表中绑定 typed payload;开放插件事件允许额外字段,校验只生成诊断,分发给既有插件的仍是原始 dict/model 对象,不改变事件 ABI。

插件可通过 app.sdk.events 调用 event.snapshot() 或 snapshot_event_data(event_type, event_data) 获取独立的类型化快照。快照的 raw 保留原始对象,payload 是组合契约,链式事件还提供 input / output 快照;known、valid 和 errors 分别用于处理未知自定义事件和兼容期校验失败。快照修改不会回写原事件,如需拦截、取消或替换链式结果,插件仍应修改原始 event.event_data。示例用法:

from app.sdk.events import snapshot_event_data

snapshot = snapshot_event_data(event.event_type, event.event_data)
if snapshot.valid and snapshot.payload.context.media_info.type == "音乐":
    music_type = snapshot.payload.context.media_info.music_type

事件分发时序如下:

sequenceDiagram
    participant T as TransferChain
    participant EM as EventManager
    participant MS as MediaServerChain
    participant N as NotificationChain
    participant PL as 插件(注册了同一事件)

    T->>EM: send_event(EventType.TransferComplete, data)
    EM->>MS: on_transfer_complete(event)
    EM->>N: on_transfer_complete(event)
    EM->>PL: on_transfer_complete(event)
    Note over EM: 处理器通过 @eventmanager.register(EventType.X) 注册<br/>事件类型集中在 schemas.types.EventType

事件治理是数字化的:生产者与消费者共用 scripts/architecture/event_facts.py 这一份逐调用事实源,生成的 runtime-contract-baseline.json 保存 line-free 事实、数量和枚举索引;人工维护的 runtime-contract-policy.json 只批准 consumer 的精确 fingerprint、owner 和理由,--write-host 不会改写该 policy。

5.4 Oper 模式:数据访问层

数据库读写一律通过 app/db/oper/ 下的 Oper 类,禁止在 Chain / Module / 端点中直接写 SQLAlchemy 查询。models/ 与 oper/ 按文件一一镜像(站点族聚合于 oper/site.py 等少数例外)。

flowchart LR
    Entry["API / Scheduler / Agent<br/>逻辑操作入口"]
    Command["Application Command<br/>事务所有者"]
    UoW["app/db/uow.py<br/>commit / rollback"]
    Oper["app/db/oper/*.py<br/>SubscribeOper / TransferHistoryOper ..."]
    Models["app/db/models/*.py<br/>SQLAlchemy 模型"]
    Engine["app/db/engine.py<br/>同步 + 异步引擎"]
    DB[("PostgreSQL / SQLite")]

    Entry --> Command --> Oper --> Models --> Engine --> DB
    Entry --> UoW --> Engine
    Command -.提交或回滚.-> UoW
    Command -.commit 后副作用.-> Effects["Event / Scheduler / Report"]
    Models -.before_insert/before_update.-> Norm["_identity.py<br/>media_source/media_id 归一化"]

核心约束:

  • Oper 只接收和返回持久化值;MediaInfo / MetaBase 与数据库行之间的转换属于业务逻辑,归 app/application/(见 application/subscription/write.py、application/history/)。
  • 规范写入口中的 Oper 只 stage mutation,不创建独立 Session、不提交;Application Command 通过请求或任务入口注入的 UnitOfWork 统一 commit/rollback,事件、刷新和上报只在 commit 成功后执行。例如订阅新增链路:application/subscription/write.py 决定事务与 post-commit 边界,SubscribeOper.stage_add() 只查重、add 和 flush,db/adapters/subscription.py 创建独占 Session。
  • Outbox 可靠副作用:业务行与 durable intent 在同一 Session/UoW 中提交;提交后由 Outbox dispatcher 依据 topic、claim/lease、有限重试和 dead-letter 执行。完成通知、事件和统计的 post-commit 逻辑必须保持幂等,不能用普通线程或 TaskRegistry 代替持久 intent。终态历史随统一数据维护任务分批清理,默认成功记录保留 30 天、dead letter 保留 90 天。
  • 统一历史保留期:所有可安全按时间回收的追加型数据均受 DATA_CLEANUP_ENABLE 控制;transferpending 和 plugininstallation 承担恢复语义,禁止按年龄删除。
  • 每次表结构变更必须新增 database/versions/ 下的 Alembic 迁移。
  • 运行期业务配置使用 SystemConfigKey 枚举 + SystemConfigOper,禁止裸字符串键;用户级配置使用 UserConfigOper。

5.5 其他横切模式

模式 说明
Config Reload 继承 ConfigReloadMixin 并声明 CONFIG_WATCH,配置变更时自动重建长生命周期对象(如下载器客户端重连)
Singleton EventManager、ModuleManager、PluginManager 等全局共享管理器继承 foundation/singleton.py 的 Singleton
Managed Resource 可选进程级技术资源(浏览器、虚拟显示等)以 data-only capability.toml 声明,runtime/extensions 解释生命周期,startup 构建 Runtime,消费者经 runtime/resources.py 显式获取;插件使用浏览器走 app.sdk.browser
Observability runtime/observability 定义低基数指标和默认 no-op 端口,Startup 可选装配 OTel;HTTP、DB、Event、Module、Scheduler、插件生命周期和 Agent 只提交白名单标签

六、典型业务调用流程

6.1 搜索 → 过滤 → 下载

sequenceDiagram
    participant E as 入口(API / 消息命令 / Agent / 订阅)
    participant SC as SearchChain
    participant MC as MediaChain
    participant TC as TorrentsChain(索引)
    participant FC as 过滤(application/filter + rules)
    participant DC as DownloadChain
    participant MOD as run_module 分发

    E->>SC: search(title)
    SC->>MC: 识别与媒体信息补全(TMDB/Douban 模块)
    SC->>TC: 检索站点资源(indexer 模块 / 站点插件)
    TC->>MOD: search_torrents(...)
    SC->>FC: 按规则组过滤与排序
    SC->>DC: download(torrent)
    DC->>MOD: download_torrent(...)(下载器模块)
    DC-->>E: 返回下载结果 / 发送通知事件

6.2 订阅全流程

flowchart TB
    A["用户创建订阅<br/>API / 消息 / Agent"] --> B["SubscribeChain<br/>写入订阅(application/subscription/write.py)"]
    B --> C{"调度器周期触发<br/>SubscribeChain.process"}
    C --> D["搜索缺失集数<br/>(复用搜索流程)"]
    D --> E{"命中资源?"}
    E -->|是| F["DownloadChain 下载"]
    F --> G["TransferChain 整理入库"]
    G --> H["刷新媒体库 + 发送通知"]
    H --> I{"订阅是否完结?"}
    I -->|否| C
    I -->|是| J["标记完成 / 发送完成通知"]

订阅生命周期的完整细节可参考 docs/subscribe-lifecycle.md。

6.3 文件整理(Transfer)与监控

sequenceDiagram
    participant W as app/monitor 目录监控
    participant T as TransferChain
    participant R as 识别(domain/metainfo + application/recognition)
    participant FS as adapters/system(文件操作)
    participant SC as ScrapingChain(刮削)
    participant EM as EventManager

    W->>T: 发现新文件,触发整理
    T->>R: 解析名称/路径得到 MetaBase
    T->>R: 匹配媒体(MediaChain)
    T->>FS: 按目录配置转移/重命名
    T->>SC: 生成 NFO / 图片刮削(domain/scraper)
    T->>EM: send_event(TransferComplete)
    Note over EM: 媒体服务器刷新、通知、<br/>插件等订阅方各自响应

启动时 replay_pending_transfers()(initializers/transfer.py)会在后台线程回放上次未整理完的文件,保证崩溃恢复。

6.4 消息命令交互

flowchart LR
    CH["消息渠道模块<br/>telegram / wechat / slack ..."] --> MP["MessageProcessingMixin<br/>(ChainBase)"]
    MP --> RT["application/messaging/router.py<br/>统一优先级与回调分发"]
    RT --> CMD["Command 命令注册表<br/>(application/commands.py 门面)"]
    RT --> IT["InteractionChainMixin<br/>斜杠命令 / 按钮回调"]
    RT --> PLG["插件输入接管<br/>(messaging/plugin.py)"]
    RT --> AG["Agent 会话<br/>(messaging/agent.py → application/agent.py)"]
    CMD --> Chain["对应业务 Chain"]
    IT --> Chain

app/application/messaging/ 负责渠道回环入口(ingress.py)、消息渲染、模板、队列(message.py)、交互会话与视图;业务工作流仍由对应 Chain 执行(如媒体交互的业务部分在 MediaInteractionChain)。该包不作为推荐给插件直接使用的公开 SDK。


七、AI Agent 子系统

Agent 采用门面 + 惰性物化设计,避免 application → agent 形成静态依赖边:

flowchart TB
    Entry["消息渠道 / API / MCP"] --> Facade["app/application/agent.py<br/>编排门面(get_agent_manager 等)"]
    Reg["app/startup/initializers/agent.py<br/>生命周期显式注册/重置 Provider"]
    Reg --> Facade
    Facade -.能力启用或首次使用时物化.-> RT["app/agent/loader.py<br/>能力发现与服务物化"]
    RT --> Manager["app/agent/manager.py<br/>稳定 AgentManager 门面"]
    Manager --> Session["session.py / lifecycle.py<br/>会话队列与有界生命周期"]
    Manager --> Tasks["tasks.py<br/>后台、调度与心跳任务"]
    Session --> ORC["orchestrator.py<br/>单 MoviePilotAgent 执行"]
    Tasks --> Session
    ORC --> Tools["app/agent/tools<br/>系统工具(经 application 门面)"]
    ORC --> LLM["app/agent/llm<br/>LLM 提供商管理"]
    ORC --> MW["middleware / policy / memory / skills"]

约束要点:

  • Chain 访问 Agent 运行时只能经 app/application/agent.py(源码中可见 get_agent_manager() 门面,见 application/agent.py);app/chain/agent.py 的 AgentChain 是链层入口,Agent 实现保持在 app/agent/。
  • app.agent.AgentManager 是插件稳定路径,精确解析到 app/agent/manager.py;宿主直接导入 owner,包根不得通配转发 orchestrator.py 的任意内部名称。
  • app.agent.llm 包根不承载实现或动态通配导出;宿主直接导入 llm/helper.py、llm/capability.py、llm/auth.py、llm/provider.py 等 owner。旧 app.agent.llm.LLMHelper 由 Compat 精确叠加,app.helper.llm 直接映射到 canonical llm/helper.py。
  • 官方插件使用的 MoviePilotTool 与 moviepilot_tool_manager 继续由 agent/tools/base.py、agent/tools/manager.py 原位拥有。
  • Agent 工具不直接 import API / 调度器 / 命令:插件动态路由与文件夹操作使用 application/plugin/routes.py、application/plugin/folders.py,调度和命令分别使用 application/scheduling.py、application/commands.py。
  • 对外暴露 MCP 端点 /api/v1/mcp 与 OpenAI / Anthropic 兼容端点,错误响应在 app/factory.py 中按协议原生格式单独处理(不走统一 Response 包装)。

复杂任务的计划、工具发现和中断恢复说明见 Agent 复杂任务执行与恢复。


八、插件系统与 SDK / 兼容边界

flowchart TB
    subgraph 插件侧
        P["app/plugins/*<br/>(运行时副本/覆盖层)"]
    end

    subgraph 宿主边界
        SDK["app/sdk<br/>新插件稳定导入面<br/>network / cache / logging / browser ..."]
        Compat["app/runtime/compat<br/>manifest 精确模块/符号映射<br/>app.core / app.helper / app.utils / app.log 及已删除旧路径"]
        PM["PluginManager<br/>发现 / 生命周期 / 事件桥接"]
    end

    subgraph 规范实现
        Canonical["foundation / domain / runtime /<br/>application / adapters / chain ..."]
    end

    P -->|新插件推荐| SDK
    P -->|旧插件(DEBUG 下告警)| Compat
    SDK -->|门面转发| Canonical
    Compat -.惰性解析.-> SDK
    Compat -.惰性解析.-> Canonical
    PM -->|run_plugin 方法分发 / 事件广播| P
    Canonical -.-|禁止 import| Compat
    Canonical -.-|禁止 import| SDK

要点:

  • app/plugins/ 是运行时插件副本,不是官方插件仓库的源码副本;它不纳入宿主架构拆分的源代码审计。宿主代码只使用 canonical 路径;只有运行时插件与兼容性测试可用旧路径。
  • compat 只存字符串映射并惰性解析,不得在模块导入期急切 import canonical 实现;canonical 包也不得为兼容而反向 import compat / sdk。
  • 插件 API 的动态注册/移除及端口协议统一位于 app/application/plugin/routes.py,FastAPI 技术实现位于 app/adapters/web/plugin/routes.py;FastAPI 实例由组合根(app/factory.py)在创建后注入,端点层禁止直接依赖 factory。
  • 动态插件路由使用原生 APIRoute,插件自行决定返回结构;主程序的统一 Response 封装只适用于 app/api/ 的宿主端点。插件若已经自行返回 Response、字典、列表或其它可序列化值,宿主不再二次包裹。
  • app/runtime/extensions/plugin/manager.py 是 canonical 管理器 owner。旧插件仍从 app.core.plugin 或 app.sdk.plugins 进入,并由 Compat 精确路由到同一个 PluginManager 身份;新入口是 app.sdk.plugin.manager。
  • app/sdk/plugin/base.py 是插件契约基类 _PluginBase 与 PluginChain 的 owner。app.plugins._PluginBase 与历史拼写 app.plugins.PluginChian 由 Compat 精确叠加承接。
  • 插件可参与 run_module 方法分发(同名方法优先响应)并注册事件处理器。

九、运行时基础设施

9.1 runtime 与 adapters 的分工

flowchart LR
    subgraph runtime["app/runtime(契约 + 内存行为)"]
        RC["config.py<br/>Settings / 部署配置"]
        RE["events.py<br/>事件总线"]
        RL["log.py<br/>日志运行时(依赖叶子)"]
        RCA["cache.py<br/>缓存协议 / 内存后端 / 装饰器"]
        MR["resources.py<br/>托管资源门面"]
    end

    subgraph adapters["app/adapters(具体 I/O)"]
        AC["cache/backends.py<br/>Redis / 文件缓存"]
        AN["network/http.py<br/>同步 + 异步 HTTP 客户端"]
        AB["network/browser.py<br/>浏览器会话"]
        AS["system/*<br/>OS / 文件 / 进程 / Rust"]
        AE["external/*<br/>市场 / OCR / MP Server"]
    end

    Startup["app/startup<br/>启动期注册具体缓存工厂"]
    Startup --> RCA
    Startup --> AC

    Caller["上层调用方"] -->|装饰器/协议| RCA
    RCA -.可切换后端.-> AC
    Caller --> AN
    Caller --> AB
  • 第三方 HTTP 的 transport 实现必须走 RequestUtils(app/adapters/network/http.py);这不授权 Application/Chain 直接导入具体 Adapter,插件使用 app.sdk.network。
  • app/runtime/log.py 是依赖叶子(无任何 app.* 导入);foundation 不输出运行日志,由上层所有者决定是否记录。
  • 缓存契约与内存后端在 runtime/cache.py,Redis/文件实现在 adapters/cache/backends.py,由 startup 在被装饰的业务模块导入前完成工厂注册。

9.2 数据与配置总览

类别 载体 说明
持久化业务数据 app/db/models + Alembic 每次 schema 变更必须配套迁移
运行期业务配置 SystemConfigKey + SystemConfigOper 用户可编辑、跨重启持久
用户级配置 UserConfigOper 按 user_id 隔离
部署配置 runtime/config.py 的 Settings 环境变量 / app.env
缓存 runtime/cache.py 装饰器 Redis 或文件后端可切换
站点资源 app/application/site/sites.* 生成的站点目录、认证与索引能力数据包

十、架构治理

架构边界中的核心子集已经由测试强制执行,其余目标不能只停留在文档约定。主要测试与工具:

  • tests/test_architecture_dependencies.py 构建完整 Python 模块图,拒绝:物理遗留源码、禁止的上向依赖、SDK/compat 反向引用、包含迁移模块的强连通分量、模块间/模块到 Chain 的 import、入口层对 app.modules 内部的 import、Chain 直接 import 模块内部(必须走 run_module 分发)、app/chain 内的下载器 SDK 依赖。
  • tests/fixtures/architecture/dependency-baseline.json 记录生成事实;人工审查的 SCC 分类单独存入 dependency-policy.json。完整宿主 SCC 必须精确匹配 policy,新增、扩大、变形和陈旧 policy 都失败;--write-host 不会替代人工决策。
  • 同一 baseline 的 direct_adapter_imports 记录现存原始直连;Application 与 Chain 均已清零,policy 目标为空集合。
  • direct_egress 记录全宿主 53 条 raw transport、network SDK 和协议操作 identity;普通 HTTP/Session bridge 与 Application DNS I/O 债务已清零。每条初始边的指纹由测试独立冻结,bindings/uses 变化、分类互换、通配导入和初始边增长都会失败;--write-host 不会改写人工 policy 或冻结上界。
  • event_facts 是生产者/消费者唯一收集源;CI 将语义 policy 与生成快照分成独立步骤,前者不能通过刷新后者绕过。
  • 任何所有权迁移必须同步更新:canonical 导入、app/runtime/compat/manifest.py、SDK 导出(若公开)、docs/rules/05-architecture.md 与上述架构测试。
  • 延迟导入不被接受为隐藏循环依赖的手段。

10.1 当前收口状态

以下数字来自 tests/fixtures/architecture/(排除 app/plugins/**),更新基线前必须先审查语义变化:

指标 当前值
Python 模块 1044
内部导入边 8,867
非平凡 SCC 1(精确 containment 的 TMDB 移植包环)
Application / Chain 具体 Adapter 直连 0 / 0
Direct egress 53(债务已清零,53 条精确 containment)
Module Contract V2 spec 215(其中 211 个进入 run_module 观察面)
Event Contract 53
Event producer / consumer 86(85 静态、1 动态)/ 17(16 静态、1 动态)
Model/Oper 自动事务与自建 Session 0
组合根外 SystemConfigOper() 0

本总览与本轮架构治理的关系:

  • 已完成的宿主边界:旧 app.core / app.helper / app.utils / app.log 根路径通过 app/runtime/compat/manifest.py 精确映射;订阅、历史、用户认证等旧 Oper 入口通过 app/sdk/_legacy/ 薄门面保留行为兼容。
  • 已完成的插件边界:插件 API 的动态路由由 application 端口 + web adapter 组成,使用原生 APIRoute 保留插件响应;插件管理器归入 runtime/extensions/plugin/manager.py。
  • 已完成的主题收口:订阅 DTO/Port 归入 app/application/subscription/contract.py,用例写入归入 app/application/subscription/write.py,SQLAlchemy 实现只在 app/db/adapters/subscription.py;插件动态路由与文件夹操作归入 app/application/plugin/routes.py、folders.py。原 app/application/subscribe.py、app/application/plugins.py 未形成插件 ABI,已直接删除。
  • 已完成的运行时可靠性收口:已迁移的主干后台任务由 TaskRegistry 或领域 lifecycle owner 管理;durable-required 事件和订阅关键副作用经 app/application/outbox.py 与 app/db/adapters/outbox.py 进入同事务 Outbox。
  • Scheduler 已从单体迁入 app.scheduler 同名职责包,startup 是业务 callable 的唯一构造与注入边界。

判断是否需要新增 manifest 映射的标准:只有当旧物理模块被删除、改名或公开符号迁移时才登记;物理文件仍是稳定入口的,不应为了目录规整新增"自己映射自己"的别名,也不应在 canonical 包中保留多余导出。

当前架构问题、优先级、分阶段实施步骤与验收门禁见 docs/refactor/optimization-checklist.md。


附录:相关文档索引

文档 内容
docs/rules/01-project-overview.md 系统目标与业务范围
docs/rules/02-tech-stack.md 技术栈与第三方集成
docs/rules/04-design-patterns.md Module / Chain / Event / Oper 等模式细则
docs/rules/05-architecture.md 层边界、依赖方向与关键文件位置(权威)
docs/rules/09-external-response.md 外部 HTTP 约定与统一响应格式
docs/rules/10-data-and-persistent.md 数据模型、迁移与缓存规范
docs/subscribe-lifecycle.md 订阅生命周期详解
docs/mcp-api.md MCP 工具端点说明
docs/refactor/optimization-checklist.md 当前架构差距、优先级与可执行优化清单
docs/refactor/refactor-roadmap.md 多级 Goal、叶子依赖、清零条件与交付状态
docs/v3t-runtime-governance.md V3/V3t 运行依赖、故障恢复、GIL 可观测性与兼容退场门禁
docs/adr/0007-background-action-reliability.md 后台动作 E0–E3 可靠性分级与完成语义决策

结语

MoviePilot v3 架构的核心价值在于把"约定"变成"可验证的事实":分层边界由模块图测试强制、依赖方向由 SCC policy 精确准入、事件与持久化副作用由逐调用事实源与 Outbox 机制治理、旧插件兼容由 manifest 精确路由。理解这套架构,不仅能帮助你快速定位某个业务能力在哪个包、由哪个 owner 实现,更能让你在贡献代码或开发插件时遵循同样的边界纪律——而这正是 v3 重构最重要的遗产。

登录后查看全文
MoviePilot