chore(architecture): establish trusted refactor baseline

app/chain/media.py

@@ -1231,9 +1231,9 @@ class MediaChain(ChainBase, metaclass=Singleton):
         indexed_tracks = list(enumerate(tracks))
         by_title: dict[str, list[int]] = {}
         for index, track in indexed_tracks:
-            key = cls._music_track_title_key(track.title)
-            if key:
-                by_title.setdefault(key, []).append(index)
+            title_key = cls._music_track_title_key(track.title)
+            if title_key:
+                by_title.setdefault(title_key, []).append(index)
 
         pending: list[tuple[Path, MetaMusic]] = []
         for file, meta in zip(files, metas):
@@ -1266,9 +1266,9 @@ class MediaChain(ChainBase, metaclass=Singleton):
                 ).append(index)
         unresolved: list[tuple[Path, MetaMusic]] = []
         for file, meta in pending:
-            key = (meta.disc_number or 1, meta.track_number or 0)
+            position_key = (meta.disc_number or 1, meta.track_number or 0)
             candidates = [
-                index for index in by_position.get(key, [])
+                index for index in by_position.get(position_key, [])
                 if index not in used
             ] if meta.track_number else []
             if candidates:

docs/architecture-optimization-checklist.md

@@ -0,0 +1,659 @@
+# MoviePilot V3 架构优化清单
+
+> 审计日期：2026-08-26
+>
+> 审计基线：`v3@9053db926d20`，与 `origin/v3` 一致
+>
+> 文档性质：当前源码的差距清单与分阶段执行说明，不是历史重构结项账本
+
+## 1. 结论摘要
+
+MoviePilot V3 已经形成较清晰的模块化单体：`foundation`、`domain`、`runtime`、
+`adapters`、`application`、`chain`、`db`、`startup`、`sdk` 和 `compat` 的一级所有权
+基本成立。旧物理兼容目录、Model/Oper 自建 Session/提交和直接跨层 DB 依赖等历史问题已有
+硬门禁；门禁还能证明可识别的 TaskRegistry 调用已经声明稳定 owner。
+
+当前主要问题不再是“目录没有分层”，而是以下四类更深层的债务：
+
+1. **边界有形、合同偏弱**：部分 Application Port 仍是 `Callable[[], Any]`，返回 ORM 或
+   动态代理；生产路径因此继续依赖无 Session Oper、全局 provider 和隐式构造。
+2. **用例编排过度集中**：Chain、Scheduler、Plugin、Agent、LLM 和部分 API 文件同时承担决策、
+   I/O、状态、生命周期与兼容职责，私有长方法又处于复杂度门禁盲区。
+3. **可靠性声明强于实现**：整理 pending 目前只能做最小重放，尚不满足 ADR 中声明的 E3
+   状态机语义；部分 commit 后副作用仍存在“业务已提交但调用方收到失败”或进程退出后丢失的窗口。
+4. **治理事实源不一致**：架构规则、总览、AST 基线和 CI 语义存在漂移；快照门禁能证明“没有变化”，
+   但不能自动证明依赖合理、没有新环或所有运行资源都有生命周期 owner。
+
+当前唯一 P0 是主线 `mypy` ratchet 已失败。后续架构优化应先恢复主线，再按可靠性、边界类型化、
+生命周期、复杂度的顺序推进；不建议再做一次大规模目录搬迁。
+
+## 2. 范围与证据边界
+
+### 2.1 本次范围
+
+- 宿主源码 `app/**`，架构统计排除运行时插件副本 `app/plugins/**`。
+- 架构、质量、测试与 CI 门禁，以及当前规则文档之间的一致性。
+- 插件只审查 SDK、Compat、稳定 ABI 和宿主边界，不把官方插件仓代码混入宿主统计。
+- 数据持久化、后台动作完成语义、进程生命周期和外部传输边界。
+
+### 2.2 审计方法
+
+- 读取当前规则、总览、ADR、关键调用链和组合根。
+- 检查依赖图、SCC、Module/Event Contract、事务/configuration 基线。
+- 对文件、类、方法长度及类型/覆盖率治理范围做静态统计。
+- 运行架构、复杂度、异步阻塞、TaskRegistry owner、service locator、Ruff 和 mypy ratchet。
+- 运行 9 个架构/质量专项测试文件，共 `158 passed`。
+
+本次没有运行完整测试套件，也没有用生产流量做动态剖析。因此，清单中的性能收益和低频并发故障
+仍需在对应实施阶段通过专项故障注入、全量测试和运行指标确认。
+
+## 3. 当前架构画像
+
+### 3.1 分层现状
+
+| 层/区域 | 已形成的正确边界 | 当前主要缺口 |
+|---|---|---|
+| `foundation` | 无状态、无配置、无 I/O 的底层机制 | 当前未发现需要重做的结构性问题 |
+| `domain` | 已与 DB、Application、Adapter 保持单向隔离 | `domain/context.py` 等核心对象过大，来源投影与领域模型仍集中 |
+| `runtime` | 已有任务、事件、缓存、托管资源和停止合同 | 导入/构造时启动线程；`global_vars` 仍混合停止、主循环和 WebPush 状态 |
+| `adapters` | 技术与命名外部生态已有明确目录 | Application/Chain 仍直接识别部分具体 Adapter；例外规则没有形式化 |
+| `application` | 已有命令、Port、Outbox 和安全能力 | 部分 Port 是 `Any` 服务定位器，ORM/具体 Adapter 仍会穿透边界 |
+| `chain` | 多入口复用的用例编排与 Module 动态分发已稳定 | God object、私有长方法、包根 SCC、无参构造和资源物化过重 |
+| `db/oper` | Model/Oper 已不自建 Session、不自行提交 | 无 Session Facade 仍被宿主组合根注入，业务操作可能拆成多个事务 |
+| `db/adapters` | 已有显式 Session/UoW 的参考切片 | Port 返回类型不够稳定；Outbox 的 stage 与自提交 dispatcher store 混在一个类型 |
+| `startup` | 已是 HostRuntime 和生命周期组合根 | `initializers/modules.py` 高扇出，仍有导入期 provider 注册和具体对象目录装配 |
+| API/Command/Scheduler | 多数入口已转向 Chain/Application | Agent/System/Plugin 等入口仍承担较多业务与 I/O 编排 |
+| `sdk`/`compat` | 精确映射、稳定插件 ABI 和宿主 canonical 路径已落地 | SDK 仍暴露部分可变全局对象/具体 Manager，只能渐进收窄，不能直接删除 |
+
+### 3.2 量化快照
+
+| 指标 | 当前值 | 解释 |
+|---|---:|---|
+| 宿主 Python 模块 / 内部依赖边 | 835 / 6,810 | `dependency-baseline.json` 当前快照 |
+| 非平凡 SCC | 2 | 新增 Chain 包根环；另一个是隔离的 29 模块 TMDB 移植包环 |
+| 跨层 DB 边界债务 | 0 | Application、Chain、API、Agent、Runtime、Workflow 到 DB 的受控债务均为零 |
+| Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 |
+| Module Contract | 215 specs / 214 methods / 264 calls | 动态方法名为 0；仍有 50 个结果形状为 `ANY` |
+| Event Contract | 53 | 均已有 payload model，但当前全部是 diagnostic enforcement |
+| Python 源码量 | 约 271,400 行 | 60 个文件超过 1,000 行，14 个超过 2,000 行 |
+| 长方法 | 281 个超过 80 行 | 67 个超过 150 行，23 个超过 250 行；大量是私有方法 |
+| 全量 mypy 历史债务 | 11,983 / 601 文件 | strict frontier 当前只覆盖 41 个文件，且 ratchet 已新增 2 个错误 |
+| Ruff 历史诊断 | 973 | 低水位门禁通过，但规则集只覆盖 `E4/E7/E9/F/I` |
+| 覆盖率低水位 | Application 77.76%，Domain 79.24% | Chain、Runtime、Agent、Adapter、Startup 未进入包级覆盖率门禁 |
+
+### 3.3 热点文件
+
+| 文件 | 行数 | 主要职责混合 |
+|---|---:|---|
+| `app/chain/subscribe.py` | 3,895 | 搜索、匹配、状态、刷新、规则引用、通知和交互 |
+| `app/agent/orchestrator.py` | 3,678 | 会话、运行、流式输出、工具、任务与 Manager |
+| `app/agent/llm/provider.py` | 3,528 | provider 目录、认证、模型发现、配置和运行时构建 |
+| `app/adapters/external/market.py` | 3,488 | 插件市场、包下载、依赖、备份恢复、健康和兼容入口 |
+| `app/chain/transfer.py` | 3,250 | 队列、恢复、规划、执行、历史、通知和清理 |
+| `app/chain/search.py` | 2,970 | 搜索计划、并发 fan-out、状态、分页和结果处理 |
+| `app/api/endpoints/agent.py` | 2,346 | HTTP/SSE、文件/音频、Agent 会话和事件编排 |
+| `app/chain/download.py` | 2,230 | 选择、提交、历史、通知、模块后处理和批量执行 |
+| `app/chain/media.py` | 2,191 | 识别、来源投影、缓存、音乐匹配和兼容入口 |
+| `app/scheduler.py` | 2,111 | 作业目录、执行状态、恢复、生命周期和领域任务 |
+
+热点不是按行数机械拆文件的依据。只有在提取出稳定合同、保留旧入口委托并有行为测试时，拆分才算
+降低复杂度；把长方法原样移动到新目录不算完成。
+
+## 4. 优化清单总表
+
+状态含义：`阻塞` 表示当前门禁已失败；`待执行` 表示尚未开始；`渐进` 表示应按触碰路径逐步收敛。
+
+| ID | 优先级 | 状态 | 事项 | 目标结果 |
+|---|---|---|---|---|
+| ARCH-001 | P0 | 阻塞 | 恢复 mypy ratchet | 主线所有既有 CI gate 重新通过 |
+| ARCH-101 | P1 | 待执行 | 统一规则、总览、基线和语义门禁 | 文档声明与机器拒绝条件一一对应 |
+| ARCH-102 | P1 | 待执行 | 将 Transfer pending 升级为真实 E3 状态机 | 崩溃窗口可判定恢复，结果未知时进入人工确认 |
+| ARCH-103 | P1 | 待执行 | 类型化 Chain/Agent 数据 Port 与 DTO | 宿主主路径不再注入无 Session Oper，不向入口泄漏 ORM |
+| ARCH-104 | P1 | 待执行 | 收口跨多次写入的业务事务 | 站点/规则引用清理可整体回滚或幂等恢复 |
+| ARCH-105 | P1 | 待执行 | 明确 post-commit 与 Outbox 完成语义 | “业务已提交、后置效果 pending”可被调用方正确识别 |
+| ARCH-106 | P1 | 待执行 | 让线程/队列/日志 writer 由 bootstrap/lifecycle 显式构造 | 导入或普通 Chain 构造不再启动进程资源 |
+| ARCH-107 | P1 | 待执行 | 消除 Chain SCC，强化循环门禁 | SCC 只剩精确豁免的 TMDB 移植包环 |
+| ARCH-108 | P1 | 待执行 | 决策并收口 Application/Chain 到 Adapter 与 HTTP 边界 | 依赖倒置有明确例外、低水位和迁移顺序 |
+| ARCH-109 | P1 | 待执行 | 按用例拆分超大 Chain、Scheduler 和厚 API | 稳定 Facade 保留，决策/I/O/状态/生命周期各有 owner |
+| ARCH-110 | P1 | 待执行 | Module/Event Contract 分可信级执行 | 宿主 provider 严格，第三方插件仍兼容诊断 |
+| ARCH-111 | P1 | 待执行 | 升级复杂度、类型、覆盖率和并发原语门禁 | 高风险私有路径也进入只降不增的治理面 |
+| ARCH-201 | P2 | 渐进 | 收窄 PluginHelper/PluginManager 与 SDK 暴露面 | ABI Facade 只委托，构造和具体服务归组合根 |
+| ARCH-202 | P2 | 渐进 | 拆分 Agent/LLM provider 职责 | provider catalog、发现、认证、会话和运行时分离 |
+| ARCH-203 | P2 | 渐进 | 拆分 Domain 投影与 Startup 高扇出目录 | 保留 canonical 类型和生命周期顺序，降低修改扩散 |
+| ARCH-204 | P2 | 渐进 | 合并重复 sync/async 核心逻辑并转换存量测试风格 | 保留双 ABI 外壳，共享纯业务核心 |
+
+## 5. P0：先恢复主线
+
+### ARCH-001 恢复 mypy ratchet
+
+**问题与证据**
+
+- `app/chain/media.py:1233` 把局部变量 `key` 推断为 `str`，`1269` 又赋值为
+  `tuple[int, int]`，随后 `1271` 触发 `dict.get` overload 错误。
+- 当前 ratchet 报告：`[assignment] 15 -> 16`，并新增 `[call-overload] x1`。
+- `.github/workflows/test.yml:71-72` 在主 CI 中执行该门禁。
+
+**执行要求**
+
+- [ ] 将标题键和位置键使用不同、带语义的变量名，修复真实类型错误。
+- [ ] 不得用 `mypy_ratchet.py --write` 接受增长。
+- [ ] 保留音乐专辑“精确标题优先、碟号/曲序回退”的现有行为。
+
+**验收**
+
+```bash
+.venv/bin/python scripts/architecture/mypy_ratchet.py
+.venv/bin/python -m pytest tests/test_music_album_match.py -q
+```
+
+## 6. P1：结构性问题
+
+### ARCH-101 统一架构事实源
+
+**问题与证据**
+
+- `docs/rules/04-design-patterns.md:125-131` 仍示范 `SubscribeOper()` 无 Session 调用，
+  与 `docs/rules/10-data-and-persistent.md:111-132` 的生产路径显式 UoW 规则冲突。
+- `docs/rules/05-architecture.md:507` 禁止 `application -> concrete adapter`，但同一文档
+  `177-183` 又要求 RSS 消费 network adapter；当前测试没有形式化这类例外。
+- 规则 `docs/rules/05-architecture.md:516` 禁止任意模块级环，实际 SCC 测试只覆盖特定根。
+- 架构总览此前仍记录 811 模块、6,572 条边和 1 个 SCC，已经落后于当前基线。
+- Event consumer 扫描把任意名为 `.register()` 的调用都当成事件注册，存在明确误报。
+
+**目标与步骤**
+
+- [ ] 指定一个机器可读事实源，文档指标由 fixture 生成或只保留不易漂移的语义描述。
+- [ ] 修正 Oper 示例，分别展示宿主显式 UoW 与插件兼容 Facade。
+- [ ] 对 Adapter 规则作出明确决策：允许哪些通用技术机制，哪些命名外部/持久化能力必须注入。
+- [ ] 让 SCC 规则、精确 allowlist 和文档声明一致。
+- [ ] Event 扫描只识别 EventManager 实例/别名和事件装饰器。
+- [ ] CI 分开报告“快照一致”与“语义规则通过”，禁止把前者表述为架构完全正确。
+
+**验收**
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_architecture_dependencies.py \
+  tests/test_architecture_contract_baseline.py \
+  tests/test_architecture_baseline_cli.py -q
+.venv/bin/python scripts/architecture/baseline.py --check-host --diagnostics
+```
+
+### ARCH-102 将 Transfer pending 升级为真实 E3 状态机
+
+**问题与证据**
+
+- `app/application/transfer.py:139-145` 当前先把任务接受到内存结构，再执行持久登记回调。
+- `app/chain/transfer.py:1012-1024` 吞掉登记失败并继续执行；
+  `tests/test_transfer_pending_replay.py:62-71` 固化了这一 fail-open 行为。
+- worker 未知异常最终也会在 `app/chain/transfer.py:1107-1113,1262-1272` 删除 pending。
+- `app/db/models/transferpending.py:9-34` 只有 `storage/src_path/created_at`，没有目标、模式、
+  step、lease、attempt、last_error，无法判定“文件已移动、历史未提交”等中间态。
+- 这与 `docs/adr/0007-background-action-reliability.md:123-139` 对 E3 的稳定身份、步骤状态、
+  lease/heartbeat 和人工恢复要求不一致。
+
+**目标与步骤**
+
+- [ ] 先在独立持久事务中 commit pending，再尝试放入内存队列；数据库事务不能与 `queue.Queue`
+  原子提交，入队失败时必须保留 pending 供重放。
+- [ ] 初始登记保存稳定源身份、模式、状态和 attempt/lease；目标在规划完成后以 planning checkpoint
+  更新，不能要求任务刚入队时已经具备尚未计算的目标路径。
+- [ ] 设计幂等文件操作和历史提交；只有所有必要步骤达到持久终态后才能删除记录。
+- [ ] 在持久状态机与现有失败历史/AI retry 之间指定唯一 retry owner，定义旧记录迁移和兼容规则。
+- [ ] E3 失败使用持久 `failed/manual_review`、最后稳定 checkpoint 和补偿边界，不直接套用 E2
+  Outbox 的 dead-letter 语义；禁止按年龄通用清理 pending。
+- [ ] 数据模型变更必须配套 Alembic migration，并验证升级与降级路径。
+
+**故障注入验收**
+
+- [ ] 登记后、内存入队前崩溃，重启可继续。
+- [ ] 持久登记成功但内存入队失败，重启可继续。
+- [ ] 文件移动后、历史提交前崩溃，在支持稳定身份/幂等操作的存储上不重复移动且可补齐历史。
+- [ ] worker 未知异常和 lease 超时后保留可诊断状态。
+- [ ] 重复回放、重复消息和人工重试都保持幂等。
+- [ ] 外部存储返回结果未知时进入 `manual_review`，不得伪装成 exactly-once 成功。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_transfer_pending_replay.py \
+  tests/test_transfer_worker_lifecycle.py \
+  tests/test_chain_durable_events.py -q
+```
+
+### ARCH-103 类型化 Chain/Agent Port 与 DTO
+
+**问题与证据**
+
+- `app/application/chain/data.py:14-29,134-176` 的 Oper factory 和 getter 基本都是 `Any`；
+  `app/application/agentdata.py:91-120` 还通过 `__dict__.update()` 动态组装端口。
+- `app/startup/initializers/modules.py:848-863,896-910` 仍向生产 Chain/Agent 注入多个无 Session Oper。
+- 无 Session Oper 会为单次调用独立创建事务；一个业务操作的“查询后更新”可能被拆成多个事务。
+- Workflow query 和 Chain/Agent raw data port 仍返回 `Any`/ORM，Subscription mutation 内部也消费 ORM，
+  因而存在 Session 生命周期外 detached/lazy-load 的潜在风险。公开 Subscription、Site、History
+  QueryService 已经投影 DTO，属于完成项，不应重做。
+
+**目标与步骤**
+
+- [ ] 按领域定义 Query/Command Protocol，不再使用通用 `OperFactory = Callable[[], Any]`。
+- [ ] 写 Port 由 `db/adapters` 创建单操作 Session/UoW；Oper 的 canonical 写方法只 stage/flush，
+  读取方法仍可在调用方 Session 中查询。
+- [ ] 查询 Port 在 adapter Session 内映射为冻结 DTO/Projection，Application 和 API 不接收 ORM。
+- [ ] `ChainDataPorts`/`AgentDataPorts` 可暂时保留为兼容聚合器，但字段必须显式、可类型检查。
+- [ ] 以一个业务纵切面迁移并验证后，再迁移下一组，禁止一次替换所有 Oper。
+- [ ] 增加 AST 门禁，禁止向 `ChainDataPorts`、`AgentDataPorts` 和新的 canonical use-case service
+  注入裸 Oper；SystemConfig singleton、legacy transaction runner 等兼容边界使用精确 allowlist。
+
+**首批建议**
+
+1. Workflow query DTO。
+2. Chain/Agent 的 Subscribe/History/User/Site raw port。
+3. Subscription mutation 与站点、规则组引用更新。
+4. Agent 数据能力。
+
+**验收**
+
+- 关闭 adapter Session 后序列化 DTO，确认不会触发 lazy load。
+- 对迁移的 Application Port 运行 strict mypy，并验证 API response contract 与插件 ABI。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_db_workflow_queries.py \
+  tests/test_agent_data_ports.py \
+  tests/test_subscription_query_service.py \
+  tests/test_site_query_service.py \
+  tests/test_history_query.py -q
+.venv/bin/mypy --config-file mypy.ini
+```
+
+### ARCH-104 收口跨多次写入的业务事务
+
+**问题与证据**
+
+- `app/chain/subscribe.py:3010-3047` 删除站点引用时先写 SystemConfig，再逐条更新订阅。
+- `app/chain/subscribe.py:3073-3110` 清理规则组时依次更新多项配置和多条订阅。
+- 当前无 Session Facade 让这些步骤各自提交；中途失败可能长期残留部分状态，直至同一事件再次触发
+  或人工修复。处理本身具备一定幂等性，但触发事件不是 durable owner。
+
+**目标与步骤**
+
+- [ ] 将引用分析与修改计划提取为纯函数/值对象。
+- [ ] SystemConfig 与 Subscribe 位于同一宿主数据库，首选一个 Application Command/UoW 和批量原子更新；
+  复用 `SystemConfigOper.update_atomically()` 的锁行能力，而不是预设必须跨存储补偿。
+- [ ] 同一 UoW 内修改配置表后，在 commit 成功时一次性发布全部进程内配置快照，并明确
+  `_write_lock`/`_snapshot_lock` 的顺序；读者只能观察完整旧快照或完整新快照。
+- [ ] 仅当未来确有无法共享事务的外部状态时，才使用持久、幂等、带 checkpoint 的 reconciliation job。
+- [ ] 每一步允许安全重试，返回明确的完成/待恢复状态。
+- [ ] 在第 `k` 次写入注入异常，验证整体回滚或下次能恢复到完整状态。
+- [ ] 增加并发触发和并发读取测试，验证没有丢更新、死锁或配置中间组合。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_site_mutation_command.py \
+  tests/test_subscription_mutation_outbox.py \
+  tests/test_rule_group_media.py -q
+```
+
+### ARCH-105 明确 post-commit 与 Outbox 完成语义
+
+**问题与证据**
+
+- `app/application/outbox.py:167-192` 在业务提交后直接执行 `after_commit()`、即时 publish 和完成标记；
+  某一步抛错时，调用方可能收到失败，但业务行和 intent 已经提交。
+- 通用 `DurableEventCommand` commit 后没有先调用已经定义的 `claim_by_event_key()`；dispatcher 可在
+  commit 与请求线程即时 publish 之间先 claim 并投递，随后请求线程再次 publish，形成双发窗口。
+  `app/application/subscription/complete.py:111-145` 已提供先 claim 的正确参考。
+- 下载历史及事件 intent 已原子提交；通知在 commit 后同步执行，模块后处理和字幕再投进线程池。
+  进程在提交与这些动作完成之间退出时，未持久化的动作不会自动恢复。
+- `SqlAlchemyOutboxRepository` 同时提供不提交的 `stage()` 和内部自提交的 dispatcher 方法，
+  事务所有权没有由类型清楚表达。
+
+**目标与步骤**
+
+- [ ] Command 返回结构化结果：业务是否提交、哪些后置效果完成、哪些处于 pending。
+- [ ] commit 后先取得 delivery lease；未取得时跳过请求线程直投，确保与 dispatcher 排他。
+- [ ] 每个 post-commit effect 使用独立 intent 隔离和结算，避免效果 A 失败导致效果 B 被一起重放。
+  单个外部效果仍是 at-least-once，必须有稳定幂等键和幂等 handler/消费者。
+- [ ] 按完成承诺、可重建性、外部不可逆性和业务重要性划分 E0-E3；用户可见性只是因素之一。
+- [ ] 拆分 `OutboxStager` 与 `OutboxDispatchStore`，避免业务 Session 调用自提交方法。
+- [ ] 在 commit、claim、publish、complete、通知和任务提交各断点注入异常/崩溃，验证声明等级与实际恢复一致。
+- [ ] 增加请求线程即时投递与 dispatcher 并发竞争测试，以及“外部调用成功、complete 前崩溃”的重放测试。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_outbox.py \
+  tests/test_chain_durable_events.py \
+  tests/test_subscription_completion_command.py \
+  tests/test_subscription_mutation_outbox.py -q
+```
+
+### ARCH-106 让进程资源由 bootstrap/lifecycle 显式构造
+
+**问题与证据**
+
+- 导入 `app.runtime.config` 会构造日志 handler，并启动 `LogBatchWriter` 线程；普通 import 已有副作用。
+- `ChainBase.__init__` 无条件构造消息队列 manager，任意一个 Chain 都可能启动消息线程。
+- `global_vars` 同时承担停止兼容、WebPush 订阅和主事件循环 owner，多层代码直接消费。
+- 当前 TaskRegistry 门禁只检查 Registry 调用是否带 owner，不会扫描全部原生 `create_task`、
+  `Thread`、`Timer`、`Executor`。
+- 当前 service locator 门禁只覆盖 scheduler/module/plugin/command/workflow 五类 concrete runtime，
+  没有覆盖 `global_vars`，门禁通过不能证明全局状态已经收口。
+- Workflow、Scheduler、Command、Agent initializer 仍有导入期 provider 注册；需要明确这是兼容设计，
+  还是迁入显式装配阶段并提供 test reset，不能长期处于未声明状态。
+
+**目标与步骤**
+
+- [ ] 日志 writer、消息队列及其他长生命周期资源由 bootstrap/lifecycle 显式构造、发布和关闭。
+  现有关闭路径已能收口部分资源，当前要修的是隐式创建权，而不是重新发明 owner。
+- [ ] startup 唯一创建/启动资源；Chain 只接收无生命周期的发送 Port。
+- [ ] 普通模块 import 和构造 `MediaChain` 等非消息用例不得新增线程。
+- [ ] 将 WebPush registry、主循环 execution gateway 和停止状态拆给各自 owner。
+- [ ] 保留 `global_vars` 作为兼容薄门面，但禁止 canonical 宿主新增依赖。
+- [ ] 将 initializer 的 provider 注册迁入显式 `configure_runtime_ports` 装配阶段并提供测试 reset；
+  若某项必须保留导入期兼容行为，需精确记录调用者、原因和退场条件。
+- [ ] 建立原生并发原语清单：结构化局部等待、TaskRegistry、显式生命周期 owner 或受限上下文；
+  未分类的新原语由 ratchet 拒绝。
+
+**验收**
+
+- 隔离进程冷导入前后比较线程名。
+- 正常模式和 safe mode 均验证启动顺序、有限关闭、超时保留 owner 和重试关闭。
+- 运行消息、Scheduler、Workflow、Agent、Plugin 和 lifecycle 专项测试。
+- 在 startup 到达 `yield` 前失败时，已经创建的日志/队列资源也必须收口。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_lifecycle_shutdown.py \
+  tests/test_module_lifecycle.py \
+  tests/test_system_notification_dispatch.py \
+  tests/test_scheduler_lifecycle.py \
+  tests/test_workflow_execution.py \
+  tests/test_agent_lifecycle.py \
+  tests/test_plugin_lifecycle_coordinator.py -q
+```
+
+### ARCH-107 消除 Chain SCC 并强化循环门禁
+
+**问题与证据**
+
+- 当前新增 SCC 为 `app.chain -> app.chain._messaging/_recognition -> app.chain`。
+- `app/chain/__init__.py` 同时是 1,000 行以上的 `ChainBase` 实现和插件/宿主导入入口，
+  又在包初始化时导入 mixin。
+- `baseline.py --check-host` 会确认该 SCC 与 fixture 一致，但现有语义测试没有拒绝 Chain 包内环。
+
+**目标与步骤**
+
+- [ ] 将 canonical `ChainBase` 实现移到 `app/chain/base.py`。
+- [ ] 宿主全部改用 `app.chain.base.ChainBase`；包根不得 eager re-export，否则父包与子模块仍形成 SCC。
+- [ ] 若 `from app.chain import ChainBase` 必须继续兼容，使用仅限 ABI 的 lazy facade，并以独立测试
+  证明它没有被宿主 canonical 路径使用；同时把这一精确例外写入“不得延迟导入隐藏循环”的规则。
+- [ ] 保证 `_messaging`、`_recognition`、`base` 任意冷导入顺序都不依赖部分初始化包。
+- [ ] 对排除 `app/plugins/**` 的完整宿主图断言 SCC 集合等于精确 allowlist，而不是继续追加根前缀。
+- [ ] TMDB 29 模块移植包允许正常单向包外依赖，但禁止 SCC 成员扩展到 allowlist 外、包外模块
+  通过反向边加入该 SCC，或新增不符合分层方向的边。
+- [ ] 更新兼容、SDK、架构文档和 fixture 前先审查真实依赖变化。
+
+**验收**
+
+- 冷导入 `app.chain.base`、`app.chain._messaging`、`app.chain._recognition` 的全部顺序组合。
+- 验证宿主当前包根导入全部迁移，并保留 `app/plugins/__init__.py` 等插件兼容探针。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_architecture_dependencies.py \
+  tests/test_architecture_contract_baseline.py \
+  tests/test_legacy_import_compat.py \
+  tests/test_plugin_sdk.py -q
+.venv/bin/python scripts/architecture/baseline.py --check-host
+```
+
+### ARCH-108 收口具体 Adapter 与 HTTP 边界
+
+**问题与证据**
+
+- 当前 `app/application` 有 10 个文件、15 条直接 Adapter 导入，代表路径包括
+  `security/passkey.py`、`backup.py`、`image.py`、`rss.py`、`security/cookie.py`。
+- `app/chain` 有 8 个文件、13 条直接 Adapter 导入，使用 `RequestUtils`、Browser、Cloudflare、
+  CookieCloud、ServerHelper 等具体能力。
+- Passkey Application 服务直接判断 Redis 后端并调用 `RedisHelper.pop()`，安全策略识别了具体实现。
+- “所有 HTTP 必须经 RequestUtils”与 LLM streaming、第三方 SDK、移植库中的直接 HTTP 客户端现状
+  没有一份精确例外表，也没有 zero-growth gate。
+
+**目标与步骤**
+
+- [ ] 先建立 `application_to_adapters`、`chain_to_adapters` 和 direct-egress 可审查清单，冻结增长。
+- [ ] 将 Passkey 原子领取提升为 runtime cache contract，由 Memory/Redis backend 分别实现。
+- [ ] 为 Backup 定义 Application-owned artifact store Port，由 startup 注入文件系统实现。
+- [ ] 普通外部请求迁移到统一网络能力；SDK transport、streaming 和 vendor code 例外必须精确到路径与原因。
+- [ ] 命名外部产品和安全敏感能力优先改为注入 Port；通用技术 Adapter 是否可直接使用由 ARCH-101 决策。
+- [ ] 最终把基线收缩到零或少量书面化例外，而不是一次性禁止后再大量豁免。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_passkey_challenge.py \
+  tests/test_mfa_passkey_transactions.py \
+  tests/test_database_backup_service.py \
+  tests/test_database_backup_adapters.py \
+  tests/test_rss_helper.py -q
+.venv/bin/python scripts/architecture/baseline.py --check-host
+```
+
+### ARCH-109 按用例拆分超大编排器
+
+**共同规则**
+
+- 保留旧 Chain/Manager/Scheduler 的公开方法和插件 ABI，内部委托新服务。
+- 先提取合同和行为测试，再迁移一条主调用链；不按文件行数机械切块。
+- 纯决策进入 Domain/Application policy，I/O 进入 Adapter/Port，运行状态进入明确 owner。
+- 每个切片应能独立验证、提交和回滚。
+
+**建议切片**
+
+| 热点 | 建议所有权拆分 | 首要长方法/耦合点 |
+|---|---|---|
+| `SubscribeChain` | search、match、refresh、reference reconciliation、notification | 匹配和站点/规则引用更新 |
+| `TransferChain` | queue/recovery、plan、execute、settle、history/notify | `_execute_transfer` 约 836 行 |
+| `SearchChain` | plan、provider fan-out、result state、pagination | 并发状态与结果处理 |
+| `DownloadChain` | selection、submission、history、post-processing | batch download 约 449 行 |
+| `MediaChain` | recognition、source projection、music alignment、cache | 保留公共识别 Facade |
+| `Scheduler` | JobCatalog、ExecutionRegistry、domain reconciler、lifecycle Facade | `init` 约 336 行且直接构造多个 Chain |
+| Agent API | WebAgent session/SSE/file/audio Application service | `_web_agent_stream_impl` 约 361 行 |
+| System/Plugin API | nettest、logging、update、market use cases | 入口直接组合多个 Helper/Manager |
+
+### ARCH-110 分可信级执行 Module/Event Contract
+
+**问题与证据**
+
+- Module 动态方法名已经归零，这是完成项；但 50 个结果形状仍是 `ANY`。
+- `app/runtime/extensions/module/dispatcher.py:463-494` 对签名和结果偏差只告警并继续透传。
+- Event 53 个 payload model 已覆盖，但当前全部为 diagnostic enforcement，输出合同也很少。
+
+**目标与步骤**
+
+- [ ] 按“宿主内置 provider / 官方插件 / 第三方未知插件”划分可信级。
+- [ ] 下载、存储、消息等高风险宿主能力使用真实 Protocol/DTO，并在 admission 阶段 fail fast。
+- [ ] 官方插件先以 CI baseline 验证，再逐组切 strict。
+- [ ] 第三方插件继续诊断兼容，错误指标必须包含 method、provider、ABI source。
+- [ ] 不得为了严格化改变 `run_module` 字符串 ABI 或吞掉旧插件原始返回值。
+
+```bash
+.venv/bin/python -m pytest \
+  tests/test_module_method_contracts.py \
+  tests/test_module_invocation_dispatcher.py \
+  tests/test_module_quality.py \
+  tests/test_event_contracts.py -q
+.venv/bin/python scripts/architecture/baseline.py --check-host --diagnostics
+```
+
+### ARCH-111 升级质量与架构趋势门禁
+
+**当前盲区**
+
+- 复杂度脚本只检查 API、Application、Chain 的公共入口；私有长方法、类/文件规模和圈复杂度不受控。
+- strict mypy 仅 41 个文件，高风险 lifecycle、Scheduler、Agent、Plugin Manager 多数不在 frontier。
+- coverage ratchet 只聚合 Application 和 Domain。
+- Task owner gate 不盘点原生并发原语；Event consumer 扫描存在误报。
+- Ruff 仅是有限规则集的历史低水位，不代表整体风格/正确性无债务。
+
+**目标与步骤**
+
+- [ ] complexity v2 增加私有方法、class/file 行数和圈复杂度；先记录低水位，再只降不增。
+- [ ] strict mypy frontier 按 `runtime extensions -> startup -> workflow/scheduler -> messaging -> Agent`
+  扩大；每批必须先清零再加入配置。
+- [ ] coverage 增加 Chain、Runtime、Agent、Startup 的高风险子包或关键文件组，不用低价值行数冲百分比。
+- [ ] 原生并发门禁和 Event 扫描按 ARCH-101/106 修正。
+- [ ] Module Quality Scale 增加 capability -> required rules -> evidence tests 映射，避免“已登记”等同“已验证”。
+- [ ] 修改 CI 或门禁脚本时同时运行 `tests/test_architecture_ci.py` 和对应脚本单元测试。
+
+## 7. P2：持续可维护性优化
+
+### ARCH-201 收窄 Plugin 与 SDK 边界
+
+- [ ] `PluginHelper` 继续作为兼容入口，但市场、包、依赖、备份/恢复、健康修复分别委托现有 owner。
+- [ ] `PluginManager` 的服务图构造移到 startup typed `PluginRuntime` factory，Facade 只保留稳定 API。
+- [ ] 新 SDK 提供只读配置、插件查询和主循环提交等窄合同；旧 `settings/global_vars` 和具体 Manager
+  只能标记弃用，不能在当前大版本直接删除。
+- [ ] 用官方插件仓 baseline 和真实插件导入探针决定退场，不按宿主“无人引用”判断。
+
+### ARCH-202 拆分 Agent 与 LLM provider
+
+- [ ] 将内置 provider spec 数据从 `LLMProviderManager` 分离为只读 catalog。
+- [ ] 模型发现、认证会话、运行时构建和用户配置分成可替换服务。
+- [ ] 将 WebAgent SSE、文件/音频与会话桥接移出 API endpoint。
+- [ ] 保留 `AgentManager`/`LLMProviderManager` 公开方法为稳定 Facade，并逐批纳入 strict mypy。
+
+### ARCH-203 拆分 Domain 投影与 Startup 高扇出
+
+- [ ] `MediaInfo`/`domain/context.py` 保留 canonical 类型路径，把各外部来源 setter 的纯投影规则提取到
+  Domain 内部模块，旧方法委托，避免 DTO 再复制一套领域语义。
+- [ ] 将 `startup/initializers/modules.py` 的对象构造按领域移到 `startup/composition/*`；initializer
+  只负责顺序、注册和是否重启的决策。
+- [ ] 保留生命周期 manifest 和顺序快照；高扇出在组合根是允许的，但业务实现不能继续沉积其中。
+
+### ARCH-204 收敛 sync/async 重复与测试存量
+
+- [ ] 对重复 sync/async 方法先识别共享纯逻辑；保留双入口 ABI，只共享解析、校验、映射和状态决策。
+- [ ] 不用在线程包装里假装异步，也不因去重而跨事件循环复用 Session/客户端。
+- [ ] 修改到 `unittest.TestCase` 文件时按项目规则渐进转 pytest-native；不发起无行为收益的全库转换。
+- [ ] 每次转换都恢复 monkeypatch 的全局状态、singleton、cache 和 `sys.modules`。
+
+## 8. 建议实施顺序
+
+### 阶段 0：恢复可信基线
+
+1. 单独修复 ARCH-001，不刷新 mypy baseline。
+2. 完成 ARCH-101 的文档/门禁语义决策。
+3. 给 Adapter、原生并发、私有复杂度建立只读清单和 zero-growth 基线。
+
+**退出条件**：当前全部 CI gate 通过；文档、fixture 和测试对 SCC、Adapter 例外、Oper 使用方式的描述一致。
+
+### 阶段 1：先修可靠性和事务语义
+
+1. ARCH-102 设计并迁移 Transfer E3 状态机。
+2. 以站点/规则引用清理为 ARCH-103/104 的第一个 typed Port + UoW 纵切面。
+3. 完成 ARCH-105 的 post-commit 结构化结果与 Outbox 角色拆分。
+
+**退出条件**：故障注入覆盖清单列出的崩溃窗口；schema 有 migration；主路径不再 fail-open；调用方能区分
+业务提交与后置效果 pending。
+
+### 阶段 2：收口进程边界
+
+1. ARCH-106 将日志、消息队列和主循环 gateway 纳入 lifecycle。
+2. ARCH-107 拆出 `chain/base.py` 并消除新增 SCC。
+3. ARCH-108 先迁移 Passkey、Backup，再按风险迁移外部调用。
+
+**退出条件**：冷导入不启动线程；SCC 只剩 TMDB 精确豁免；Application/Chain 到 Adapter 的债务只降不增。
+
+### 阶段 3：按热点做纵向拆分
+
+建议顺序：Transfer -> Subscribe -> Scheduler -> Download/Search -> Agent API。每次只迁移一个完整用例，
+旧 Facade 委托并同时运行新旧入口契约测试。
+
+**退出条件**：复杂度低水位下降，公开 ABI 未变，文件移动没有新增跨层边或兼容映射滥用。
+
+### 阶段 4：扩大强类型与严格合同
+
+1. ARCH-110 对宿主高风险 Module/Event 开 strict。
+2. ARCH-111 扩大 strict mypy 和 coverage frontier。
+3. 执行 ARCH-201 至 ARCH-204 的渐进收敛。
+
+**退出条件**：新增代码全部位于强治理面；历史低水位持续下降；官方插件兼容验证无回退。
+
+## 9. 每个实施切片的统一门禁
+
+先运行受影响测试，再按风险扩大。架构、持久化、启动、生命周期、兼容层或跨模块改动必须运行全量套件。
+
+```bash
+# 当前宿主架构与趋势门禁
+.venv/bin/python scripts/architecture/baseline.py --check-host
+.venv/bin/mypy --config-file mypy.ini
+.venv/bin/python scripts/architecture/complexity.py
+.venv/bin/python scripts/architecture/async_blocking.py
+.venv/bin/python scripts/architecture/task_ownership.py
+.venv/bin/python scripts/architecture/service_locator.py
+.venv/bin/python scripts/architecture/ruff_ratchet.py
+.venv/bin/python scripts/architecture/mypy_ratchet.py
+.venv/bin/python scripts/startup/performance.py --check --repeat 3
+
+# 架构专项
+.venv/bin/python -m pytest \
+  tests/test_architecture_dependencies.py \
+  tests/test_architecture_contract_baseline.py \
+  tests/test_architecture_baseline_cli.py \
+  tests/test_complexity_gate.py \
+  tests/test_async_blocking_gate.py \
+  tests/test_task_ownership_gate.py \
+  tests/test_quality_ratchets.py \
+  tests/test_mypy_gate.py \
+  tests/test_architecture_ci.py -q
+
+# 广泛变更的最终本地回归
+uv run --locked --no-sync python tests/run.py
+
+# 需要覆盖率证据时按 CI 串行生成真实报告，再检查低水位
+uv run --locked --no-sync python -m coverage erase
+uv run --locked --no-sync python -m coverage run tests/run.py --serial
+uv run --locked --no-sync python -m coverage json
+uv run --locked --no-sync python scripts/architecture/coverage_ratchet.py
+
+# Python 源码改动对实际变更路径运行（按切片替换示例路径）
+uv run --locked --no-sync pylint app/path/to/changed.py
+```
+
+附加要求：
+
+- fixture 只有在依赖/合同变化经过人工审查后才能用 `--write-host` 更新，不能为转绿接受新增债务。
+- 所有 DB schema 变化必须新增 Alembic migration。
+- Plugin ABI、SDK/Compat 映射和官方插件仓验证独立执行；宿主绿灯不能替代插件兼容证据。
+- 正式插件 ABI 验证前先同步独立插件仓并记录所验 SHA，再运行：
+  `.venv/bin/python scripts/architecture/baseline.py --check-plugins --plugin-repo ../MoviePilot-Plugins`。
+- 每个阶段使用独立、可回滚的提交；不要把一个专项绿灯表述成整个长期目标完成。
+- 完成一次所有权迁移后，同步更新 canonical import、架构规则、SDK/Compat（仅在确有公共迁移时）和测试。
+- 依赖变更还必须运行 `uv lock --check`、锁定环境检查和
+  `docs/rules/03-commands.md` 规定的运行依赖漏洞审计。
+
+## 10. 明确不做
+
+- 不恢复物理 `app/core`、`app/helper`、`app/utils`、`app/log.py`。
+- 不删除精确 Compat 映射、`app.sdk._legacy`、Chain/Manager 稳定 Facade 或旧插件 ABI。
+- 不把 `app/plugins/**` 当作宿主实现重构；官方插件仓单独验证。
+- 不把所有 `run_module` 字符串调用一次性替换成静态 import。
+- 不把所有后台工作改造成持久队列；仅按 ADR 判定为需要跨重启完成的 E2/E3 动作进入 durable 机制。
+- 不机械拆 TMDB 移植包 SCC；当前只做精确 containment，未来通过替换/升级移植库处理。
+- 不为降低行数进行无合同、无行为测试的目录搬运。
+- 不一次性删除 sync/async 双入口、全局兼容对象或无参构造 ABI。
+- 不用更新 baseline、降低门禁或增加宽泛 allowlist 掩盖回归。
+
+## 11. 已完成且应继续保护的边界
+
+- [x] 旧 `core/helper/utils/log` 物理源码已移除，Compat 使用精确、惰性映射。
+- [x] canonical 实现层当前无 SDK/Compat 反向违规，`app/__init__.py` 和插件启动扫描等 bootstrap
+  例外保持精确；插件旧导入仍可用。
+- [x] Model/Oper 自建 Session、自动写事务和直接 commit/rollback 债务为零。
+- [x] HostRuntime、显式 Session/UoW、订阅/站点/Workflow 等参考切片已经落地。
+- [x] TaskRegistry owner、Workflow 有界关闭、Scheduler/Agent/Plugin/Message 生命周期已有专项保护。
+- [x] durable event/outbox 已覆盖关键事件切片；后续是按完成语义扩面，不是推倒重写。
+- [x] Module 动态方法名为零；Event payload model 已覆盖全部登记事件。
+- [x] `app/plugins/**` 与宿主架构基线分离，SDK/Plugin ABI 是独立验收面。
+
+这些完成项是后续优化的护栏。任何阶段若重新引入 Model/Oper 自建事务、物理旧路径、无 owner 资源
+或宿主到插件实现的依赖，即使局部测试通过，也应视为架构回退。

