MCP get_search_results 增加 include_labels 按需返回种子标签 (#6335)

让 Agent 在筛选命中标签时能按需查看 labels，默认不返回以免拉长上下文。

Co-authored-by: Cursor <cursoragent@cursor.com>

app/agent/tools/impl/_torrent_search_utils.py

@@ -131,6 +131,7 @@ def simplify_search_result(
     context: Context,
     index: int,
     include_description: bool = False,
+    include_labels: bool = False,
 ) -> dict:
     """
     精简单条搜索结果
@@ -138,6 +139,7 @@ def simplify_search_result(
     :param context: 搜索结果上下文
     :param index: 搜索结果在原始缓存中的序号
     :param include_description: 是否返回种子简介
+    :param include_labels: 是否返回种子标签
     :return: 精简后的搜索结果
     """
     simplified = {}
@@ -160,6 +162,8 @@ def simplify_search_result(
         }
         if include_description:
             simplified["torrent_info"]["description"] = torrent_info.description
+        if include_labels:
+            simplified["torrent_info"]["labels"] = torrent_info.labels or []
 
     if media_info:
         simplified["media_info"] = {

app/agent/tools/impl/get_search_results.py

@@ -42,6 +42,10 @@ class GetSearchResultsInput(BaseModel):
         False,
         description="Whether to include torrent descriptions in returned results",
     )
+    include_labels: Optional[bool] = Field(
+        False,
+        description="Whether to include torrent labels in returned results",
+    )
     show_filter_options: Optional[bool] = Field(
         False,
         description="Whether to return only optional filter options for re-checking available conditions",
@@ -79,6 +83,7 @@ class GetSearchResultsTool(MoviePilotTool):
         title_pattern: Optional[str] = None,
         content_pattern: Optional[str] = None,
         include_description: bool = False,
+        include_labels: bool = False,
         show_filter_options: bool = False,
         page: Optional[int] = 1,
         **kwargs,
@@ -96,6 +101,7 @@ class GetSearchResultsTool(MoviePilotTool):
         :param title_pattern: 仅匹配种子标题的正则表达式
         :param content_pattern: 匹配种子标题、简介和标签的正则表达式
         :param include_description: 是否在结果中返回种子简介
+        :param include_labels: 是否在结果中返回种子标签
         :param show_filter_options: 是否只返回可用筛选项
         :param page: 分页页码
         :param kwargs: 工具框架附加参数
@@ -103,7 +109,7 @@ class GetSearchResultsTool(MoviePilotTool):
         """
         page = max(1, page or 1)
         logger.info(
-            f"执行工具: {self.name}, 参数: site={site}, season={season}, free_state={free_state}, video_code={video_code}, edition={edition}, resolution={resolution}, release_group={release_group}, title_pattern={title_pattern}, content_pattern={content_pattern}, include_description={include_description}, show_filter_options={show_filter_options}, page={page}"
+            f"执行工具: {self.name}, 参数: site={site}, season={season}, free_state={free_state}, video_code={video_code}, edition={edition}, resolution={resolution}, release_group={release_group}, title_pattern={title_pattern}, content_pattern={content_pattern}, include_description={include_description}, include_labels={include_labels}, show_filter_options={show_filter_options}, page={page}"
         )
 
         try:
@@ -193,6 +199,7 @@ class GetSearchResultsTool(MoviePilotTool):
                     item,
                     index,
                     include_description=include_description,
+                    include_labels=include_labels,
                 )
                 for item, index in zip(page_items, page_indices)
             ]

docs/mcp-api.md

@@ -265,7 +265,7 @@ TMDB 缓存查询响应的 `data` 包含 `count`、`recognized`、`unrecognized`
 
 媒体相关 MCP 工具（如 `query_media_detail`、`search_torrents`、`query_library_exists`、`add_subscribe`、`transfer_file`）接受 `tmdb_id`/`tmdbid`、`douban_id`/`doubanid`、`bangumi_id`/`bangumiid`、`anilist_id`/`anilistid`，也接受 `media_source` + `media_id`。工具返回的媒体、订阅、下载和整理记录会同步带回可用的四种专用 ID 及通用主身份。
 
-`get_search_results` 可使用 `title_pattern` 对种子标题执行正则筛选，也可使用 `content_pattern` 联合匹配种子标题、简介和标签。`title_pattern` 保持仅匹配标题的兼容语义；需要在结果中查看种子简介时，传入 `include_description=true`。两种正则参数与站点、分辨率等结构化筛选条件同时传入时按 AND 关系组合。
+`get_search_results` 可使用 `title_pattern` 对种子标题执行正则筛选，也可使用 `content_pattern` 联合匹配种子标题、简介和标签。`title_pattern` 保持仅匹配标题的兼容语义；需要在结果中查看种子简介时，传入 `include_description=true`；需要查看种子标签时，传入 `include_labels=true`。两种正则参数与站点、分辨率等结构化筛选条件同时传入时按 AND 关系组合。
 
 #### Agent 自主定时任务工具
 

skills/moviepilot-cli/SKILL.md

@@ -103,8 +103,8 @@ Filter values must come from the `filter_options` returned by `search_torrents`
 Fetch results with selected filters:
 `moviepilot tool run get_search_results resolution='1080p,2160p' free_state='免费,50%'`
 
-To filter subtitle, audio, DIY, translation, or release notes that may appear outside the title, use `content_pattern`. It matches the torrent title, description, and labels while `title_pattern` continues to match the title only. Set `include_description=true` when the description is needed to explain why a result matched:
+To filter subtitle, audio, DIY, translation, or release notes that may appear outside the title, use `content_pattern`. It matches the torrent title, description, and labels while `title_pattern` continues to match the title only. Set `include_description=true` when the description is needed to explain why a result matched, and `include_labels=true` when the labels should be returned:
-`moviepilot tool run get_search_results content_pattern='特效字幕|国语|DIY' include_description=true`
+`moviepilot tool run get_search_results content_pattern='特效字幕|国语|DIY' include_description=true include_labels=true`
 
 If empty, tell the user which filter to relax and ask before retrying.
 

tests/test_agent_get_search_results_tool.py

@@ -54,6 +54,17 @@ def test_simplify_search_result_only_includes_description_when_requested():
     assert detailed_result["torrent_info"]["description"] == "简繁特效字幕"
 
 
+def test_simplify_search_result_only_includes_labels_when_requested():
+    """精简结果应按参数控制标签输出，避免默认增加上下文长度。"""
+    context = _build_context("Movie.2026.1080p", labels=["官译", "特效"])
+
+    default_result = simplify_search_result(context, 1)
+    detailed_result = simplify_search_result(context, 1, include_labels=True)
+
+    assert "labels" not in default_result["torrent_info"]
+    assert detailed_result["torrent_info"]["labels"] == ["官译", "特效"]
+
+
 def test_content_pattern_matches_title_description_and_labels():
     """内容正则应联合匹配标题、简介和标签，并可返回命中的简介。"""
     items = [