refactor: unify host agent runtime access

app/api/endpoints/agent.py

@@ -37,10 +37,8 @@ from app.api.presentation.sse import build_sse_error_response, build_sse_respons
 from app.agent.contracts import ReplyMode, build_display_message
 from app.agent.llm.capability import AgentCapabilityManager
 from app.agent.mcp import agent_mcp_manager
-from app.agent.runtime_loader import (
-    get_moviepilot_agent_type,
-    get_running_agent_manager,
-)
+from app.agent.runtime_loader import get_moviepilot_agent_type
+from app.application.agent import get_running_agent_manager
 from app.chain.message import MessageChain
 from app.application.commands import get_command, get_commands
 from app.runtime.config import global_vars

app/api/endpoints/anthropic.py

@@ -22,7 +22,7 @@ from app.api.openai_utils import (
     build_session_id,
 )
 from app.api.presentation.sse import build_sse_response, encode_named_event
-from app.agent.runtime_loader import get_running_agent_manager
+from app.application.agent import get_running_agent_manager
 from app.application.configuration import get_api_runtime_config_snapshot
 from app.adapters.web.security.access import anthropic_api_key_header
 from app.api.context import (

app/api/endpoints/history.py

@@ -14,7 +14,7 @@ from app.schemas.token import TokenPayload as _SchemaTokenPayload
 from app.schemas.history import DownloadHistory as _SchemaDownloadHistory
 from app.api.response import ResponseAPIRouter
 from app.agent.contracts import ReplyMode
-from app.agent.runtime_loader import get_running_agent_manager
+from app.application.agent import get_running_agent_manager
 from app.agent.prompt.transfer_redo import (
     build_batch_manual_redo_prompt,
     build_manual_redo_prompt,

app/api/endpoints/openai.py

@@ -26,10 +26,8 @@ from app.api.openai_utils import (
     build_session_id,
 )
 from app.api.presentation.sse import build_sse_response, encode_data_event
-from app.agent.runtime_loader import (
-    get_moviepilot_agent_type,
-    get_running_agent_manager,
-)
+from app.agent.runtime_loader import get_moviepilot_agent_type
+from app.application.agent import get_running_agent_manager
 from app.agent.contracts import ReplyMode
 from app.application.configuration import get_api_runtime_config_snapshot
 from app.adapters.web.security.access import openai_bearer_scheme

app/application/agent.py

@@ -78,6 +78,8 @@ def get_agent_manager() -> Any:
 
 def get_running_agent_manager() -> Any | None:
     """返回已进入 RUNNING 的 AgentManager，不触发实现物化。"""
+    if _running_agent_manager_provider is None:
+        return None
     return _resolve(_running_agent_manager_provider, "running_agent_manager")
 
 

app/scheduler.py

@@ -1580,7 +1580,7 @@ class Scheduler(ConfigReloadMixin, metaclass=SingletonClass):
         :param trigger_source: 触发入口，scheduled-自动调度，manual-显式立即执行
         :return: 执行是否成功及结果摘要
         """
-        from app.agent.runtime_loader import get_running_agent_manager
+        from app.application.agent import get_running_agent_manager
 
         try:
             manager = get_running_agent_manager()
@@ -1993,7 +1993,7 @@ class Scheduler(ConfigReloadMixin, metaclass=SingletonClass):
         """
         智能体心跳唤醒：检查并执行待处理的定时任务
         """
-        from app.agent.runtime_loader import get_running_agent_manager
+        from app.application.agent import get_running_agent_manager
 
         manager = get_running_agent_manager()
         if manager is None:

docs/refactor/backend-architecture-next-stage.md

@@ -6,7 +6,7 @@
 > 审计范围：宿主后端；排除 `app/plugins/**` 运行时插件副本
 > 规范优先级：`AGENTS.md` 与 `docs/rules/` 高于本文
 > 相关文档：`docs/architecture-overview.md`、`docs/refactor/backend-architecture-governance.md`、`docs/refactor/backend-module-refactor-compatibility.md`
-> 实施进度：阶段 0～6 的宿主架构能力已完成收口；API/Application 公共复杂度基线已清零，启动组合根的 SystemConfigOper 构造点已由 14 降至 1；API 进程内后台任务已完成首批统一登记，插件仓适配和 Outbox 外围扩展仍按风险切片推进。Model/Base 查询与写装饰器、legacy 隐式会话外壳均已清零，插件 SDK 也不再导出宿主 Model。2026-08-23 的长期整改阶段 0 已恢复宿主、启动性能、官方插件和 SDK 契约门禁的可信基线；阶段 1a 已补齐 TaskRegistry owner 零债务门禁和诚实的关停超时语义；阶段 1b1 已收口整理 worker、pending 回放、失败通知、进程内 AI 重试、插件监控与事件投递的生命周期所有权；2026-08-24 的阶段 2 已将 212 个已观察宿主模块方法的 legacy aggregation 清零，并补齐可执行 fanout 与下载器文件 DTO 边界；阶段 3 已将消息交互和远程命令的订阅删除统一到 Application/UoW/outbox，宿主不再调用裸线程统计入口；阶段 4 已统一七种消息渠道的宿主回环与后台执行边界；阶段 5 已补齐事件窗口聚合任务的生命周期所有权；阶段 6 已统一插件文件操作的取消完成语义；阶段 7 已统一插件协程补偿的终态等待；阶段 8 已统一宿主同步函数的异步线程池入口；阶段 9 已统一工作流运行时的宿主获取路径；阶段 10 已统一模块、插件与调度运行时的显式 getter 调用；阶段 11 已清除系统配置 getter 的 Oper 形别名；阶段 12 已完成工作流域的显式 Chain 数据端口迁移；阶段 13 已收口用户、交互与消息链的数据端口；阶段 14 已收口音乐订阅数据端口；阶段 15 已收口站点数据端口；阶段 16 已收口媒体服务器数据端口；阶段 17 已收口下载数据端口；阶段 18 已收口主订阅数据端口；阶段 19 已收口整理数据端口；阶段 20 已收口 Agent 数据端口；阶段 21 已收口监控历史端口；阶段 22 已统一服务配置应用边界；阶段 23 已补齐媒体服务器 API 遗留的类形配置读取路径；阶段 24 已清除 Scheduler 内部无 owner 的协程提交双轨；阶段 25 已补齐 TaskRegistry 跨线程 owner 并迁移整理 AI 接管；阶段 26 已统一 Agent 会话清理提交；阶段 27 已统一历史 AI 进度 owner；阶段 28 已托管旧插件订阅统计线程；阶段 29 已统一 Emby 系条目转换并清零重复代码白名单；阶段 30 已收口插件市场请求级子任务；阶段 31 已托管搜索 AI 推荐任务；阶段 32 已清除事件调度器绕过生命周期 owner 的投递回退。
+> 实施进度：阶段 0～6 的宿主架构能力已完成收口；API/Application 公共复杂度基线已清零，启动组合根的 SystemConfigOper 构造点已由 14 降至 1；API 进程内后台任务已完成首批统一登记，插件仓适配和 Outbox 外围扩展仍按风险切片推进。Model/Base 查询与写装饰器、legacy 隐式会话外壳均已清零，插件 SDK 也不再导出宿主 Model。2026-08-23 的长期整改阶段 0 已恢复宿主、启动性能、官方插件和 SDK 契约门禁的可信基线；阶段 1a 已补齐 TaskRegistry owner 零债务门禁和诚实的关停超时语义；阶段 1b1 已收口整理 worker、pending 回放、失败通知、进程内 AI 重试、插件监控与事件投递的生命周期所有权；2026-08-24 的阶段 2 已将 212 个已观察宿主模块方法的 legacy aggregation 清零，并补齐可执行 fanout 与下载器文件 DTO 边界；阶段 3 已将消息交互和远程命令的订阅删除统一到 Application/UoW/outbox，宿主不再调用裸线程统计入口；阶段 4 已统一七种消息渠道的宿主回环与后台执行边界；阶段 5 已补齐事件窗口聚合任务的生命周期所有权；阶段 6 已统一插件文件操作的取消完成语义；阶段 7 已统一插件协程补偿的终态等待；阶段 8 已统一宿主同步函数的异步线程池入口；阶段 9 已统一工作流运行时的宿主获取路径；阶段 10 已统一模块、插件与调度运行时的显式 getter 调用；阶段 11 已清除系统配置 getter 的 Oper 形别名；阶段 12 已完成工作流域的显式 Chain 数据端口迁移；阶段 13 已收口用户、交互与消息链的数据端口；阶段 14 已收口音乐订阅数据端口；阶段 15 已收口站点数据端口；阶段 16 已收口媒体服务器数据端口；阶段 17 已收口下载数据端口；阶段 18 已收口主订阅数据端口；阶段 19 已收口整理数据端口；阶段 20 已收口 Agent 数据端口；阶段 21 已收口监控历史端口；阶段 22 已统一服务配置应用边界；阶段 23 已补齐媒体服务器 API 遗留的类形配置读取路径；阶段 24 已清除 Scheduler 内部无 owner 的协程提交双轨；阶段 25 已补齐 TaskRegistry 跨线程 owner 并迁移整理 AI 接管；阶段 26 已统一 Agent 会话清理提交；阶段 27 已统一历史 AI 进度 owner；阶段 28 已托管旧插件订阅统计线程；阶段 29 已统一 Emby 系条目转换并清零重复代码白名单；阶段 30 已收口插件市场请求级子任务；阶段 31 已托管搜索 AI 推荐任务；阶段 32 已清除事件调度器绕过生命周期 owner 的投递回退；阶段 33 已统一宿主 Agent 运行时的获取路径。
 
 ## 当前复核结论（2026-08-24）
 
@@ -341,6 +341,19 @@
 - 事件类型、payload、优先级、同步/异步 handler 签名、插件监听注册和 SDK/Compat 映射均未修改；
   `EventDispatcher` 仍是不对外公开的宿主内部算法类。
 
+### 长期整改阶段 33：宿主 Agent 运行时获取单路径（2026-08-24）
+
+- Chain 早已通过 `app.application.agent` 获取 Agent 服务，但 WebAgent、OpenAI、Anthropic、整理
+  历史 API 和 Scheduler 仍直接调用 `app.agent.runtime_loader`，对同一运行实例形成两条
+  宿主服务定位路径。
+- 五个宿主消费模块现在统一经已有 running manager provider 获取实例；门面在 lifespan
+  尚未装配时保持旧的 `None` 查询语义，API 仍返回 503，也不会提前物化 Agent、LLM 或工具树。
+- 架构 ratchet 精确禁止 `app.agent/**` 和 `app.startup/**` 之外的宿主模块直接导入两个 manager
+  getter。WebAgent/OpenAI 构造具体 Agent 的类型入口仍留在 Agent 展示实现边界；loader 原函数、
+  内部工具工厂、启动/热更新/关停语义、API 参数与插件 SDK/Compat 均未修改。
+- 依赖边集合按新门面路径刷新，模块数仍为 `806`、内部边仍为 `6546`；12 组禁止边
+  与唯一隔离 TMDB SCC 均未变化。
+
 ### 总体判断
 
 当前架构总体合理，已经从跨层混合的遗留单体收敛为**边界清晰的模块化单体**：

tests/fixtures/architecture/dependency-baseline.json

@@ -14,7 +14,7 @@
     "workflow_to_db": []
   },
   "edge_count": 6546,
-  "edge_sha256": "c840c6290e55ff267e35481176484590c5635d2d22904f57dd32d5adf396d0d1",
+  "edge_sha256": "64bd673bda7224d371b91e229d23eeea6ac14655301357a209dff510e30e151b",
   "edges": [
     "app -> app.runtime",
     "app -> app.runtime.compat",
@@ -1663,6 +1663,7 @@
     "app.api.endpoints.agent -> app.api.principal",
     "app.api.endpoints.agent -> app.api.response",
     "app.api.endpoints.agent -> app.application",
+    "app.api.endpoints.agent -> app.application.agent",
     "app.api.endpoints.agent -> app.application.commands",
     "app.api.endpoints.agent -> app.application.configuration",
     "app.api.endpoints.agent -> app.application.messaging",
@@ -1702,8 +1703,6 @@
     "app.api.endpoints.anthropic -> app.adapters.web",
     "app.api.endpoints.anthropic -> app.adapters.web.security",
     "app.api.endpoints.anthropic -> app.adapters.web.security.access",
-    "app.api.endpoints.anthropic -> app.agent",
-    "app.api.endpoints.anthropic -> app.agent.runtime_loader",
     "app.api.endpoints.anthropic -> app.api",
     "app.api.endpoints.anthropic -> app.api.context",
     "app.api.endpoints.anthropic -> app.api.endpoints",
@@ -1712,6 +1711,7 @@
     "app.api.endpoints.anthropic -> app.api.presentation",
     "app.api.endpoints.anthropic -> app.api.presentation.sse",
     "app.api.endpoints.anthropic -> app.application",
+    "app.api.endpoints.anthropic -> app.application.agent",
     "app.api.endpoints.anthropic -> app.application.configuration",
     "app.api.endpoints.anthropic -> app.runtime",
     "app.api.endpoints.anthropic -> app.runtime.tasks",
@@ -1847,7 +1847,6 @@
     "app.api.endpoints.history -> app.agent.contracts",
     "app.api.endpoints.history -> app.agent.prompt",
     "app.api.endpoints.history -> app.agent.prompt.transfer_redo",
-    "app.api.endpoints.history -> app.agent.runtime_loader",
     "app.api.endpoints.history -> app.api",
     "app.api.endpoints.history -> app.api.context",
     "app.api.endpoints.history -> app.api.dependencies",
@@ -1855,6 +1854,7 @@
     "app.api.endpoints.history -> app.api.dependencies.history",
     "app.api.endpoints.history -> app.api.response",
     "app.api.endpoints.history -> app.application",
+    "app.api.endpoints.history -> app.application.agent",
     "app.api.endpoints.history -> app.application.configuration",
     "app.api.endpoints.history -> app.application.history",
     "app.api.endpoints.history -> app.runtime",
@@ -2064,6 +2064,7 @@
     "app.api.endpoints.openai -> app.api.presentation",
     "app.api.endpoints.openai -> app.api.presentation.sse",
     "app.api.endpoints.openai -> app.application",
+    "app.api.endpoints.openai -> app.application.agent",
     "app.api.endpoints.openai -> app.application.configuration",
     "app.api.endpoints.openai -> app.runtime",
     "app.api.endpoints.openai -> app.runtime.tasks",
@@ -5798,9 +5799,8 @@
     "app.scheduler -> app.adapters",
     "app.scheduler -> app.adapters.external",
     "app.scheduler -> app.adapters.external.server",
-    "app.scheduler -> app.agent",
-    "app.scheduler -> app.agent.runtime_loader",
     "app.scheduler -> app.application",
+    "app.scheduler -> app.application.agent",
     "app.scheduler -> app.application.configuration",
     "app.scheduler -> app.application.database",
     "app.scheduler -> app.application.image",

tests/test_agent_scheduled_tasks.py

@@ -404,7 +404,7 @@ async def test_interrupted_date_task_manual_run_disables_and_removes_job(
     )
     manager.execute_scheduled_task = AgentManager.execute_scheduled_task.__get__(manager)
     monkeypatch.setattr(
-        "app.agent.runtime_loader.get_running_agent_manager",
+        "app.application.agent.get_running_agent_manager",
         lambda: manager,
     )
 
@@ -432,7 +432,7 @@ async def test_scheduler_propagates_scheduled_trigger_source(monkeypatch) -> Non
     scheduler = _build_agent_task_scheduler()
     execute = AsyncMock(return_value=(True, "执行完成"))
     monkeypatch.setattr(
-        "app.agent.runtime_loader.get_running_agent_manager",
+        "app.application.agent.get_running_agent_manager",
         lambda: SimpleNamespace(execute_scheduled_task=execute),
     )
 
@@ -677,7 +677,7 @@ async def test_scheduler_config_reload_preserves_active_agent_task(
     )
     manager.execute_scheduled_task = AgentManager.execute_scheduled_task.__get__(manager)
     monkeypatch.setattr(
-        "app.agent.runtime_loader.get_running_agent_manager",
+        "app.application.agent.get_running_agent_manager",
         lambda: manager,
     )
     monkeypatch.setattr(

tests/test_agent_task_runs.py

@@ -175,7 +175,7 @@ async def test_scheduler_agent_task_cleanup_uses_async_query(monkeypatch) -> Non
     sync_get = Mock(side_effect=AssertionError("不应调用同步 AgentTaskOper.get"))
     scheduler = SimpleNamespace(remove_agent_task_job=Mock())
     monkeypatch.setattr(
-        "app.agent.runtime_loader.get_running_agent_manager",
+        "app.application.agent.get_running_agent_manager",
         lambda: SimpleNamespace(execute_scheduled_task=execute),
     )
     monkeypatch.setattr(AgentTaskOper, "async_get", async_get)

tests/test_architecture_dependencies.py

@@ -1156,6 +1156,27 @@ def test_agent_application_facade_does_not_import_agent_implementation():
     } == set()
 
 
+def test_host_consumers_get_agent_manager_through_application_facade():
+    """宿主消费者不得绕过 Application 门面直接定位 Agent manager。"""
+    forbidden = {"get_agent_manager", "get_running_agent_manager"}
+    violations: dict[str, set[str]] = {}
+    for module_name, path in _discover_modules().items():
+        if module_name.startswith(("app.agent", "app.startup")):
+            continue
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        imported = {
+            alias.name
+            for node in ast.walk(tree)
+            if isinstance(node, ast.ImportFrom)
+            and node.module == "app.agent.runtime_loader"
+            for alias in node.names
+            if alias.name in forbidden
+        }
+        if imported:
+            violations[module_name] = imported
+    assert violations == {}
+
+
 def test_agent_tools_do_not_import_entrypoint_internals():
     """Agent 工具不得穿透导入 HTTP 端点、调度器与命令注册表内部实现。