docs/architecture-overview.md

@@ -59,8 +59,12 @@ flowchart LR
 
 ## 二、整体分层架构
 
-MoviePilot v3 采用严格的单向依赖分层。历史包 `app/core`、`app/helper`、`app/utils`
-已不再存在物理目录，仅作为旧插件的**虚拟兼容导入根**保留。
+MoviePilot v3 以单向依赖的模块化单体为目标。历史包 `app/core`、`app/helper`、`app/utils`
+已不再存在物理目录，仅作为旧插件的**虚拟兼容导入根**保留。核心边界已有机器门禁，
+尚未强制的 Adapter 例外、完整宿主 SCC 等差距记录在本章末的优化清单中。
+
+下图同时表达职责关系与运行时调用方向，不等同于 Python 静态 import 图；通过 Port 注入的调用
+会与具体 Adapter 的静态依赖方向相反。
 
 ```mermaid
 flowchart TB
@@ -111,8 +115,7 @@ flowchart TB
 
     Chain -->|run_module 分发| Modules
     Chain -->|Application service / 命名数据端口| App
-    App --> Modules
-    App -->|Protocol / 持久化端口| Db
+    App -->|运行时调用 Protocol / 持久化端口| Db
 
     Modules --> Domain
     App --> Domain
@@ -136,13 +139,14 @@ flowchart TB
     Compat -.精确别名.-> Adapters
 ```
 
