feat: 统一音乐识别与影视共享上报，优化相关参数处理

app/chain/__init__.py

@@ -14,7 +14,7 @@ from transmission_rpc import File
 
 from app.core.cache import FileCache, AsyncFileCache, fresh, async_fresh
 from app.core.config import settings
-from app.core.context import Context, MediaInfo, MusicInfo, SubtitleInfo, TorrentInfo
+from app.core.context import Context, MediaInfo, SubtitleInfo, TorrentInfo
 from app.core.event import EventManager
 from app.core.meta import MetaBase
 from app.core.module import ModuleManager
@@ -705,10 +705,8 @@ class ChainBase(metaclass=ABCMeta):
                 **module_kwargs,
             )
         if mediainfo:
-            # 音乐识别结果不参与影视共享上报
+            # 电影、电视剧、音乐统一上报；音乐的 tmdb 等字段恒为 None，身份取数据源原生 ID
-            if isinstance(mediainfo, MusicInfo):
+            if not getattr(mediainfo, "recognize_cache_hit", False):
-                return mediainfo
-            if not mediainfo.recognize_cache_hit:
                 MoviePilotServerHelper.report_recognize_share(
                     meta=meta,
                     mediainfo=mediainfo,
@@ -716,7 +714,7 @@ class ChainBase(metaclass=ABCMeta):
                 )
             return mediainfo
 
-        if not source and mtype != MediaType.MUSIC and self._can_use_media_recognize_share(
+        if not source and self._can_use_media_recognize_share(
                 share_query_meta, tmdbid, doubanid, bangumiid, anilistid
         ):
             shared_cache_meta = self._snapshot_recognize_cache_meta(meta)
@@ -818,10 +816,8 @@ class ChainBase(metaclass=ABCMeta):
                 **module_kwargs,
             )
         if mediainfo:
-            # 音乐识别结果不参与影视共享上报
+            # 电影、电视剧、音乐统一上报；音乐的 tmdb 等字段恒为 None，身份取数据源原生 ID
-            if isinstance(mediainfo, MusicInfo):
+            if not getattr(mediainfo, "recognize_cache_hit", False):
-                return mediainfo
-            if not mediainfo.recognize_cache_hit:
                 await MoviePilotServerHelper.async_report_recognize_share(
                     meta=meta,
                     mediainfo=mediainfo,
@@ -829,7 +825,7 @@ class ChainBase(metaclass=ABCMeta):
                 )
             return mediainfo
 
-        if not source and mtype != MediaType.MUSIC and self._can_use_media_recognize_share(
+        if not source and self._can_use_media_recognize_share(
                 share_query_meta, tmdbid, doubanid, bangumiid, anilistid
         ):
             shared_cache_meta = self._snapshot_recognize_cache_meta(meta)

app/helper/server.py

@@ -2,12 +2,12 @@ import json
 import platform
 from pathlib import Path
 from threading import Thread
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple, Union
 from urllib.parse import parse_qs, quote, urlparse, urlsplit
 
 from app.core.cache import cached
 from app.core.config import settings
-from app.core.context import MediaInfo
+from app.core.context import MediaInfo, MusicInfo
 from app.core.meta import MetaBase
 from app.db.subscribe_oper import SubscribeOper
 from app.db.systemconfig_oper import SystemConfigOper
@@ -1366,11 +1366,11 @@ class MoviePilotServerHelper:
     def report_recognize_share(
             cls,
             meta: Optional[MetaBase],
-            mediainfo: Optional[MediaInfo],
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]],
             keyword_meta: Optional[MetaBase] = None,
     ) -> bool:
         """
-        上报共享识别结果。
+        上报共享识别结果，电影、电视剧、音乐共用。
         """
         if not settings.MEDIA_RECOGNIZE_SHARE:
             return False
@@ -1388,11 +1388,11 @@ class MoviePilotServerHelper:
     async def async_report_recognize_share(
             cls,
             meta: Optional[MetaBase],
-            mediainfo: Optional[MediaInfo],
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]],
             keyword_meta: Optional[MetaBase] = None,
     ) -> bool:
         """
-        异步上报共享识别结果。
+        异步上报共享识别结果，电影、电视剧、音乐共用。
         """
         if not settings.MEDIA_RECOGNIZE_SHARE:
             return False
@@ -1409,7 +1409,7 @@ class MoviePilotServerHelper:
     @classmethod
     def to_recognize_params(cls, item: Optional[dict]) -> Optional[dict]:
         """
-        将服务端返回的共享识别结果转成本地识别参数。
+        将服务端返回的共享识别结果转成本地识别参数，音乐仅携带数据源原生 ID。
         """
         if not isinstance(item, dict):
             return None
