feat(media): aggregate aliases from enabled metadata sources

app/application/configuration.py

@@ -187,6 +187,7 @@ class ChainRuntimeConfig:
     ai_recommend_user_preference: str = ""
     max_search_name_limit: int = 3
     search_multiple_name: bool = False
+    search_source: str = "themoviedb"
     search_threadpool_size: int = 1
     transfer_threads: int = 1
     transfer_failure_notification_aggregation: bool = True

app/chain/media.py

@@ -19,7 +19,7 @@ from app.domain.context import (
     MusicArtistInfo,
     MusicInfo,
 )
-from app.domain.media import is_music_media_source
+from app.domain.media import is_music_media_source, parse_media_source_selection
 from app.domain.meta.metabase import MetaBase
 from app.domain.meta.metamusic import MetaMusic
 from app.domain.metainfo import MetaInfo, MetaInfoPath
@@ -530,48 +530,6 @@ class MediaChain(ChainBase, metaclass=Singleton):
             logger.warn(f"{metainfo.title} 未识别到媒体信息")
         return mediainfo
 
-    @staticmethod
-    def _build_tmdb_supplement_meta(
-            mediainfo: MediaInfo,
-            metainfo: Optional[MetaBase] = None,
-    ) -> MetaBase:
-        """
-        根据主识别结果构造 TMDB 辅助识别参数。
-
-        :param mediainfo: 主识别源返回的媒体信息
-        :param metainfo: 原始标题解析信息
-        :return: 不携带主识别源身份的 TMDB 查询参数
-        """
-        title = mediainfo.title or getattr(metainfo, "name", None) or ""
-        tmdb_meta = MetaInfo(title)
-        if not tmdb_meta.cn_name and getattr(metainfo, "cn_name", None):
-            tmdb_meta.cn_name = metainfo.cn_name
-        if not tmdb_meta.en_name:
-            tmdb_meta.en_name = mediainfo.en_title or (
-                getattr(metainfo, "en_name", None)
-            )
-        tmdb_meta.type = mediainfo.type or (
-            getattr(metainfo, "type", None) or MediaType.UNKNOWN
-        )
-        season = (
-            mediainfo.season
-            if mediainfo.season is not None
-            else getattr(metainfo, "begin_season", None)
-        )
-        tmdb_meta.begin_season = season
-        season_year = None
-        if season is not None and mediainfo.season_years:
-            season_year = (
-                mediainfo.season_years.get(season)
-                or mediainfo.season_years.get(str(season))
-            )
-        tmdb_meta.year = (
-            season_year
-            or mediainfo.year
-            or getattr(metainfo, "year", None)
-        )
-        return tmdb_meta
-
     @staticmethod
     def _merge_tmdb_auxiliary(
             mediainfo: MediaInfo,
@@ -602,6 +560,154 @@ class MediaChain(ChainBase, metaclass=Singleton):
                 setattr(mediainfo, field, getattr(tmdb_media, field, None))
         return mediainfo
 
+    @staticmethod
+    def _build_tmdb_supplement_meta(
+            mediainfo: MediaInfo,
+            metainfo: Optional[MetaBase] = None,
+    ) -> MetaBase:
+        """构造兼容旧调用方的 TMDB 附加识别参数。"""
+        title = mediainfo.title or getattr(metainfo, "name", None) or ""
+        tmdb_meta = MetaInfo(title)
+        tmdb_meta.en_name = mediainfo.en_title or getattr(metainfo, "en_name", None)
+        tmdb_meta.type = mediainfo.type or getattr(metainfo, "type", None) or MediaType.UNKNOWN
+        season = (
+            mediainfo.season
+            if mediainfo.season is not None
+            else getattr(metainfo, "begin_season", None)
+        )
+        tmdb_meta.begin_season = season
+        season_year = None
+        if season is not None and mediainfo.season_years:
+            season_year = (
+                mediainfo.season_years.get(season)
+                or mediainfo.season_years.get(str(season))
+            )
+        tmdb_meta.year = season_year or mediainfo.year or getattr(metainfo, "year", None)
+        return tmdb_meta
+
+    @staticmethod
+    def _media_alias_candidates(mediainfo: object) -> list[str]:
+        """按稳定字段顺序提取单个来源可参与搜索匹配的标题候选。"""
+        candidates = [
+            getattr(mediainfo, field, None)
+            for field in (
+                "title",
+                "original_title",
+                "en_title",
+                "hk_title",
+                "tw_title",
+                "sg_title",
+            )
+        ]
+        candidates.extend(getattr(mediainfo, "names", None) or [])
+        return [str(candidate).strip() for candidate in candidates if str(candidate or "").strip()]
+
+    @classmethod
+    def _merge_media_auxiliary(
+            cls,
+            mediainfo: MediaInfo,
+            auxiliary_medias: Iterable[object],
+            selected_sources: Optional[MediaSourceSelection],
+    ) -> MediaInfo:
+        """合并多来源别名，并仅接受 TMDB 的兼容字段补充。"""
+        aliases = cls._media_alias_candidates(mediainfo)
+        seen_aliases = {" ".join(alias.casefold().split()) for alias in aliases}
+        selected = (
+            {selected_sources}
+            if isinstance(selected_sources, MediaSource)
+            else set(selected_sources or ())
+        )
+        for auxiliary in auxiliary_medias or []:
+            auxiliary_source = normalize_media_source(
+                getattr(auxiliary, "media_source", None)
+            )
+            if not auxiliary_source or (selected and auxiliary_source not in selected):
+                continue
+            for alias in cls._media_alias_candidates(auxiliary):
+                normalized = " ".join(alias.casefold().split())
+                if normalized in seen_aliases:
+                    continue
+                aliases.append(alias)
+                seen_aliases.add(normalized)
+            if auxiliary_source == MediaSource.TMDB:
+                cls._merge_tmdb_auxiliary(mediainfo, auxiliary)
+        mediainfo.names = aliases
+        return mediainfo
+
+    @staticmethod
+    def _resolve_auxiliary_sources(
+            media_source: Optional[MediaSourceSelection],
+    ) -> Optional[MediaSourceSelection]:
+        """解析请求级来源，未指定时使用用户配置的影视搜索来源集合。"""
+        if media_source:
+            return media_source
+        configured = get_chain_runtime_config_snapshot().search_source
+        try:
+            return parse_media_source_selection(configured) or None
+        except ValueError as err:
+            logger.warning(f"媒体附加信息来源配置无效，跳过补充：{err}")
+            return ()
+
+    def supplement_media_info(
+            self,
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]],
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> Optional[Union[MediaInfo, MusicInfo]]:
+        """按用户启用的数据源聚合影视别名和受控的 TMDB 附加字段。"""
+        if (
+                not mediainfo
+                or isinstance(mediainfo, MusicInfo)
+                or mediainfo.type == MediaType.MUSIC
+        ):
+            return mediainfo
+        selected_sources = self._resolve_auxiliary_sources(media_source)
+        try:
+            auxiliary_medias = self.run_module(
+                "get_media_auxiliary_info",
+                mediainfo=mediainfo,
+                media_source=selected_sources,
+                metainfo=metainfo,
+            ) or []
+        except Exception as err:
+            logger.warning(f"{mediainfo.title_year} 获取媒体附加信息失败：{err}")
+            return mediainfo
+        return self._merge_media_auxiliary(
+            mediainfo,
+            auxiliary_medias,
+            selected_sources,
+        )
+
+    async def async_supplement_media_info(
+            self,
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]],
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> Optional[Union[MediaInfo, MusicInfo]]:
+        """异步按用户启用的数据源聚合影视别名和受控 TMDB 字段。"""
+        if (
+                not mediainfo
+                or isinstance(mediainfo, MusicInfo)
+                or mediainfo.type == MediaType.MUSIC
+        ):
+            return mediainfo
+        selected_sources = self._resolve_auxiliary_sources(media_source)
+        try:
+            auxiliary_medias = await self.async_run_module(
+                "async_get_media_auxiliary_info",
+                mediainfo=mediainfo,
+                media_source=selected_sources,
+                metainfo=metainfo,
+            ) or []
+        except Exception as err:
+            logger.warning(f"{mediainfo.title_year} 异步获取媒体附加信息失败：{err}")
+            return mediainfo
+        return self._merge_media_auxiliary(
+            mediainfo,
+            auxiliary_medias,
+            selected_sources,
+        )
+
     def supplement_tmdb_info(
             self,
             mediainfo: Optional[Union[MediaInfo, MusicInfo]],
@@ -614,35 +720,11 @@ class MediaChain(ChainBase, metaclass=Singleton):
         :param metainfo: 原始标题解析信息
         :return: 已补充 TMDB 辅助字段的原媒体对象
         """
-        if not mediainfo:
-            return None
-        # 音乐原样返回：下面全是 TMDB 影视字段，MusicInfo 上根本没有。用 isinstance
-        # 而不只看 type，一来静态检查能据此收窄（.type == 的比较收窄不了类型），二来
-        # type 没被正确赋值的 MusicInfo 也挡得住，不至于到下一行才 AttributeError
-        if isinstance(mediainfo, MusicInfo) or mediainfo.type == MediaType.MUSIC:
-            return mediainfo
-        if mediainfo.tmdb_id and mediainfo.tmdb_info and mediainfo.genre_ids:
-            return mediainfo
-        tmdb_meta = self._build_tmdb_supplement_meta(mediainfo, metainfo)
-        # 按 source 路由走统一 dispatch：宿主识别模块对非自身来源都会快速返回 None，
-        # 指定 TMDB 来源时只有 TheMovieDbModule 会应答，链层无需点名具体模块
-        try:
-            tmdb_media = self.run_module(
-                "recognize_media",
-                meta=tmdb_meta,
-                mtype=mediainfo.type,
-                media_source=MediaSource.TMDB,
-                media_id=str(mediainfo.tmdb_id) if mediainfo.tmdb_id else None,
-                episode_group=mediainfo.episode_group,
-                cache=True,
-            )
-        except Exception as err:
-            logger.warn(f"{mediainfo.title_year} 补充 TMDB 辅助信息失败：{err}")
-            return mediainfo
-        if not tmdb_media:
-            logger.warn(f"{mediainfo.title_year} 未匹配到 TMDB 辅助信息")
-            return mediainfo
-        return self._merge_tmdb_auxiliary(mediainfo, tmdb_media)
+        return self.supplement_media_info(
+            mediainfo=mediainfo,
+            media_source=MediaSource.TMDB,
+            metainfo=metainfo,
+        )
 
     def _recognize_with_fallback_by_meta(
             self,

app/chain/search.py

@@ -1212,6 +1212,7 @@ class SearchChain(ChainBase):
         else:
             # 去重去空，但要保持顺序
             keywords = list(dict.fromkeys([k for k in [mediainfo.title,
+                                                       *(mediainfo.names or []),
                                                        mediainfo.original_title,
                                                        mediainfo.en_title,
                                                        mediainfo.hk_title,
@@ -1709,6 +1710,9 @@ class SearchChain(ChainBase):
                 logger.error('媒体信息识别失败！')
                 return []
 
+        # 搜索前按用户启用的数据源聚合别名；分类、风格与外部 ID 仅由 TMDB 补充。
+        mediainfo = MediaChain().supplement_media_info(mediainfo) or mediainfo
+
         # 准备搜索参数
         season_episodes, keywords = self.__prepare_params(
             mediainfo=mediainfo,
@@ -1802,6 +1806,12 @@ class SearchChain(ChainBase):
                 logger.error('媒体信息识别失败！')
                 return []
 
+        # 异步搜索与同步入口共享同一份多来源附加信息语义。
+        mediainfo = (
+            await MediaChain().async_supplement_media_info(mediainfo)
+            or mediainfo
+        )
+
         # 准备搜索参数
         season_episodes, keywords = self.__prepare_params(
             mediainfo=mediainfo,
@@ -1890,6 +1900,11 @@ class SearchChain(ChainBase):
                 }
                 return
 
+        mediainfo = (
+            await MediaChain().async_supplement_media_info(mediainfo)
+            or mediainfo
+        )
+
         # 准备搜索参数
         season_episodes, keywords = self.__prepare_params(
             mediainfo=mediainfo,

app/chain/subscribe.py

@@ -1804,8 +1804,14 @@ class SubscribeChain(MusicSubscribeMixin, InteractionChainMixin, ChainBase):
                     if exist_flag:
                         continue
 
-                    # 清理多余信息
+                    # 匹配前聚合多来源别名；清理大字段时保留匹配所需的标题合集。
+                    mediainfo = (
+                        MediaChain().supplement_media_info(mediainfo)
+                        or mediainfo
+                    )
+                    auxiliary_names = list(getattr(mediainfo, "names", None) or [])
                     mediainfo.clear()
+                    mediainfo.names = auxiliary_names
 
                     # 订阅识别词
                     if subscribe.custom_words:

app/modules/anilist/__init__.py

@@ -1,15 +1,17 @@
 from typing import List, Optional, Tuple, Union
 
-from app.schemas.context import MediaPerson as _SchemaMediaPerson
 from app.runtime.settings import RuntimeSettingsCompat
+from app.schemas.context import MediaPerson as _SchemaMediaPerson
 
 settings = RuntimeSettingsCompat()
 from app.domain.context import MediaInfo
+from app.domain.media import is_media_source_enabled
 from app.domain.meta.metabase import MetaBase
 from app.domain.scraper import MediaScraperHelper
-from app.runtime.log import logger
 from app.modules import _ModuleBase
 from app.modules.anilist.anilist import AniListApi
+from app.modules.media_auxiliary import MediaAuxiliaryProviderMixin
+from app.runtime.log import logger
 from app.schemas.types import (
     MediaRecognizeType,
     MediaSource,
@@ -17,14 +19,14 @@ from app.schemas.types import (
     MediaType,
     ModuleType,
 )
-from app.domain.media import is_media_source_enabled
 
 
-class AniListModule(_ModuleBase):
+class AniListModule(MediaAuxiliaryProviderMixin, _ModuleBase):
     """
     AniList 动画媒体识别与刮削模块
     """
 
+    auxiliary_media_source = MediaSource.AniList
     CONFIG_WATCH = {"PROXY_HOST"}
 
     anilist_api: AniListApi = None

app/modules/bangumi/__init__.py

@@ -1,16 +1,19 @@
 from dataclasses import dataclass
 from typing import Any, List, Optional, Tuple, Union
 
-from app.schemas.context import MediaPerson as _SchemaMediaPerson
 from app.runtime.settings import RuntimeSettingsCompat
+from app.schemas.context import MediaPerson as _SchemaMediaPerson
 
 settings = RuntimeSettingsCompat()
+from app.adapters.network.http import RequestUtils
 from app.domain.context import MediaInfo
+from app.domain.media import is_media_source_enabled
 from app.domain.meta.metabase import MetaBase
 from app.domain.scraper import MediaScraperHelper
-from app.runtime.log import logger
 from app.modules import _ModuleBase
 from app.modules.bangumi.bangumi import BangumiApi
+from app.modules.media_auxiliary import MediaAuxiliaryProviderMixin
+from app.runtime.log import logger
 from app.schemas.types import (
     MediaRecognizeType,
     MediaSource,
@@ -18,8 +21,6 @@ from app.schemas.types import (
     MediaType,
     ModuleType,
 )
-from app.adapters.network.http import RequestUtils
-from app.domain.media import is_media_source_enabled
 
 
 @dataclass(frozen=True, slots=True)
@@ -29,10 +30,11 @@ class BangumiConfigSnapshot:
     proxy: Any
 
 
-class BangumiModule(_ModuleBase):
+class BangumiModule(MediaAuxiliaryProviderMixin, _ModuleBase):
     """
     Bangumi媒体信息匹配
     """
+    auxiliary_media_source = MediaSource.Bangumi
     CONFIG_WATCH = {"PROXY_HOST"}
 
     bangumiapi: BangumiApi = None

app/modules/douban/__init__.py

@@ -3,43 +3,45 @@ from typing import Any, List, Optional, Tuple, Union
 
 import cn2an
 
-from app.schemas.context import MediaPerson as _SchemaMediaPerson
 from app.runtime.settings import RuntimeSettingsCompat
+from app.schemas.context import MediaPerson as _SchemaMediaPerson
 
 settings = RuntimeSettingsCompat()
+from app.adapters.network.http import RequestUtils
 from app.domain.context import (
     MediaInfo,
     MusicAlbumInfo,
     MusicInfo,
 )
+from app.domain.media import is_media_source_enabled, is_media_source_selected
 from app.domain.meta.metabase import MetaBase
 from app.domain.meta.metamusic import MetaMusic
 from app.domain.metainfo import MetaInfo
-from app.runtime.log import logger
+from app.foundation.text import convert as zhconv_convert
 from app.modules import _ModuleBase
 from app.modules.douban.apiv2 import DoubanApi
 from app.modules.douban.scraper import DoubanScraper
+from app.modules.media_auxiliary import MediaAuxiliaryProviderMixin
+from app.runtime.execution import retry
+from app.runtime.log import logger
+from app.runtime.rate import rate_limit_exponential
 from app.schemas.context import MediaPerson
 from app.schemas.exception import APIRateLimitException
 from app.schemas.types import (
     MUSIC_ENTITY_ALBUM,
     MUSIC_ENTITY_RECORDING,
+    MediaRecognizeType,
     MediaSource,
     MediaSourceSelection,
     MediaType,
     ModuleType,
-    MediaRecognizeType,
 )
-from app.runtime.execution import retry
-from app.adapters.network.http import RequestUtils
-from app.runtime.rate import rate_limit_exponential
-from app.domain.media import is_media_source_enabled, is_media_source_selected
-from app.foundation.text import convert as zhconv_convert
 
 
-class DoubanModule(_ModuleBase):
+class DoubanModule(MediaAuxiliaryProviderMixin, _ModuleBase):
     """提供豆瓣影视与豆瓣音乐元数据识别能力。"""
 
+    auxiliary_media_source = MediaSource.Douban
     _music_source = MediaSource.DoubanMusic
     doubanapi: DoubanApi = None
     scraper: DoubanScraper = None

app/modules/imdb/__init__.py

@@ -11,6 +11,7 @@ from app.domain.meta.metabase import MetaBase
 from app.domain.scraper import MediaScraperHelper
 from app.foundation.text import convert as zhconv_convert
 from app.modules import _ModuleBase
+from app.modules.media_auxiliary import MediaAuxiliaryProviderMixin
 from app.runtime.settings import RuntimeSettingsCompat
 
 settings = RuntimeSettingsCompat()
@@ -43,9 +44,10 @@ class ImdbConfigSnapshot:
     proxy: Any
 
 
-class ImdbModule(_ModuleBase):
+class ImdbModule(MediaAuxiliaryProviderMixin, _ModuleBase):
     """提供 IMDb 搜索、识别、详情补全与刮削能力。"""
 
+    auxiliary_media_source = MediaSource.IMDb
     CONFIG_WATCH = {"PROXY_HOST"}
     _IMDB_ID_PATTERN = re.compile(r"^tt\d+$", re.IGNORECASE)
     _MOVIE_TYPES = frozenset({"movie", "tvMovie"})

app/modules/media_auxiliary.py

@@ -0,0 +1,95 @@
+"""影视识别模块共享的附加信息能力实现。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Optional
+
+from app.domain.context import MediaInfo
+from app.domain.media import is_media_source_enabled
+from app.domain.meta.metabase import MetaBase
+from app.domain.metainfo import MetaInfo
+from app.schemas.types import MediaSource, MediaSourceSelection, MediaType
+
+
+class MediaAuxiliaryProviderMixin:
+    """把现有识别接口适配为可聚合的影视附加信息能力。"""
+
+    auxiliary_media_source: MediaSource
+
+    @staticmethod
+    def _build_auxiliary_meta(
+            mediainfo: MediaInfo,
+            metainfo: Optional[MetaBase] = None,
+    ) -> MetaInfo:
+        """根据主识别结果构造不携带原来源身份的标题查询参数。"""
+        meta = MetaInfo(mediainfo.title or getattr(metainfo, "name", None) or "")
+        if not meta.en_name:
+            meta.en_name = mediainfo.en_title or getattr(metainfo, "en_name", None)
+        meta.type = mediainfo.type or getattr(metainfo, "type", None) or MediaType.UNKNOWN
+        meta.begin_season = (
+            mediainfo.season
+            if mediainfo.season is not None
+            else getattr(metainfo, "begin_season", None)
+        )
+        season_year = None
+        if meta.begin_season is not None and mediainfo.season_years:
+            season_year = (
+                mediainfo.season_years.get(meta.begin_season)
+                or mediainfo.season_years.get(str(meta.begin_season))
+            )
+        meta.year = season_year or mediainfo.year or getattr(metainfo, "year", None)
+        return meta
+
+    def _auxiliary_recognize_kwargs(
+            self,
+            mediainfo: MediaInfo,
+            metainfo: Optional[MetaBase] = None,
+    ) -> dict[str, object]:
+        """构造当前来源的识别参数，同源媒体优先使用来源原生 ID。"""
+        same_source = mediainfo.media_source == self.auxiliary_media_source
+        return {
+            "meta": self._build_auxiliary_meta(mediainfo, metainfo),
+            "mtype": mediainfo.type,
+            "media_source": self.auxiliary_media_source,
+            "media_id": mediainfo.media_id if same_source else None,
+            "episode_group": mediainfo.episode_group,
+            "cache": True,
+        }
+
+    def get_media_auxiliary_info(
+            self,
+            mediainfo: MediaInfo,
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> list[MediaInfo]:
+        """使用当前来源同步获取影视别名等附加信息。"""
+        if (
+                not mediainfo
+                or mediainfo.type not in (MediaType.MOVIE, MediaType.TV)
+                or not is_media_source_enabled(media_source, self.auxiliary_media_source)
+        ):
+            return []
+        recognize: Callable[..., Optional[MediaInfo]] = getattr(self, "recognize_media")
+        result = recognize(**self._auxiliary_recognize_kwargs(mediainfo, metainfo))
+        return [result] if result else []
+
+    async def async_get_media_auxiliary_info(
+            self,
+            mediainfo: MediaInfo,
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> list[MediaInfo]:
+        """使用当前来源异步获取影视别名等附加信息。"""
+        if (
+                not mediainfo
+                or mediainfo.type not in (MediaType.MOVIE, MediaType.TV)
+                or not is_media_source_enabled(media_source, self.auxiliary_media_source)
+        ):
+            return []
+        recognize: Callable[..., Awaitable[Optional[MediaInfo]]] = getattr(
+            self,
+            "async_recognize_media",
+        )
+        result = await recognize(**self._auxiliary_recognize_kwargs(mediainfo, metainfo))
+        return [result] if result else []

app/modules/themoviedb/__init__.py

@@ -1,24 +1,29 @@
 import re
-from typing import Optional, List, Tuple, Union, Dict
+from typing import Dict, List, Optional, Tuple, Union
 
 import cn2an
 
-from app.schemas.context import MediaPerson as _SchemaMediaPerson
-from app.schemas.tmdb import TmdbSeason as _SchemaTmdbSeason
-from app.schemas.tmdb import TmdbEpisode as _SchemaTmdbEpisode
 from app.runtime.settings import RuntimeSettingsCompat
+from app.schemas.context import MediaPerson as _SchemaMediaPerson
+from app.schemas.tmdb import TmdbEpisode as _SchemaTmdbEpisode
+from app.schemas.tmdb import TmdbSeason as _SchemaTmdbSeason
 
 settings = RuntimeSettingsCompat()
+from app.adapters.network.http import RequestUtils
 from app.domain.context import MediaInfo
+from app.domain.media import is_media_source_enabled, is_media_source_selected
 from app.domain.meta.metabase import MetaBase
-from app.runtime.log import logger
+from app.foundation.text import convert as zhconv_convert
 from app.modules import _ModuleBase
+from app.modules.media_auxiliary import MediaAuxiliaryProviderMixin
 from app.modules.themoviedb.category import CategoryHelper
 from app.modules.themoviedb.scraper import TmdbScraper
 from app.modules.themoviedb.tmdb_cache import TmdbCache
 from app.modules.themoviedb.tmdbapi import TmdbApi
 from app.modules.themoviedb.tmdbv3api.exceptions import TMDbConnectionError
+from app.runtime.log import logger
 from app.schemas.category import CategoryConfig
+from app.schemas.media import normalize_media_source
 from app.schemas.types import (
     MediaImageType,
     MediaRecognizeType,
@@ -27,20 +32,16 @@ from app.schemas.types import (
     MediaType,
     ModuleType,
 )
-from app.adapters.network.http import RequestUtils
-from app.domain.media import is_media_source_enabled, is_media_source_selected
-from app.schemas.media import normalize_media_source
-from app.foundation.text import convert as zhconv_convert
-
 
 _DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
 
-class TheMovieDbModule(_ModuleBase):
+class TheMovieDbModule(MediaAuxiliaryProviderMixin, _ModuleBase):
     """
     TMDB媒体信息匹配
     """
     CONFIG_WATCH = {"PROXY_HOST", "TMDB_API_DOMAIN", "TMDB_API_KEY", "TMDB_LOCALE"}
+    auxiliary_media_source = MediaSource.TMDB
 
     # 元数据缓存
     cache: TmdbCache = None

app/modules/thetvdb/__init__.py

@@ -1,13 +1,23 @@
 from threading import Lock
-from typing import Optional, Tuple, Union
+from typing import Optional, Tuple, Union, cast
 
 from app.runtime.settings import RuntimeSettingsCompat
 
 settings = RuntimeSettingsCompat()
-from app.runtime.log import logger
+from app.domain.context import MediaInfo
+from app.domain.media import is_media_source_enabled
+from app.domain.meta.metabase import MetaBase
 from app.modules import _ModuleBase
 from app.modules.thetvdb import tvdb_v4_official
-from app.schemas.types import ModuleType, MediaRecognizeType
+from app.runtime.execution import run_in_threadpool
+from app.runtime.log import logger
+from app.schemas.types import (
+    MediaRecognizeType,
+    MediaSource,
+    MediaSourceSelection,
+    MediaType,
+    ModuleType,
+)
 
 
 class TheTvDbModule(_ModuleBase):
@@ -179,6 +189,111 @@ class TheTvDbModule(_ModuleBase):
             logger.error(f"用标题搜索TVDB剧集失败 ({title}): {str(err)}")
             return []
 
+    @staticmethod
+    def _tvdb_aliases(info: dict[str, object]) -> list[str]:
+        """从 TVDB 搜索或详情响应中提取名称与翻译别名。"""
+        values: list[object] = [info.get("name")]
+        for field in ("aliases", "translations", "nameTranslations"):
+            raw_value = info.get(field) or []
+            if isinstance(raw_value, dict):
+                raw_value = list(raw_value.values())
+            if not isinstance(raw_value, (list, tuple, set)):
+                raw_value = [raw_value]
+            for item in raw_value:
+                values.append(
+                    item.get("name") or item.get("value")
+                    if isinstance(item, dict)
+                    else item
+                )
+        aliases: list[str] = []
+        seen: set[str] = set()
+        for value in values:
+            alias = str(value or "").strip()
+            normalized = " ".join(alias.casefold().split())
+            if alias and normalized not in seen:
+                aliases.append(alias)
+                seen.add(normalized)
+        return aliases
+
+    @staticmethod
+    def _tvdb_media_id(info: dict[str, object]) -> Optional[str]:
+        """从不同形态的 TVDB 响应中提取纯数字来源 ID。"""
+        raw_id = info.get("tvdb_id") or info.get("id")
+        if raw_id is None:
+            return None
+        value = str(raw_id).rsplit("-", 1)[-1]
+        return value if value.isdigit() else None
+
+    def get_media_auxiliary_info(
+            self,
+            mediainfo: MediaInfo,
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> list[MediaInfo]:
+        """从 TVDB 补充电视剧别名，不向主媒体写入 TVDB 专用字段。"""
+        if (
+                not mediainfo
+                or mediainfo.type != MediaType.TV
+                or not is_media_source_enabled(media_source, MediaSource.TVDB)
+        ):
+            return []
+        del metainfo
+        if (
+                mediainfo.media_source == MediaSource.TVDB
+                and str(mediainfo.media_id or "").isdigit()
+        ):
+            info = self.tvdb_info(int(mediainfo.media_id))
+            candidates = [info] if info else []
+        else:
+            candidates = self.search_tvdb(mediainfo.title)
+        target_names = {
+            " ".join(str(name).casefold().split())
+            for name in [mediainfo.title, *(mediainfo.names or [])]
+            if name
+        }
+        for info in candidates:
+            candidate_year = str(
+                info.get("year")
+                or info.get("firstAired")
+                or info.get("first_air_time")
+                or ""
+            )[:4]
+            if mediainfo.year and candidate_year and str(mediainfo.year) != candidate_year:
+                continue
+            aliases = self._tvdb_aliases(info)
+            normalized_aliases = {" ".join(alias.casefold().split()) for alias in aliases}
+            if not target_names.intersection(normalized_aliases):
+                continue
+            media_id = self._tvdb_media_id(info)
+            if not media_id or not aliases:
+                continue
+            return [MediaInfo(
+                media_source=MediaSource.TVDB,
+                media_id=media_id,
+                type=MediaType.TV,
+                title=aliases[0],
+                year=str(info.get("year")) if info.get("year") else mediainfo.year,
+                names=aliases,
+            )]
+        return []
+
+    async def async_get_media_auxiliary_info(
+            self,
+            mediainfo: MediaInfo,
+            media_source: Optional[MediaSourceSelection] = None,
+            metainfo: Optional[MetaBase] = None,
+    ) -> list[MediaInfo]:
+        """在线程池中执行 TVDB 同步附加信息查询。"""
+        return cast(
+            list[MediaInfo],
+            await run_in_threadpool(
+                self.get_media_auxiliary_info,
+                mediainfo=mediainfo,
+                media_source=media_source,
+                metainfo=metainfo,
+            ),
+        )
+
     def clear_cache(self):
         """
         清除缓存

app/runtime/extensions/module/contracts.py

@@ -89,6 +89,13 @@ _METHOD_CONTRACTS = {
         aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
         required_parameters=("meta", "media_source"),
     ),
+    "get_media_auxiliary_info": ModuleMethodContract(
+        family="media-recognition", input_contract="MediaAuxiliaryInfoRequest",
+        result_contract="list[MediaInfo]", result_shape=ModuleResultShape.LIST,
+        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
+        required_parameters=("mediainfo", "media_source", "metainfo"),
+        plugin_short_circuit=False,
+    ),
     "obtain_images": ModuleMethodContract(family="media-recognition", input_contract="MediaInfo", result_contract="MediaInfo | None", aggregation=ModuleResultAggregation.PIPELINE_RELAY, required_parameters=("mediainfo",)),
     "media_category": ModuleMethodContract(family="media-recognition", input_contract="MediaCategoryRequest", result_contract="dict[str, list] | None", result_shape=ModuleResultShape.MAPPING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY),
     "mediaserver_items": ModuleMethodContract(family="media-server", input_contract="MediaServerItemsRequest", result_contract="Iterable[MediaServerItem] | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "library_id", "start_index", "limit")),
@@ -248,6 +255,7 @@ _METHOD_CONTRACTS.update({
     "async_match_tmdbinfo": _METHOD_CONTRACTS["match_tmdbinfo"],
     "async_update_recognize_cache": _METHOD_CONTRACTS["update_recognize_cache"],
     "async_search_medias": _METHOD_CONTRACTS["search_medias"],
+    "async_get_media_auxiliary_info": _METHOD_CONTRACTS["get_media_auxiliary_info"],
     "async_obtain_images": _METHOD_CONTRACTS["obtain_images"],
     "async_movie_hot": _METHOD_CONTRACTS["movie_hot"],
     "async_movie_showing": _METHOD_CONTRACTS["movie_showing"],
@@ -592,9 +600,9 @@ def _infer_observed_family(method: str) -> str:
     )):
         return "music"
     if method.startswith((
-        "async_match_", "async_obtain_images", "async_recognize_media",
+        "async_get_media_auxiliary_info", "async_match_", "async_obtain_images", "async_recognize_media",
         "async_update_recognize_cache", "match_", "obtain_images",
-        "recognize_media", "update_recognize_cache",
+        "get_media_auxiliary_info", "recognize_media", "update_recognize_cache",
     )):
         return "media-recognition"
     if method.startswith((

app/startup/composition/configuration.py

@@ -139,6 +139,7 @@ def build_chain_runtime_config(settings: Settings) -> ChainRuntimeConfig:
         ai_recommend_user_preference=settings.AI_RECOMMEND_USER_PREFERENCE,
         max_search_name_limit=settings.MAX_SEARCH_NAME_LIMIT,
         search_multiple_name=settings.SEARCH_MULTIPLE_NAME,
+        search_source=settings.SEARCH_SOURCE,
         search_threadpool_size=settings.CONF.threadpool,
         transfer_threads=settings.TRANSFER_THREADS,
         transfer_failure_notification_aggregation=(