-图中的 `Chain → Application` 与 `Application → Db` 表示通过应用端口和组合根注入的实现完成持久化，
+图中的 `Chain → Application` 与 `Application → Db` 是运行时调用关系，表示通过应用端口和组合根
+注入的实现完成持久化；静态 import 方向是 `db.adapters → application Protocol`。
 具体 DB Adapter 再使用 Oper；这不是允许在用例代码中直接创建数据库引擎或拼接 SQL。`compat` 也不是只面向 SDK 的转发层，
 它按 `app/runtime/compat/manifest.py` 的白名单把已经删除的旧模块/符号精确映射到各自的 canonical
 归属。`app/application/subscribe.py` 与 `app/application/plugins.py` 都是 V3 重构过程中新增、
 未形成插件 ABI 的宿主内部聚合文件，主题实现收口后直接删除，不在 manifest 中制造新的兼容债务。
 
-当前实际的持久化调用路径可概括为：
+当前正式目标和已完成参考切片的持久化调用路径可概括为：
 
 ```text
 入口（API / Agent / CLI / Scheduler / Workflow）
@@ -153,13 +157,16 @@ flowchart TB
 ```
 
 `app/application/chain/data.py`、`app/application/agentdata.py` 和
-`app/application/history.py` 的 `get_*_port()` 是宿主生产代码读取组合根能力的规范入口；
-兼容期保留的 `*PortProxy` 不能重新被别名为 Oper。需要跨进程恢复或 commit 后可靠执行的
+`app/application/history.py` 的 `get_*_port()` 是宿主生产代码读取组合根能力的现有接缝；其中
+Chain/Agent 的 `Any` factory 和裸 Oper 仍需迁移为类型化 Port/DTO，不能把当前兼容代理当作最终合同。
+需要跨进程恢复或 commit 后可靠执行的
 业务副作用进入 `app/application/outbox.py` 定义的 Outbox 端口，由
 `app/db/adapters/outbox.py` 实现；`app/runtime/tasks.py` 的 TaskRegistry 只负责进程内任务所有权、
 取消和有限等待，不承担 durable queue 语义。
 