@@ -1461,13 +1461,15 @@ class MoviePilotServerHelper:
         统一媒体类型，兼容枚举、中文值和 agent 风格字符串。
         """
         normalized = media_type_to_agent(media_type)
-        if normalized in {"movie", "tv"}:
+        if normalized in {"movie", "tv", "music"}:
             return normalized
         if isinstance(media_type, str):
             if media_type == MediaType.MOVIE.value:
                 return "movie"
             if media_type == MediaType.TV.value:
                 return "tv"
+            if media_type == MediaType.MUSIC.value:
+                return "music"
         return None
 
     @staticmethod
@@ -1495,9 +1497,10 @@ class MoviePilotServerHelper:
         media_type = cls._normalize_media_type(mtype)
         if media_type:
             return media_type
-        if mediainfo and mediainfo.type in {MediaType.MOVIE, MediaType.TV}:
+        shareable_types = {MediaType.MOVIE, MediaType.TV, MediaType.MUSIC}
+        if mediainfo and mediainfo.type in shareable_types:
             return mediainfo.type.to_agent()
-        if meta and meta.type in {MediaType.MOVIE, MediaType.TV}:
+        if meta and meta.type in shareable_types:
             return meta.type.to_agent()
         if meta and (meta.begin_season is not None or meta.begin_episode is not None):
             return "tv"
@@ -1566,11 +1569,11 @@ class MoviePilotServerHelper:
     def _build_recognize_report_payload(
             cls,
             meta: Optional[MetaBase],
-            mediainfo: Optional[MediaInfo],
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]],
             keyword_meta: Optional[MetaBase] = None,
     ) -> Optional[dict]:
         """
-        组装共享识别上报载荷。
+        组装共享识别上报载荷，电影、电视剧、音乐共用同一结构。
         """
         if not meta or not mediainfo:
             return None

tests/test_media_recognize_share.py

@@ -1,69 +1,56 @@
-import asyncio
+"""共享媒体识别链路测试。
-import sys
-import unittest
-from types import ModuleType
-from unittest.mock import AsyncMock, patch
 
