refactor: unify mediaserver api config access

app/api/endpoints/mediaserver.py

@@ -20,7 +20,10 @@ from app.domain.context import MediaInfo
 from app.domain.metainfo import MetaInfo
 from app.adapters.web.security.access import verify_token
 from app.application.configuration import get_configured_system_config
-from app.application.mediaserver import MediaServerHelper, MediaServerQueryService
+from app.application.mediaserver import (
+    MediaServerQueryService,
+    get_mediaserver_configs,
+)
 from app.api.dependencies.history import get_mediaserver_query_service
 from app.schemas.mediaserver import NotExistMediaInfo
 from app.schemas.types import MediaSource, MediaType, SystemConfigKey
@@ -54,11 +57,12 @@ def play_item(
     """
     if not itemid:
         return _SchemaResponse(success=False, message="参数错误")
-    configs = MediaServerHelper().get_configs()
+    configs = get_mediaserver_configs()
     if not configs:
         return _SchemaResponse(success=False, message="未配置媒体服务器")
     media_chain = MediaServerChain()
-    for name in configs.keys():
+    for config in configs:
+        name = config.name
         item = media_chain.iteminfo(server=name, item_id=itemid)
         if item:
             play_url = media_chain.get_play_url(server=name, item_id=itemid)

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 已统一服务配置应用边界。
+> 实施进度：阶段 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 遗留的类形配置读取路径。
 
 ## 当前复核结论（2026-08-24）
 
@@ -240,6 +240,15 @@
 - `ServiceConfigHelper` 继续保留在 startup、runtime module adapter、模块实例初始化和 `app.sdk.services`
   插件兼容出口；V2/V3 插件导入、配置 Schema 和热更新读取器均未修改。
 
+### 长期整改阶段 23：媒体服务器 API 配置路径收口（2026-08-24）
+
+- 在线播放端点是阶段 22 后唯一仍以 `MediaServerHelper().get_configs()` 读取配置的 canonical API；现统一
+  调用 `get_mediaserver_configs()`，配置过滤、遍历顺序和播放地址响应保持不变。
+- 架构门禁覆盖该遗留点，拒绝端点重新导入类形 Helper；测试也替换命名 Application 接缝，不再伪造
+  Helper 实例。
+- `MediaServerHelper` 继续服务于运行实例发现和插件 SDK 兼容，类路径、方法、配置 Schema、路由及响应
+  均未修改，V2/V3 插件无需迁移。
+
 ### 总体判断
 
 当前架构总体合理，已经从跨层混合的遗留单体收敛为**边界清晰的模块化单体**：

tests/test_architecture_dependencies.py

@@ -615,7 +615,7 @@ def test_monitor_dispatcher_uses_explicit_history_port_getter():
 
 
 def test_canonical_service_config_consumers_use_application_directory():
-    """Chain、API、Scheduler 与 Agent 不得绕过应用目录读取运行时配置 Helper。"""
+    """Chain、API、Scheduler 与 Agent 不得绕过命名应用目录读取服务配置。"""
     paths = [
         APP_ROOT / "chain" / "_messaging.py",
         APP_ROOT / "chain" / "mediaserver.py",
@@ -624,6 +624,7 @@ def test_canonical_service_config_consumers_use_application_directory():
         APP_ROOT / "agent" / "llm" / "capability.py",
         APP_ROOT / "agent" / "tools" / "base.py",
         APP_ROOT / "agent" / "tools" / "impl" / "query_library_latest.py",
+        APP_ROOT / "api" / "endpoints" / "mediaserver.py",
     ]
     violations: list[str] = []
     for path in paths:
@@ -636,6 +637,15 @@ def test_canonical_service_config_consumers_use_application_directory():
                 violations.append(
                     f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}"
                 )
+            if (
+                path.name == "mediaserver.py"
+                and isinstance(node, ast.ImportFrom)
+                and node.module == "app.application.mediaserver"
+                and any(alias.name == "MediaServerHelper" for alias in node.names)
+            ):
+                violations.append(
+                    f"{path.relative_to(PROJECT_ROOT).as_posix()}:{node.lineno}:MediaServerHelper"
+                )
 
     assert violations == []
 

tests/test_emby_dashboard_links.py

@@ -1,4 +1,5 @@
 import unittest
+from types import SimpleNamespace
 from typing import Any
 from unittest.mock import Mock, patch
 
@@ -127,10 +128,12 @@ class EmbyDashboardLinksTest(unittest.TestCase):
         item = schemas.MediaServerItem(server="emby", item_id="emby-item-id", server_id="server-id")
 
         with (
-            patch("app.api.endpoints.mediaserver.MediaServerHelper") as helper_cls,
+            patch(
+                "app.api.endpoints.mediaserver.get_mediaserver_configs",
+                return_value=[SimpleNamespace(name="Emby")],
+            ),
             patch("app.api.endpoints.mediaserver.MediaServerChain") as chain_cls,
         ):
-            helper_cls.return_value.get_configs.return_value = {"Emby": object()}
             chain = chain_cls.return_value
             chain.iteminfo.return_value = item
             chain.get_play_url.return_value = "http://emby.local/web/index.html#!/item?id=emby-item-id"