-**依赖方向的核心约束**（由 `tests/test_architecture_dependencies.py` 强制检查）：
+**依赖方向的规范目标**如下。`tests/test_architecture_dependencies.py` 已强制其中的核心子集；
+Application/Chain 到具体 Adapter 的例外和完整宿主 SCC 仍需按优化清单补齐门禁，不能把表中每一行
+都理解为当前已经被 CI 全量证明：
 
 | 方向 | 状态 |
 |---|---|
@@ -655,7 +662,7 @@ flowchart LR
 
 ## 十、架构治理
 
-架构边界不是文档约定，而是**由测试强制执行的门禁**：
+架构边界中的核心子集已经由测试强制执行，其余目标不能只停留在文档约定：
 
 - `tests/test_architecture_dependencies.py` 构建完整 Python 模块图，拒绝：
   物理遗留源码、禁止的上向依赖、SDK/compat 反向引用、包含迁移模块的强连通分量、
@@ -665,23 +672,24 @@ flowchart LR
   SDK 导出（若公开）、`docs/rules/05-architecture.md` 与上述架构测试。
 - 延迟导入不被接受为隐藏循环依赖的手段。
 
-### 10.1 2026-08-24 当前收口状态与后续边界
+### 10.1 2026-08-26 当前收口状态与后续边界
 
 当前宿主架构基线（排除 `app/plugins/**`）如下；数字来自
 `tests/fixtures/architecture/`，更新基线前必须先审查语义变化：
 
 | 指标 | 当前值 |
 |---|---:|