-sys.modules.setdefault("qbittorrentapi", ModuleType("qbittorrentapi"))
+覆盖本地识别成功后上报共享识别、本地识别失败后回查共享识别并二次识别、
-setattr(sys.modules["qbittorrentapi"], "TorrentFilesList", list)
+共享识别成功后回填本地缓存、音乐识别上报/查询载荷，以及命中缓存不重复上报等场景。
-sys.modules.setdefault("transmission_rpc", ModuleType("transmission_rpc"))
+"""
-setattr(sys.modules["transmission_rpc"], "File", object)
+import asyncio
-sys.modules.setdefault("psutil", ModuleType("psutil"))
+from unittest.mock import AsyncMock, Mock, patch
 
 from app.chain import ChainBase
-from app.core.context import MediaInfo
-from app.core.meta import MetaBase
-from app.core.metainfo import MetaInfo
 from app.chain.media import MediaChain
+from app.core.context import MediaInfo, MusicInfo
+from app.core.meta import MetaBase, MetaMusic
+from app.core.metainfo import MetaInfo
 from app.helper.server import MoviePilotServerHelper
 from app.schemas.types import MediaType
 
 
-class TestMediaRecognizeShare(unittest.TestCase):
+def _build_meta(name: str, media_type: MediaType = MediaType.UNKNOWN) -> MetaBase:
-    @classmethod
+    """构造测试用元数据。"""
-    def setUpClass(cls):
-        cls.chain = ChainBase()
-        cls.media_chain = MediaChain()
-
-    @staticmethod
-    def _build_meta(name: str, media_type: MediaType = MediaType.UNKNOWN) -> MetaBase:
-        """
-        构造测试用元数据
-        """
     meta = MetaBase(name)
     meta.name = name
     meta.type = media_type
     return meta
 
-    def test_report_shared_result_after_local_recognize_success(self):
+
-        """
+def test_report_shared_result_after_local_recognize_success():
-        本地识别成功后应上报共享识别结果
+    """本地识别成功后应上报共享识别结果。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("测试电影", MediaType.MOVIE)
+    meta = _build_meta("测试电影", MediaType.MOVIE)
     mediainfo = MediaInfo(title="测试电影", year="2024", tmdb_id=100, type=MediaType.MOVIE)
 
-        with patch.object(self.chain, "run_module", return_value=mediainfo) as run_module, patch(
+    with patch.object(chain, "run_module", return_value=mediainfo) as run_module, patch(
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=True,
     ) as report_mock, patch(
         "app.chain.MoviePilotServerHelper.query_recognize_share"
     ) as query_mock:
-            result = self.chain.recognize_media(meta=meta, cache=False)
+        result = chain.recognize_media(meta=meta, cache=False)
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     run_module.assert_called_once()
     report_mock.assert_called_once_with(meta=meta, mediainfo=mediainfo, keyword_meta=meta)
     query_mock.assert_not_called()
 
-    def test_query_shared_result_when_local_recognize_failed(self):
+
-        """
+def test_query_shared_result_when_local_recognize_failed():
-        本地识别失败后应回查共享识别结果，并按共享ID再次识别
+    """本地识别失败后应回查共享识别结果，并按共享ID再次识别。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("测试剧集")
+    meta = _build_meta("测试剧集")
     shared_media = MediaInfo(title="测试剧集", year="2024", tmdb_id=200, type=MediaType.TV)
 
     with patch.object(
-            self.chain,
+        chain,
         "run_module",
         side_effect=[None, shared_media],
     ) as run_module, patch(
@@ -82,30 +69,30 @@ class TestMediaRecognizeShare(unittest.TestCase):
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=False,
     ), patch.object(
-            self.chain,
+        chain,
         "_update_local_recognize_cache",
     ):
-            result = self.chain.recognize_media(meta=meta, cache=False)
+        result = chain.recognize_media(meta=meta, cache=False)
 
-        self.assertIs(result, shared_media)
+    assert result is shared_media
-        self.assertEqual(run_module.call_count, 2)
+    assert run_module.call_count == 2
     query_mock.assert_called_once_with(meta=meta, mtype=None, keyword_meta=meta)
     second_call = run_module.call_args_list[1]
-        self.assertEqual(second_call.kwargs["tmdbid"], 200)
+    assert second_call.kwargs["tmdbid"] == 200
-        self.assertEqual(second_call.kwargs["mtype"], MediaType.TV)
+    assert second_call.kwargs["mtype"] == MediaType.TV
-        self.assertIsNone(meta.begin_season)
+    assert meta.begin_season is None
 
-    def test_async_query_shared_result_when_local_recognize_failed(self):
+
-        """
+def test_async_query_shared_result_when_local_recognize_failed():
-        异步识别失败后也应回查共享识别结果
+    """异步识别失败后也应回查共享识别结果。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("测试异步剧集")
+    meta = _build_meta("测试异步剧集")
     shared_media = MediaInfo(title="测试异步剧集", year="2025", tmdb_id=300, type=MediaType.TV)
     async_run_module = AsyncMock(side_effect=[None, shared_media])
 
     async def runner():
         with patch.object(
-                self.chain,
+            chain,
             "async_run_module",
             async_run_module,
         ), patch(
@@ -124,26 +111,26 @@ class TestMediaRecognizeShare(unittest.TestCase):
             "app.chain.MoviePilotServerHelper.async_report_recognize_share",
             AsyncMock(return_value=False),
         ), patch.object(
-                self.chain,
+            chain,
             "_async_update_local_recognize_cache",
             AsyncMock(),
         ) as backfill_mock:
-                result = await self.chain.async_recognize_media(meta=meta, cache=False)
+            result = await chain.async_recognize_media(meta=meta, cache=False)
         return result, query_mock, backfill_mock
 
     result, query_mock, backfill_mock = asyncio.run(runner())
 
-        self.assertIs(result, shared_media)
+    assert result is shared_media
-        self.assertEqual(async_run_module.await_count, 2)
+    assert async_run_module.await_count == 2
     query_mock.assert_awaited_once_with(meta=meta, mtype=None, keyword_meta=meta)
     backfill_mock.assert_awaited_once()
-        self.assertIsNone(meta.begin_season)
+    assert meta.begin_season is None
 
-    def test_backfill_local_cache_after_shared_recognize_success(self):
+
-        """
+def test_backfill_local_cache_after_shared_recognize_success():
-        共享识别后二次本地识别成功时，应回填原始名称对应的本地识别缓存。
+    """共享识别后二次本地识别成功时，应回填原始名称对应的本地识别缓存。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("测试缓存回填", MediaType.MOVIE)
+    meta = _build_meta("测试缓存回填", MediaType.MOVIE)
     shared_media = MediaInfo(
         title="测试缓存回填",
         year="2024",
@@ -154,7 +141,7 @@ class TestMediaRecognizeShare(unittest.TestCase):
     )
 
     with patch.object(
-            self.chain,
+        chain,
         "run_module",
         side_effect=[None, shared_media, None],
     ) as run_module_mock, patch(
@@ -173,22 +160,21 @@ class TestMediaRecognizeShare(unittest.TestCase):
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=False,
     ):
-            result = self.chain.recognize_media(meta=meta, cache=False)
+        result = chain.recognize_media(meta=meta, cache=False)
 
-        self.assertIs(result, shared_media)
+    assert result is shared_media
-        self.assertEqual(run_module_mock.call_count, 3)
+    assert run_module_mock.call_count == 3
     update_call = run_module_mock.call_args_list[2]
-        self.assertEqual(update_call.args[0], "update_recognize_cache")
+    assert update_call.args[0] == "update_recognize_cache"
-        self.assertIsNot(update_call.kwargs["meta"], meta)
+    assert update_call.kwargs["meta"] is not meta
-        self.assertEqual(update_call.kwargs["meta"].name, meta.name)
+    assert update_call.kwargs["meta"].name == meta.name
-        self.assertEqual(update_call.kwargs["meta"].type, meta.type)
+    assert update_call.kwargs["meta"].type == meta.type
-        self.assertIs(update_call.kwargs["mediainfo"], shared_media)
+    assert update_call.kwargs["mediainfo"] is shared_media
 
-    def test_query_and_report_prefer_original_name_keyword(self):
+
-        """
+def test_query_and_report_prefer_original_name_keyword():
-        查询和上报共享识别时应优先使用未应用识别词的识别名称
+    """查询和上报共享识别时应优先使用未应用识别词的识别名称。"""
-        """
+    meta = _build_meta("应用识别词后的名称", MediaType.TV)
-        meta = self._build_meta("应用识别词后的名称", MediaType.TV)
     meta.original_name = "未应用识别词的名称"
     meta.year = "2024"
     meta.begin_season = 1
@@ -203,18 +189,17 @@ class TestMediaRecognizeShare(unittest.TestCase):
     query_params = MoviePilotServerHelper._build_recognize_query_params(meta=meta)
     report_payload = MoviePilotServerHelper._build_recognize_report_payload(meta=meta, mediainfo=mediainfo)
 
-        self.assertEqual(query_params["keyword"], "未应用识别词的名称")
+    assert query_params["keyword"] == "未应用识别词的名称"
-        self.assertEqual(report_payload["keyword"], "未应用识别词的名称")
+    assert report_payload["keyword"] == "未应用识别词的名称"
 
-    def test_query_and_report_can_use_distinct_keyword_meta(self):
+
-        """
+def test_query_and_report_can_use_distinct_keyword_meta():
-        共享识别应允许用原始关键字上报，同时保留辅助识别后的年份/季信息。
+    """共享识别应允许用原始关键字上报，同时保留辅助识别后的年份/季信息。"""
-        """
+    meta = _build_meta("辅助识别后的名称", MediaType.TV)
-        meta = self._build_meta("辅助识别后的名称", MediaType.TV)
     meta.year = "2024"
     meta.begin_season = 2
 
-        keyword_meta = self._build_meta("辅助识别前的名称", MediaType.UNKNOWN)
+    keyword_meta = _build_meta("辅助识别前的名称", MediaType.UNKNOWN)
     keyword_meta.original_name = "辅助识别前的名称"
 
     mediainfo = MediaInfo(
@@ -236,16 +221,17 @@ class TestMediaRecognizeShare(unittest.TestCase):
         keyword_meta=keyword_meta,
     )
 
-        self.assertEqual(query_params["keyword"], "辅助识别前的名称")
+    assert query_params["keyword"] == "辅助识别前的名称"
-        self.assertEqual(query_params["year"], "2024")
+    assert query_params["year"] == "2024"
-        self.assertEqual(query_params["season"], 2)
+    assert query_params["season"] == 2
-        self.assertEqual(report_payload["keyword"], "辅助识别前的名称")
+    assert report_payload["keyword"] == "辅助识别前的名称"
-        self.assertEqual(report_payload["year"], "2024")
+    assert report_payload["year"] == "2024"
-        self.assertEqual(report_payload["season"], 2)
+    assert report_payload["season"] == 2
 
-    def test_query_and_report_preserve_special_season_zero(self):
+
+def test_query_and_report_preserve_special_season_zero():
     """共享识别查询和上报都必须保留显式特别季。"""
-        meta = self._build_meta("测试剧特别篇", MediaType.TV)
+    meta = _build_meta("测试剧特别篇", MediaType.TV)
     meta.begin_season = 0
     mediainfo = MediaInfo(title="测试剧", tmdb_id=402, type=MediaType.TV, season=0)
 
@@ -255,52 +241,54 @@ class TestMediaRecognizeShare(unittest.TestCase):
         mediainfo=mediainfo,
     )
 
-        self.assertEqual(query_params["season"], 0)
+    assert query_params["season"] == 0
-        self.assertEqual(report_payload["season"], 0)
+    assert report_payload["season"] == 0
 
-    def test_plugin_recognize_number_parser_preserves_zero(self):
+
+def test_plugin_recognize_number_parser_preserves_zero():
     """插件辅助识别应同时接受整数和字符串形式的季 0。"""
-        self.assertEqual(self.media_chain._parse_recognize_event_number(0), 0)
+    media_chain = MediaChain()
-        self.assertEqual(self.media_chain._parse_recognize_event_number("0"), 0)
+    assert media_chain._parse_recognize_event_number(0) == 0
-        self.assertIsNone(self.media_chain._parse_recognize_event_number(None))
+    assert media_chain._parse_recognize_event_number("0") == 0
-        self.assertIsNone(self.media_chain._parse_recognize_event_number("invalid"))
+    assert media_chain._parse_recognize_event_number(None) is None
+    assert media_chain._parse_recognize_event_number("invalid") is None
 
-    def test_report_shared_result_with_distinct_keyword_meta(self):
+
-        """
+def test_report_shared_result_with_distinct_keyword_meta():
-        辅助识别成功后应按辅助前名称上报共享结果。
+    """辅助识别成功后应按辅助前名称上报共享结果。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("辅助识别后的名称", MediaType.TV)
+    meta = _build_meta("辅助识别后的名称", MediaType.TV)
     meta.year = "2024"
     meta.begin_season = 1
-        share_meta = self._build_meta("辅助识别前的名称", MediaType.UNKNOWN)
+    share_meta = _build_meta("辅助识别前的名称", MediaType.UNKNOWN)
     share_meta.original_name = "辅助识别前的名称"
     mediainfo = MediaInfo(title="测试剧集", year="2024", tmdb_id=402, type=MediaType.TV)
 
-        with patch.object(self.chain, "run_module", return_value=mediainfo), patch(
+    with patch.object(chain, "run_module", return_value=mediainfo), patch(
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=True,
     ) as report_mock:
-            result = self.chain.recognize_media(meta=meta, share_meta=share_meta, cache=False)
+        result = chain.recognize_media(meta=meta, share_meta=share_meta, cache=False)
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     report_mock.assert_called_once_with(
         meta=meta,
         mediainfo=mediainfo,
         keyword_meta=share_meta,
     )
 
-    def test_query_shared_result_with_distinct_keyword_meta(self):
+
-        """
+def test_query_shared_result_with_distinct_keyword_meta():
-        本地识别失败后应按辅助前名称回查共享结果。
+    """本地识别失败后应按辅助前名称回查共享结果。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("辅助识别后的名称", MediaType.TV)
+    meta = _build_meta("辅助识别后的名称", MediaType.TV)
     meta.year = "2024"
-        share_meta = self._build_meta("辅助识别前的名称", MediaType.UNKNOWN)
+    share_meta = _build_meta("辅助识别前的名称", MediaType.UNKNOWN)
     share_meta.original_name = "辅助识别前的名称"
     shared_media = MediaInfo(title="测试剧集", year="2024", tmdb_id=403, type=MediaType.TV)
 
     with patch.object(
-            self.chain,
+        chain,
         "run_module",
         side_effect=[None, shared_media],
     ), patch(
@@ -319,54 +307,54 @@ class TestMediaRecognizeShare(unittest.TestCase):
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=False,
     ), patch.object(
-            self.chain,
+        chain,
         "_update_local_recognize_cache",
     ):
-            result = self.chain.recognize_media(
+        result = chain.recognize_media(
             meta=meta,
             share_meta=share_meta,
             cache=False,
         )
 
-        self.assertIs(result, shared_media)
+    assert result is shared_media
     query_mock.assert_called_once_with(
         meta=meta,
         mtype=MediaType.TV,
         keyword_meta=share_meta,
     )
 
-    def test_skip_report_when_local_recognize_hits_cache(self):
+
-        """
+def test_skip_report_when_local_recognize_hits_cache():
-        本地识别命中缓存时不应上报共享识别
+    """本地识别命中缓存时不应上报共享识别。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("缓存电影", MediaType.MOVIE)
+    meta = _build_meta("缓存电影", MediaType.MOVIE)
     mediainfo = MediaInfo(title="缓存电影", year="2024", tmdb_id=500, type=MediaType.MOVIE)
     mediainfo.recognize_cache_hit = True
 
-        with patch.object(self.chain, "run_module", return_value=mediainfo) as run_module, patch(
+    with patch.object(chain, "run_module", return_value=mediainfo) as run_module, patch(
         "app.chain.MoviePilotServerHelper.report_recognize_share",
         return_value=True,
     ) as report_mock, patch(
         "app.chain.MoviePilotServerHelper.query_recognize_share"
     ) as query_mock:
-            result = self.chain.recognize_media(meta=meta)
+        result = chain.recognize_media(meta=meta)
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     run_module.assert_called_once()
     report_mock.assert_not_called()
     query_mock.assert_not_called()
 
-    def test_async_skip_report_when_local_recognize_hits_cache(self):
+
-        """
+def test_async_skip_report_when_local_recognize_hits_cache():
-        异步本地识别命中缓存时不应上报共享识别
+    """异步本地识别命中缓存时不应上报共享识别。"""
-        """
+    chain = ChainBase()
-        meta = self._build_meta("缓存剧集", MediaType.TV)
+    meta = _build_meta("缓存剧集", MediaType.TV)
     mediainfo = MediaInfo(title="缓存剧集", year="2025", tmdb_id=600, type=MediaType.TV)
     mediainfo.recognize_cache_hit = True
 
     async def runner():
         with patch.object(
-                self.chain,
+            chain,
             "async_run_module",
             AsyncMock(return_value=mediainfo),
         ) as async_run_module, patch(
@@ -376,79 +364,79 @@ class TestMediaRecognizeShare(unittest.TestCase):
             "app.chain.MoviePilotServerHelper.async_query_recognize_share",
             AsyncMock(),
         ) as query_mock:
-                result = await self.chain.async_recognize_media(meta=meta)
+            result = await chain.async_recognize_media(meta=meta)
         return result, async_run_module, report_mock, query_mock
 
     result, async_run_module, report_mock, query_mock = asyncio.run(runner())
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     async_run_module.assert_awaited_once()
     report_mock.assert_not_awaited()
     query_mock.assert_not_awaited()
 
-    def test_recognize_by_meta_can_skip_obtain_images(self):
+
-        """
+def test_recognize_by_meta_can_skip_obtain_images():
-        标题识别可显式关闭图片拉取。
+    """标题识别可显式关闭图片拉取。"""
-        """
+    media_chain = MediaChain()
     meta = MetaInfo("测试电影")
     mediainfo = MediaInfo(title="测试电影", year="2024", tmdb_id=404, type=MediaType.MOVIE)
 
     with patch.object(
-            self.media_chain,
+        media_chain,
         "recognize_media",
         return_value=mediainfo,
     ) as recognize_mock, patch.object(
-            self.media_chain,
+        media_chain,
         "obtain_images",
     ) as obtain_images_mock:
-            result = self.media_chain.recognize_by_meta(meta, obtain_images=False)
+        result = media_chain.recognize_by_meta(meta, obtain_images=False)
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     recognize_mock.assert_called_once()
     obtain_images_mock.assert_not_called()
 
-    def test_recognize_by_meta_reports_with_original_keyword_after_plugin_help(self):
+
-        """
+def test_recognize_by_meta_reports_with_original_keyword_after_plugin_help():
-        辅助识别后应继续使用辅助前关键字进行共享上报。
+    """辅助识别后应继续使用辅助前关键字进行共享上报。"""
-        """
+    media_chain = MediaChain()
     meta = MetaInfo("辅助前名称")
     plugin_media = MediaInfo(title="辅助后名称", year="2024", tmdb_id=405, type=MediaType.TV)
 
     with patch.object(
-            self.media_chain,
+        media_chain,
         "select_recognize_source",
         side_effect=lambda **kwargs: kwargs["plugin_fn"](),
     ), patch.object(
-            self.media_chain,
+        media_chain,
         "recognize_help",
         return_value=plugin_media,
     ) as recognize_help_mock, patch.object(
-            self.media_chain,
+        media_chain,
         "obtain_images",
     ):
-            result = self.media_chain.recognize_by_meta(meta, obtain_images=False)
+        result = media_chain.recognize_by_meta(meta, obtain_images=False)
 
-        self.assertIs(result, plugin_media)
+    assert result is plugin_media
-        self.assertEqual(recognize_help_mock.call_args.kwargs["share_meta"].name, "辅助前名称")
+    assert recognize_help_mock.call_args.kwargs["share_meta"].name == "辅助前名称"
 
-    def test_async_recognize_by_meta_can_skip_obtain_images(self):
+
-        """
+def test_async_recognize_by_meta_can_skip_obtain_images():
-        异步标题识别可显式关闭图片拉取。
+    """异步标题识别可显式关闭图片拉取。"""
-        """
+    media_chain = MediaChain()
     meta = MetaInfo("测试异步电影")
     mediainfo = MediaInfo(title="测试异步电影", year="2025", tmdb_id=406, type=MediaType.MOVIE)
 
     async def runner():
         with patch.object(
-                self.media_chain,
+            media_chain,
             "async_recognize_media",
             AsyncMock(return_value=mediainfo),
         ) as recognize_mock, patch.object(
-                self.media_chain,
+            media_chain,
             "async_obtain_images",
             AsyncMock(),
         ) as obtain_images_mock:
-                result = await self.media_chain.async_recognize_by_meta(
+            result = await media_chain.async_recognize_by_meta(
                 meta,
                 obtain_images=False,
             )
@@ -456,6 +444,144 @@ class TestMediaRecognizeShare(unittest.TestCase):
 
     result, recognize_mock, obtain_images_mock = asyncio.run(runner())
 
-        self.assertIs(result, mediainfo)
+    assert result is mediainfo
     recognize_mock.assert_awaited_once()
-        obtain_images_mock.assert_not_awaited()
+    obtain_images_mock.assert_not_called()
+
+
+def _music_info() -> MusicInfo:
+    """构造带远端身份的标准音乐信息。"""
+    return MusicInfo(
+        source="musicbrainz",
+        media_id="recording-1",
+        title="晴天",
+        artists=["周杰伦"],
+        album="叶惠美",
+        year=2003,
+    )
+
+
+def test_music_report_payload_includes_source_and_media_id():
+    """音乐上报载荷应携带 music 类型与数据源原生身份，其余媒体 ID 恒为 None。"""
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], album="叶惠美", year=2003)
+    payload = MoviePilotServerHelper._build_recognize_report_payload(
+        meta=meta,
+        mediainfo=_music_info(),
+    )
+
+    assert payload["keyword"] == "晴天"
+    assert payload["type"] == "music"
+    assert payload["title"] == "晴天"
+    assert payload["year"] == "2003"
+    assert payload["season"] is None
+    assert payload["tmdbid"] is None
+    assert payload["doubanid"] is None
+    assert payload["media_source"] == "musicbrainz"
+    assert payload["media_id"] == "recording-1"
+
+
+def test_music_report_payload_skips_fallback_without_remote_identity():
+    """无远端身份的兜底音乐结果不应上报。"""
+    meta = MetaMusic(title="未知曲目", artists=["未知艺术家"])
+    fallback = MusicInfo(title="未知曲目", artists=["未知艺术家"])
+    payload = MoviePilotServerHelper._build_recognize_report_payload(
+        meta=meta,
+        mediainfo=fallback,
+    )
+
+    assert payload is None
+
+
+def test_music_query_params_build_for_music_type():
+    """音乐查询参数应携带 music 类型、年份且不包含季。"""
+    meta = MetaMusic(title="晴天", year=2003)
+    keyword_meta = MetaMusic(title="晴天")
+
+    params = MoviePilotServerHelper._build_recognize_query_params(
+        meta=meta,
+        mtype=MediaType.MUSIC,
+        keyword_meta=keyword_meta,
+    )
+
+    assert params["keyword"] == "晴天"
+    assert params["type"] == "music"
+    assert params["year"] == "2003"
+    assert "season" not in params
+
+
+def test_chain_recognize_media_reports_music_share_result():
+    """音乐识别成功且有远端身份时，应与影视一样走统一共享上报。"""
+    chain = ChainBase()
+    meta = MetaMusic(title="晴天", artists=["周杰伦"], year=2003)
+    music = _music_info()
+
+    with patch.object(chain, "run_module", return_value=music), patch(
+        "app.chain.MoviePilotServerHelper.report_recognize_share",
+        return_value=True,
+    ) as report_mock, patch(
+        "app.chain.MoviePilotServerHelper.query_recognize_share"
+    ) as query_mock:
+        result = chain.recognize_media(meta=meta, cache=False)
+
+    assert result is music
+    report_mock.assert_called_once_with(meta=meta, mediainfo=music, keyword_meta=meta)
+    query_mock.assert_not_called()
+
+
+def test_chain_recognize_media_queries_music_share_when_local_failed():
+    """音乐本地识别失败后应回查共享识别并按数据源原生 ID 二次识别。"""
+    chain = ChainBase()
+    meta = MetaMusic(title="晴天", artists=["周杰伦"])
+    music = _music_info()
+
+    with patch.object(
+        chain,
+        "run_module",
+        side_effect=[None, music],
+    ) as run_module, patch(
+        "app.chain.MoviePilotServerHelper.query_recognize_share",
+        return_value={"type": "music", "media_source": "musicbrainz", "media_id": "recording-1"},
+    ), patch(
+        "app.chain.MoviePilotServerHelper.to_recognize_params",
+        return_value={
+            "mtype": MediaType.MUSIC,
+            "source": "musicbrainz",
+            "mediaid": "recording-1",
+            "tmdbid": None,
+            "doubanid": None,
+            "bangumiid": None,
+            "anilistid": None,
+            "season": None,
+        },
+    ), patch(
+        "app.chain.MoviePilotServerHelper.report_recognize_share",
+        return_value=False,
+    ), patch.object(
+        chain,
+        "_update_local_recognize_cache",
+    ):
+        result = chain.recognize_media(meta=meta, cache=False)
+
+    assert result is music
+    assert run_module.call_count == 2
+    second_call = run_module.call_args_list[1]
+    assert second_call.kwargs["mtype"] == MediaType.MUSIC
+    assert second_call.kwargs["source"] == "musicbrainz"
+    assert second_call.kwargs["mediaid"] == "recording-1"
+
+
+def test_chain_recognize_media_skips_music_report_for_fallback_result():
+    """兜底无远端身份的音乐结果不上报共享识别，由载荷构建返回空保证。"""
+    chain = ChainBase()
+    meta = MetaMusic(title="未知曲目", artists=["未知艺术家"])
+    fallback = MusicInfo(title="未知曲目", artists=["未知艺术家"])
+
+    with patch.object(chain, "run_module", return_value=fallback), patch(
+        "app.chain.MoviePilotServerHelper.recognize_report"
+    ) as report_mock, patch(
+        "app.chain.settings.MEDIA_RECOGNIZE_SHARE", True
+    ):
+        result = chain.recognize_media(meta=meta, cache=False)
+
+    assert result is fallback
+    report_mock.assert_not_called()

tests/test_music_recognize_routing.py

@@ -3,7 +3,7 @@
 覆盖 MediaChain 同步/异步 ``recognize_by_meta`` 与 ``recognize_by_path`` 按
 ``MetaMusic`` 路由到音乐模块，以及 MusicBrainz 模块 ``recognize_media`` /
 ``async_recognize_media`` 对音乐请求的详情、搜索匹配与兜底分支，ChainBase
-对 MusicInfo 结果短路返回（不参与影视共享上报）。
+对 MusicInfo 结果与影视统一走共享识别上报。
 """
 import asyncio
 from unittest.mock import AsyncMock, Mock, patch
