refactor: normalize downloader file contracts

tests/fixtures/architecture/runtime-contract-baseline.json

@@ -6138,7 +6138,7 @@
       "version": 1
     },
     "torrent_files": {
-      "aggregation": "legacy",
+      "aggregation": "first_non_empty",
       "error_policy": "isolate_provider",
       "execution": "sync_or_async",
       "family": "downloader",
@@ -6149,8 +6149,8 @@
         "downloader",
         "tid"
       ],
-      "result_contract": "DownloaderFileCollection | None",
-      "result_shape": "any",
+      "result_contract": "list[DownloaderFile]",
+      "result_shape": "list",
       "supports_async": true,
       "supports_sync": true,
       "timeout_policy": "caller_budget",

tests/test_downloader_file_contract.py

@@ -0,0 +1,35 @@
+"""下载器文件项宿主投影的跨 provider 契约测试。"""
+
+from types import SimpleNamespace
+
+from app.modules._base.downloader import _DownloaderModuleBase
+from app.schemas.transfer import DownloaderFile
+
+
+def test_normalize_torrent_files_accepts_mapping_object_and_sdk_wrapper() -> None:
+    """共同适配器应归一字典、属性对象和带 data 的 SDK 集合。"""
+    files = SimpleNamespace(
+        data=[
+            {"id": 1, "name": "Movie.mkv", "size": 1024},
+            SimpleNamespace(id="2", name="Subtitle.srt", progress=100),
+        ]
+    )
+
+    result = _DownloaderModuleBase._normalize_torrent_files(
+        files, DownloaderFile.model_validate
+    )
+
+    assert result == [
+        DownloaderFile(id=1, name="Movie.mkv", size=1024),
+        DownloaderFile(id="2", name="Subtitle.srt", progress=100),
+    ]
+
+
+def test_normalize_torrent_files_preserves_none_and_empty_collections() -> None:
+    """未命中 provider 与已命中空集合必须继续保持不同结果。"""
+    assert _DownloaderModuleBase._normalize_torrent_files(
+        None, DownloaderFile.model_validate
+    ) is None
+    assert _DownloaderModuleBase._normalize_torrent_files(
+        [], DownloaderFile.model_validate
+    ) == []

tests/test_module_manager_capability_adapter.py

@@ -851,7 +851,7 @@ from app.testing.bootstrap import prepare_backend
 prepare_backend()
 
 import sys
-from typing import Any, Optional, get_type_hints
+from typing import List, Optional, get_type_hints
 
 provider_prefixes = ("qbittorrentapi", "transmission_rpc", "pywebpush")
 
@@ -869,8 +869,9 @@ assert loaded_provider_modules() == []
 
 from app.chain import ChainBase
 from app.api.endpoints.message import WebPushError, is_webpush_subscription_gone
+from app.schemas.transfer import DownloaderFile
 
-assert get_type_hints(ChainBase.torrent_files)["return"] == Optional[Any]
+assert get_type_hints(ChainBase.torrent_files)["return"] == Optional[List[DownloaderFile]]
 assert get_type_hints(is_webpush_subscription_gone)["error"] is WebPushError
 assert loaded_provider_modules() == []
 """

tests/test_module_method_contracts.py

@@ -317,14 +317,14 @@ def test_side_effect_hooks_use_non_short_circuiting_fan_out_contracts() -> None:
         assert contract.plugin_short_circuit is False
 
 
-def test_heterogeneous_torrent_files_result_remains_legacy_compatible() -> None:
-    """下载器文件集合尚未归一前不得声明虚假的列表聚合语义。"""
+def test_torrent_files_uses_normalized_first_provider_result() -> None:
+    """下载器文件项归一后应按目标 provider 返回宿主 DTO 列表。"""
     contract = get_module_method_contract("torrent_files")
 
     assert contract.required_parameters == ("tid", "downloader")
-    assert contract.result_contract == "DownloaderFileCollection | None"
-    assert contract.aggregation is ModuleResultAggregation.LEGACY
-    assert contract.result_shape is ModuleResultShape.ANY
+    assert contract.result_contract == "list[DownloaderFile]"
+    assert contract.aggregation is ModuleResultAggregation.FIRST_NON_EMPTY
+    assert contract.result_shape is ModuleResultShape.LIST
 
 
 def test_torrent_tracker_contract_merges_downloader_mappings() -> None:

tests/test_qbittorrent_compat.py

@@ -113,6 +113,14 @@ def _load_qbittorrent_modules():
         def scheduler_job(self):
             pass
 
+        @staticmethod
+        def _normalize_torrent_files(files, item_factory):
+            """镜像宿主边界的文件集合投影。"""
+            if files is None:
+                return None
+            source = getattr(files, "data", files)
+            return [item_factory(item) for item in source]
+
         def _get_torrent_info(self, content):
             torrent_info, torrent_content = None, None
             if isinstance(content, Path):
@@ -148,6 +156,20 @@ def _load_qbittorrent_modules():
         def __init__(self, **kwargs):
             self.__dict__.update(kwargs)
 
+    class _DownloaderFile:
+        """隔离加载测试使用的最小下载器文件 DTO。"""
+
+        def __init__(self, **kwargs):
+            """保存文件字段。"""
+            self.__dict__.update(kwargs)
+
+        @classmethod
+        def model_validate(cls, item):
+            """兼容字典和属性对象输入。"""
+            if isinstance(item, dict):
+                return cls(**item)
+            return cls(**vars(item))
+
     class TorrentStatus(Enum):
         TRANSFER = "transfer"
         DOWNLOADING = "downloading"
@@ -179,6 +201,7 @@ def _load_qbittorrent_modules():
     schema_transfer_module.TransferTorrent = object
     schema_transfer_module.DownloadingTorrent = object
     schema_transfer_module.DownloaderTorrent = _DownloaderTorrent
+    schema_transfer_module.DownloaderFile = _DownloaderFile
     schema_types_module.TorrentStatus = TorrentStatus
     schema_types_module.TorrentQueryStatus = TorrentQueryStatus
     schema_types_module.DownloadTaskState = DownloadTaskState