-| Python 模块 | 811 |
-| 内部导入边 | 6,572 |
-| 非平凡 SCC | 1（仅隔离的 TMDB 移植包） |
-| Module Contract V2 spec | 212（其中 211 个进入 `run_module` 观察面） |
+| Python 模块 | 835 |
+| 内部导入边 | 6,810 |
+| 非平凡 SCC | 2（Chain 包根环与隔离的 TMDB 移植包环） |
+| Module Contract V2 spec | 215（其中 214 个进入 `run_module` 观察面） |
 | Event Contract | 53 |
 | Model/Oper 自动事务与自建 Session | 0 |
 | 组合根外 `SystemConfigOper()` | 0 |
 
 架构专项验证：`tests/test_architecture_dependencies.py` 与
-`tests/test_architecture_contract_baseline.py` 共 68 passed；当前工作树未修改架构 fixture。
+`tests/test_architecture_contract_baseline.py` 共同提供语义断言和快照比较；
+`scripts/architecture/baseline.py --check-host` 只验证快照一致，不能替代依赖合理性审查。
 
 本总览与本轮架构治理的关系如下：
 
@@ -696,7 +704,8 @@ flowchart LR
   文件夹操作归入 `app/application/plugin/routes.py`、`folders.py`。原
   `app/application/subscribe.py`、`app/application/plugins.py` 未形成插件 ABI，已经直接删除，
   宿主调用统一改为 canonical 路径。