@@ -148,8 +148,8 @@ def test_musicbrainz_module_async_recognize_media(monkeypatch):
     assert result is expected
 
 
-def test_chain_recognize_media_returns_musicinfo_without_shared_report():
+def test_chain_recognize_media_returns_musicinfo_and_reports_share():
-    """ChainBase.recognize_media 收到 MusicInfo 结果应直接返回，不触发影视共享上报。"""
+    """ChainBase.recognize_media 收到 MusicInfo 结果应与影视统一上报共享识别。"""
     expected = _music_info()
     chain = MediaChain()
     chain.run_module = Mock(return_value=expected)
@@ -158,22 +158,25 @@ def test_chain_recognize_media_returns_musicinfo_without_shared_report():
     ) as report_mock:
         result = chain.recognize_media(meta=MetaMusic(title="晴天"))
 
-    report_mock.assert_not_called()
+    report_mock.assert_called_once()
+    assert report_mock.call_args.kwargs["mediainfo"] is expected
     assert result is expected
 
 
-def test_chain_async_recognize_media_returns_musicinfo_without_shared_report():
+def test_chain_async_recognize_media_returns_musicinfo_and_reports_share():
-    """异步 ChainBase 收到 MusicInfo 结果应直接返回，不触发影视共享上报。"""
+    """异步 ChainBase 收到 MusicInfo 结果应与影视统一上报共享识别。"""
     expected = _music_info()
     chain = MediaChain()
     chain.async_run_module = AsyncMock(return_value=expected)
     with patch(
-        "app.helper.server.MoviePilotServerHelper.async_report_recognize_share"
+        "app.helper.server.MoviePilotServerHelper.async_report_recognize_share",
+        AsyncMock(),
     ) as report_mock:
         async def runner():
             return await chain.async_recognize_media(meta=MetaMusic(title="晴天"))
 
         result = asyncio.run(runner())
 
-    report_mock.assert_not_called()
+    report_mock.assert_awaited_once()
+    assert report_mock.call_args.kwargs["mediainfo"] is expected
     assert result is expected