-- 已完成的运行时可靠性收口：TaskRegistry 统一进程内后台任务 owner；durable-required 事件和
+- 已完成的运行时可靠性收口：已迁移的主干后台任务由 TaskRegistry 或领域 lifecycle owner 管理；
+  durable-required 事件和
   订阅关键副作用经 `app/application/outbox.py` 与 `app/db/adapters/outbox.py` 进入同事务 Outbox；
   搜索逐页任务、Agent/消息事件和插件市场子任务均遵守请求或生命周期 owner，不再由入口模块维护
   无法追踪的裸任务集合。
@@ -704,6 +713,9 @@ flowchart LR
   物理文件仍是稳定入口的，不应为了目录规整新增“自己映射自己”的别名，也不应在 canonical 包中
   保留多余导出。
 
+当前架构问题、优先级、分阶段实施步骤与验收门禁见
+[`docs/architecture-optimization-checklist.md`](architecture-optimization-checklist.md)。
+
 ---
 
 ## 附录：相关文档索引
@@ -718,5 +730,7 @@ flowchart LR
 | [`docs/rules/10-data-and-persistent.md`](rules/10-data-and-persistent.md) | 数据模型、迁移与缓存规范 |
 | [`docs/subscribe-lifecycle.md`](subscribe-lifecycle.md) | 订阅生命周期详解 |
 | [`docs/mcp-api.md`](mcp-api.md) | MCP 工具端点说明 |
+| [`docs/architecture-optimization-checklist.md`](architecture-optimization-checklist.md) | 当前架构差距、优先级与可执行优化清单 |
+| [`docs/architecture-refactor-roadmap.md`](architecture-refactor-roadmap.md) | 多级 Goal、叶子依赖、清零条件与交付状态 |
 | [`docs/v3t-runtime-governance.md`](v3t-runtime-governance.md) | V3/V3t 运行依赖、故障恢复、GIL 可观测性与兼容退场门禁 |
 | [`docs/adr/0007-background-action-reliability.md`](adr/0007-background-action-reliability.md) | 后台动作 E0–E3 可靠性分级与完成语义决策 |

docs/architecture-refactor-roadmap.md

@@ -0,0 +1,203 @@
+# MoviePilot V3 架构重构路线图
+
+> 战略目标：完成 `docs/architecture-optimization-checklist.md` 的全部宿主架构重构与治理任务。
+>
+> 执行分支：`v3`；每个叶子完成后独立验证、提交、推送并确认远端 SHA。
+>
+> 排除范围：`app/plugins/**` 是插件运行时副本，不参与宿主重构。
+>
+> 兼容原则：新插件只使用 `app.sdk`；旧插件导入、符号和行为只由统一 Compat/Legacy 层承接。
+
+## 1. 治理合同
+
+### 1.1 Goal 层级
+
+- **G-ARCH（父目标）**：宿主架构、模块职责、持久化、生命周期、合同和质量债务全部达到本路线图终态。
+- **Stage（阶段）**：一组有共同退出条件的能力面，可包含多个独立叶子。
+- **Leaf（叶子）**：单一所有权面、可独立实现、验证、提交、推送和回滚的最小交付单元。
+
+原生 Codex Goal 保存 G-ARCH 的稳定目标；本文件保存阶段、叶子、依赖、状态和停止条件。
+
+### 1.2 状态
+
+| 状态 | 含义 |
+|---|---|
+| `ACTIVE` | 当前唯一允许编辑的叶子 |
+| `PLANNED` | 已定义边界，依赖满足后可激活 |
+| `BLOCKED` | 有明确阻塞证据，且没有可推进的替代叶子 |
+| `VERIFIED` | 本地验收完成，尚未推送或尚未确认远端 |
+| `DELIVERED` | 已提交、推送，远端 SHA 与本地交付一致 |
+| `COMPLETE` | 叶子验收和后续依赖均已结清 |
+
+任何时刻只允许一个 `ACTIVE` 叶子。子代理可以并行做只读审计、测试设计和下一叶准备；只有当前
+叶子的明确文件所有者可以写入源码。共享工作树中发现的并发改动必须先确认归属，不能覆盖。
+
+### 1.3 叶子完成条件
+
+一个叶子只有同时满足以下条件才可标记 `DELIVERED`：
+
+1. 所有定义在该叶子内的债务计数降为零，或变为有业务理由、精确路径、机器约束的非债务例外。
+2. 真实调用链已切换到新 owner；不能只增加新类、Port、DTO、门禁或测试而保留主路径走旧实现。
+3. canonical 主程序删除被替代的旧实现、兼容分支和重复导出，不保留“新旧两套正式入口”。
+4. 插件兼容只落在 `app/sdk`、`app/sdk/_legacy`、`app/runtime/compat` 或经批准的稳定 Facade；
+   canonical 实现不得为了兼容反向依赖这些层。
+5. 受影响专项、架构门禁、strict mypy、Ruff/mypy ratchet、scoped pylint 全部通过。
+6. 广泛架构、启动、生命周期、持久化或兼容变更运行锁定全量测试；插件 ABI 变更独立检查官方插件仓。
+7. diff、工作树、提交范围经过主线程审查；提交推送后 `HEAD == origin/v3` 且 ahead/behind 为 `0/0`。
+
+不得以以下状态宣称完成：只建立 baseline、只新增抽象未迁移调用方、只留下 TODO、只让新测试通过、
+只完成目录移动、只在兼容层外保留旧导出，或用 `--write` 接受新增债务。
+
+## 2. 最终停止条件
+
+G-ARCH 只有在以下条件全部满足后才可完成：
+
+- [ ] `ARCH-001`、`ARCH-101` 至 `ARCH-111`、`ARCH-201` 至 `ARCH-204` 全部完成。
+- [ ] 宿主依赖图没有未解释 SCC；只允许精确 containment 的 TMDB 移植包例外，成员不能增长。
+- [ ] Application/Chain 到具体 Adapter、direct egress、raw concurrency 等所有例外均精确、可解释、不可增长。
+- [ ] Chain/Agent 正式数据入口不再注入无 Session Oper，不再以 `Any`/ORM 作为跨层合同。
+- [ ] 正式业务写入均有单一事务 owner；E2/E3 动作完成语义、幂等、恢复与人工决策路径一致。
+- [ ] import、普通对象构造不启动进程资源；资源由 bootstrap/lifecycle 显式创建、发布、关闭和重试收口。
+- [ ] 宿主 Module/Event 高风险合同 strict；宿主已知 `ANY` 结果形状归零，第三方插件保持诊断兼容。
+- [ ] 全量 mypy 历史错误、当前 Ruff 治理规则诊断和所有新增 complexity-v2 超限归零。
+- [ ] 高风险 Chain、Agent、Runtime、Startup、Adapter 纳入类型、复杂度、覆盖率和并发原语门禁。
+- [ ] canonical 主程序无旧实现、重复导出和 legacy import；插件兼容检查基于同步后的官方插件仓 SHA 通过。
+- [ ] 锁定全量测试、Pylint、依赖一致性/漏洞审计（若涉及依赖）和最终远端一致性全部通过。
+
+## 3. 阶段与叶子
+
+### S0：可信基线与事实源
+
+退出条件：主线门禁全绿；架构规则、总览、机器快照和语义门禁一致；新增债务不能靠更新 fixture 进入。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S0-L1 可信基线恢复 | `VERIFIED` | 无 | 交付架构审计/路线图，修复 `ARCH-001` 两个 mypy 增量错误；现有专项和主线门禁通过 |
+| S0-L2 规范事实统一 | `PLANNED` | S0-L1 | 修正 Oper、Adapter、HTTP、SCC、调用图规则冲突；规范目标与已执行门禁逐项对应 |
+| S0-L3 完整宿主 SCC 门禁 | `PLANNED` | S0-L2 | 完整宿主 SCC 集合只允许 TMDB 精确 allowlist；Chain 环清零前门禁提供可审查低水位，最终由 S2-L2 清零 |
+| S0-L4 Adapter/Egress 债务门禁 | `PLANNED` | S0-L2 | Application/Chain Adapter 导入和 direct HTTP egress 有精确分类；未解释项归零且禁止增长 |
+| S0-L5 Event 扫描事实修复 | `PLANNED` | S0-L2 | consumer 只识别 EventManager 注册；动态误报归零，台账与真实生产/消费一致 |
+
+### S1：可靠性、事务与数据合同
+
+退出条件：Transfer 达到 E3；正式数据 Port 类型化；跨表业务操作有单一 UoW；post-commit/Outbox
+竞争、失败呈现、at-least-once 和幂等语义全部闭环。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S1-L1 Transfer E3 状态机 | `PLANNED` | S0 | `ARCH-102` 全部完成：migration、持久状态、checkpoint、lease、唯一 retry owner、重放和 manual review 一次交付 |
+| S1-L2 Workflow typed query | `PLANNED` | S0 | Workflow Application Port 不返回 `Any`/ORM，Session 内投影 DTO，正式调用方全部切换 |
+| S1-L3 Chain/Agent typed data ports | `PLANNED` | S1-L2 | `ChainDataPorts`/`AgentDataPorts` 的 raw Oper/`Any` factory 全部清零，兼容调用进入 Legacy 层 |
+| S1-L4 Subscription mutation UoW | `PLANNED` | S1-L3 | Subscription mutation 不跨 Session 传 ORM，正式写路径一个 UoW，旧自动事务入口退出 canonical 路径 |
+| S1-L5 站点/规则引用原子清理 | `PLANNED` | S1-L4 | SystemConfig+Subscribe 同事务更新，commit 后快照原子发布，并发/故障注入无部分状态 |
+| S1-L6 Outbox 完成语义 | `PLANNED` | S0 | claim 竞争双发清零；业务提交与 effect pending 可区分；stager/store 分离；handler 幂等与崩溃测试完整 |
+
+### S2：进程生命周期、循环与 Adapter 边界
+
+退出条件：导入/构造零资源副作用；Chain SCC 清零；Application/Chain 只依赖经批准的技术合同，
+安全和命名外部能力全部经注入 Port。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S2-L1 日志/消息资源显式生命周期 | `PLANNED` | S0 | import 和非消息 Chain 构造零新增线程；bootstrap 显式创建，失败和正常关闭均收口 |
+| S2-L2 ChainBase 与 SCC 清零 | `PLANNED` | S0-L3 | canonical `app.chain.base` 落地，包根无 eager/重复导出，宿主包根导入清零，Chain SCC 消失 |
+| S2-L3 GlobalVar/provider 注册收口 | `PLANNED` | S2-L1 | `global_vars` canonical 消费清零，provider 注册进入显式装配阶段并可 reset；Legacy 入口精确保留 |
+| S2-L4 Passkey 缓存边界 | `PLANNED` | S0-L4 | Application 不识别 Redis；原子 consume 由 runtime cache contract + backend 实现 |
+| S2-L5 Backup artifact Port | `PLANNED` | S0-L4 | Application 不构造 `BackupFiles`，文件 I/O 由注入 Adapter 拥有 |
+| S2-L6 Application Adapter 债务清零 | `PLANNED` | S2-L4,S2-L5 | Application 到具体 Adapter 的未批准边归零，批准通用机制有精确规则和门禁 |
+| S2-L7 Chain Adapter/HTTP 债务清零 | `PLANNED` | S2-L6 | Chain 具体 Adapter 与普通 direct HTTP 依赖归零；SDK/stream/vendor 例外精确 containment |
+
+### S3：大型编排器职责清零
+
+退出条件：每个热点 Facade 只保留稳定公开入口；决策、I/O、状态和生命周期各有单一 owner；
+旧实现从 canonical 文件删除，complexity-v2 对该所有权面无债务。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S3-L1 TransferChain | `PLANNED` | S1-L1 | queue/recovery、plan、execute、settle、history/notify 完整拆分，原 836 行执行方法消失 |
+| S3-L2 SubscribeChain | `PLANNED` | S1-L5 | search、match、refresh、reconciliation、notification 完整拆分，原文件无跨域业务实现 |
+| S3-L3 Scheduler | `PLANNED` | S2-L3 | JobCatalog、ExecutionRegistry、reconciler、lifecycle 分离，无参 Chain 构造清零 |
+| S3-L4 DownloadChain | `PLANNED` | S1-L6 | selection、submission、history、post-processing 分离，提交后动作遵守新完成语义 |
+| S3-L5 SearchChain | `PLANNED` | S2-L7 | plan、provider fan-out、result state、pagination 分离，状态 owner 唯一 |
+| S3-L6 MediaChain | `PLANNED` | S2-L2 | recognition、source projection、music alignment、cache 分离，兼容仅经统一层 |
+| S3-L7 Agent/System/Plugin API | `PLANNED` | S2,S1-L6 | WebAgent SSE/file/audio、nettest/log/update/market 用例进入 Application，endpoint 只做传输适配 |
+
+### S4：可执行合同与质量债务清零
+
+退出条件：高风险动态合同按信任级执行；所有 Python 源码进入一致的类型、复杂度、覆盖率和并发治理面；
+历史 mypy/Ruff/复杂度债务为零。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S4-L1 Module strict contract | `PLANNED` | S2-L7 | 宿主 provider `ANY` 结果归零，宿主 admission strict，官方/第三方插件分级兼容 |
+| S4-L2 Event strict contract | `PLANNED` | S0-L5,S1-L6 | 宿主事件输入/输出按风险 strict，诊断例外只属于第三方插件兼容 |
+| S4-L3 Complexity v2 | `PLANNED` | S3 | 私有方法、class/file、圈复杂度进入门禁；所有超限通过职责拆分归零 |
+| S4-L4 全量 mypy 清零 | `PLANNED` | S3,S4-L1,S4-L2 | `mypy-baseline.json` 归零并删除债务接受路径，全宿主 strict 类型通过 |
+| S4-L5 Ruff 治理债务清零 | `PLANNED` | S3 | 当前受控 973 条诊断归零，规则集扩展经过独立审查且新增诊断为零 |
+| S4-L6 Coverage/并发/质量证据 | `PLANNED` | S3,S4-L1,S4-L2 | 高风险包纳入 coverage；raw concurrency 分类清零；Module Quality 有真实 evidence test |
+
+### S5：Plugin、Agent、Domain、Startup 与最终收口
+
+退出条件：剩余 Facade/Manager/Domain/Startup 重复职责清零；官方插件兼容、全量测试和远端交付完成。
+
+| Leaf | 状态 | 依赖 | 完成定义 |
+|---|---|---|---|
+| S5-L1 PluginHelper/PluginManager | `PLANNED` | S2,S4 | 市场/包/依赖/备份/健康服务各归 owner；Facade 只转发稳定 ABI，构造归 typed PluginRuntime |
+| S5-L2 Agent/LLM provider | `PLANNED` | S3-L7,S4 | catalog、发现、认证、session、runtime 分离；Manager 只保留稳定 API |
+| S5-L3 Domain projection | `PLANNED` | S3-L6,S4 | `MediaInfo` canonical 路径保留，来源投影规则拆分，重复 DTO/业务语义清零 |
+| S5-L4 Startup composition | `PLANNED` | S2,S3,S5-L1,S5-L2 | `initializers/modules.py` 仅负责顺序/注册/重启决策，构造按领域进入 composition |
+| S5-L5 Sync/async 重复清零 | `PLANNED` | S3,S5 | 双 ABI 外壳共享纯逻辑，重复业务实现清零，Session/客户端不跨并发边界复用 |
+| S5-L6 最终兼容与交付 | `PLANNED` | 全部 | canonical 旧实现/重复导出清零；同步官方插件仓验证；锁定全量、Pylint、架构、类型、覆盖率全部通过并推送 |
+
+## 4. 当前活动叶子
+
+### S0-L1 可信基线恢复
+
+**Status:** `VERIFIED`（本地验收完成，等待提交、推送和远端一致性确认）
+
+**Outcome**
+
+在不接受新债务的前提下恢复当前主线类型门禁，交付审计清单、Goal 路线图和与实际基线一致的架构总览。
+
+**Ownership**
+
+- `app/chain/media.py` 的音乐曲目匹配局部类型回归。
+- `docs/architecture-optimization-checklist.md`。
+- `docs/architecture-refactor-roadmap.md`。
+- `docs/architecture-overview.md` 的当前事实与文档索引。
+
+**Excluded**
+
+- 不在本叶实现 ARCH-102 之后的业务重构。
+- 不刷新 mypy、Ruff、依赖或复杂度 fixture。
+- 不修改 `app/plugins/**` 或独立插件仓。
+
+**Acceptance**
+
+```bash
+.venv/bin/python -m pytest tests/test_music_album_match.py -q
+.venv/bin/mypy --config-file mypy.ini
+.venv/bin/python scripts/architecture/mypy_ratchet.py
+.venv/bin/python scripts/architecture/baseline.py --check-host
+.venv/bin/python scripts/architecture/complexity.py
+.venv/bin/python scripts/architecture/async_blocking.py
+.venv/bin/python scripts/architecture/task_ownership.py
+.venv/bin/python scripts/architecture/service_locator.py
+.venv/bin/python scripts/architecture/ruff_ratchet.py
+.venv/bin/python -m pytest \
+  tests/test_architecture_dependencies.py \
+  tests/test_architecture_contract_baseline.py \
+  tests/test_architecture_baseline_cli.py \
+  tests/test_complexity_gate.py \
+  tests/test_async_blocking_gate.py \
+  tests/test_task_ownership_gate.py \
+  tests/test_quality_ratchets.py \
+  tests/test_mypy_gate.py \
+  tests/test_architecture_ci.py -q
+git diff --check
+```
+
+**Delivery**
+
+- 单一提交主题：恢复可信架构基线并建立长期路线图。
+- 推送 `origin/v3` 后确认提交祖先关系、远端 SHA 和 ahead/behind `0/0`。