将所有agent工具的explanation字段改为可选

修复Pydantic验证错误：QueryTransferHistoryInput的explanation字段为必需，但用户未提供。
修改了74个工具文件，将explanation字段从必需改为可选，默认值为None。

app/agent/tools/impl/add_custom_filter_rule.py

@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class AddCustomFilterRuleInput(BaseModel):
     """新增自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     rule_id: str = Field(
         ...,
         description="Unique custom rule ID. Only letters and numbers are allowed.",

app/agent/tools/impl/add_download.py

@@ -22,7 +22,7 @@ from app.utils.crypto import HashUtils
 
 class AddDownloadInput(BaseModel):
     """添加下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     torrent_url: List[str] = Field(
         ...,
         description="One or more torrent_url values. Supports refs from get_search_results (`hash:id`) and magnet links."

app/agent/tools/impl/add_rule_group.py

@@ -23,10 +23,8 @@ from app.schemas.types import SystemConfigKey
 class AddRuleGroupInput(BaseModel):
     """新增过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     name: str = Field(..., description="New rule group name.")
     rule_string: str = Field(
         ...,

app/agent/tools/impl/add_subscribe.py

@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, MessageChannel
 class AddSubscribeInput(BaseModel):
     """添加订阅工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     title: str = Field(
         ...,
         description="The title of the media to subscribe to (e.g., 'The Matrix', 'Breaking Bad')",

app/agent/tools/impl/ask_user_choice.py

@@ -38,10 +38,8 @@ class UserChoiceOptionInput(BaseModel):
 class AskUserChoiceInput(BaseModel):
     """按钮选择工具输入。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why the agent needs the user to choose from buttons",)
-        description="Clear explanation of why the agent needs the user to choose from buttons",
-    )
     message: str = Field(
         ...,
         description="Question or prompt shown to the user together with the buttons",

app/agent/tools/impl/browse_webpage.py

@@ -38,10 +38,8 @@ class BrowserAction(str, Enum):
 class BrowseWebpageInput(BaseModel):
     """浏览器操作工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this browser action is being performed",)
-        description="Clear explanation of why this browser action is being performed",
-    )
     action: str = Field(
         ...,
         description=(

app/agent/tools/impl/delete_custom_filter_rule.py

@@ -19,10 +19,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteCustomFilterRuleInput(BaseModel):
     """删除自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     rule_id: str = Field(..., description="Custom rule ID to delete.")
 
 

app/agent/tools/impl/delete_download.py

@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteDownloadInput(BaseModel):
     """删除下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     hash: str = Field(
         ..., description="Task hash (can be obtained from query_download_tasks tool)"
     )

app/agent/tools/impl/delete_download_history.py

@@ -13,10 +13,8 @@ from app.log import logger
 class DeleteDownloadHistoryInput(BaseModel):
     """删除下载历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     history_id: int = Field(
         ..., description="The ID of the download history record to delete"
     )

app/agent/tools/impl/delete_rule_group.py

@@ -18,10 +18,8 @@ from app.schemas.types import SystemConfigKey
 class DeleteRuleGroupInput(BaseModel):
     """删除过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     name: str = Field(..., description="Rule group name to delete.")
 
 

app/agent/tools/impl/delete_subscribe.py

@@ -15,10 +15,8 @@ from app.schemas.types import EventType
 class DeleteSubscribeInput(BaseModel):
     """删除订阅工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     subscribe_id: int = Field(
         ...,
         description="The ID of the subscription to delete (can be obtained from query_subscribes tool)",

app/agent/tools/impl/delete_transfer_history.py

@@ -12,10 +12,8 @@ from app.log import logger
 class DeleteTransferHistoryInput(BaseModel):
     """删除整理历史记录工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     history_id: int = Field(
         ..., description="The ID of the transfer history record to delete"
     )

app/agent/tools/impl/execute_command.py

@@ -141,9 +141,7 @@ class _CommandOutput:
 class ExecuteCommandInput(BaseModel):
     """执行 Shell 命令工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this command action is needed")
-        ..., description="Clear explanation of why this command action is needed"
-    )
     action: Optional[Literal["start", "read", "wait", "write", "kill", "run"]] = Field(
         "start",
         description=(

app/agent/tools/impl/get_recommendations.py

@@ -14,10 +14,8 @@ from app.schemas.types import MediaType, media_type_to_agent
 class GetRecommendationsInput(BaseModel):
     """获取推荐工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     source: Optional[str] = Field(
         "tmdb_trending",
         description="Recommendation source: "

app/agent/tools/impl/get_search_results.py

@@ -20,10 +20,8 @@ from ._torrent_search_utils import (
 class GetSearchResultsInput(BaseModel):
     """获取搜索结果工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     site: Optional[List[str]] = Field(None, description="Site name filters")
     season: Optional[List[str]] = Field(None, description="Season or episode filters")
     free_state: Optional[List[str]] = Field(None, description="Promotion state filters")

app/agent/tools/impl/install_plugin.py

@@ -18,10 +18,8 @@ from app.log import logger
 class InstallPluginInput(BaseModel):
     """安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="Exact plugin ID to install. Use query_market_plugins first to find the correct plugin_id.",

app/agent/tools/impl/list_directory.py

@@ -16,7 +16,7 @@ from app.utils.string import StringUtils
 
 class ListDirectoryInput(BaseModel):
     """查询文件系统目录内容工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     path: str = Field(..., description="Directory path to list contents (e.g., '/home/user/downloads' or 'C:/Downloads')")
     storage: Optional[str] = Field("local", description="Storage type (default: 'local' for local file system, can be 'smb', 'alist', etc.)")
     sort_by: Optional[str] = Field("name", description="Sort order: 'name' for alphabetical sorting, 'time' for modification time sorting (default: 'name')")

app/agent/tools/impl/list_slash_commands.py

@@ -12,10 +12,8 @@ from app.log import logger
 class ListSlashCommandsInput(BaseModel):
     """查询所有可用斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
 
 
 class ListSlashCommandsTool(MoviePilotTool):

app/agent/tools/impl/modify_download.py

@@ -12,10 +12,8 @@ from app.log import logger
 class ModifyDownloadInput(BaseModel):
     """修改下载任务工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     hash: str = Field(
         ..., description="Task hash (can be obtained from query_download_tasks tool)"
     )

app/agent/tools/impl/query_builtin_filter_rules.py

@@ -17,10 +17,8 @@ from app.log import logger
 class QueryBuiltinFilterRulesInput(BaseModel):
     """查询内置过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of built-in rule IDs to query. If omitted, return all built-in rules.",

app/agent/tools/impl/query_custom_filter_rules.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryCustomFilterRulesInput(BaseModel):
     """查询自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     rule_ids: Optional[List[str]] = Field(
         None,
         description="Optional list of custom rule IDs to query. If omitted, return all custom rules.",

app/agent/tools/impl/query_custom_identifiers.py

@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class QueryCustomIdentifiersInput(BaseModel):
     """查询自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
 
 
 class QueryCustomIdentifiersTool(MoviePilotTool):

app/agent/tools/impl/query_directory_settings.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryDirectorySettingsInput(BaseModel):
     """查询系统目录设置工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     directory_type: Optional[str] = Field("all",
                                           description="Filter directories by type: 'download' for download directories, 'library' for media library directories, 'all' for all directories")
     storage_type: Optional[str] = Field("all",

app/agent/tools/impl/query_download_tasks.py

@@ -15,7 +15,7 @@ from app.schemas.types import TorrentStatus, media_type_to_agent
 
 class QueryDownloadTasksInput(BaseModel):
     """查询下载工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     downloader: Optional[str] = Field(None,
                                       description="Name of specific downloader to query (optional, if not provided queries all configured downloaders)")
     status: Optional[str] = Field("all",

app/agent/tools/impl/query_downloaders.py

@@ -13,7 +13,7 @@ from app.schemas.types import SystemConfigKey
 
 class QueryDownloadersInput(BaseModel):
     """查询下载器工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QueryDownloadersTool(MoviePilotTool):

app/agent/tools/impl/query_episode_schedule.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class QueryEpisodeScheduleInput(BaseModel):
     """查询剧集上映时间工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: int = Field(..., description="TMDB ID of the TV series (can be obtained from search_media tool)")
     season: int = Field(..., description="Season number to query")
     episode_group: Optional[str] = Field(None, description="Episode group ID (optional)")

app/agent/tools/impl/query_installed_plugins.py

@@ -20,10 +20,8 @@ from app.log import logger
 class QueryInstalledPluginsInput(BaseModel):
     """查询已安装插件工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter installed plugins by plugin ID, name, description, or author.",

app/agent/tools/impl/query_library_exists.py

@@ -76,7 +76,7 @@ def _build_tv_server_result(existing_seasons: OrderedDict, total_seasons: Ordere
 
 class QueryLibraryExistsInput(BaseModel):
     """查询媒体库工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")

app/agent/tools/impl/query_library_latest.py

@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QueryLibraryLatestInput(BaseModel):
     """查询媒体服务器最近入库影片工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     server: Optional[str] = Field(
         None,
         description="Media server name (optional, if not specified queries all enabled media servers)",

app/agent/tools/impl/query_market_plugins.py

@@ -20,10 +20,8 @@ from app.log import logger
 class QueryMarketPluginsInput(BaseModel):
     """查询插件市场工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     query: Optional[str] = Field(
         None,
         description="Optional keyword to filter plugin market results by plugin ID, name, description, or author.",

app/agent/tools/impl/query_media_detail.py

@@ -17,7 +17,7 @@ SEASON_PREVIEW_LIMIT = 100
 
 class QueryMediaDetailInput(BaseModel):
     """查询媒体详情工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID of the media (movie or TV series, can be obtained from search_media tool)")
     douban_id: Optional[str] = Field(None, description="Douban ID of the media (alternative to tmdb_id)")
     media_type: str = Field(..., description="Allowed values: movie, tv")

app/agent/tools/impl/query_personas.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPersonasInput(BaseModel):
     """查询人格工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     query: Optional[str] = Field(
         None,
         description=(

app/agent/tools/impl/query_plugin_capabilities.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QueryPluginCapabilitiesInput(BaseModel):
     """查询插件能力工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: Optional[str] = Field(
         None,
         description="Optional plugin ID to query capabilities for a specific plugin. "

app/agent/tools/impl/query_plugin_config.py

@@ -14,10 +14,8 @@ from app.log import logger
 class QueryPluginConfigInput(BaseModel):
     """查询插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",

app/agent/tools/impl/query_plugin_data.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryPluginDataInput(BaseModel):
     """查询插件数据工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="The plugin ID to query. Use query_installed_plugins first to discover valid plugin IDs.",

app/agent/tools/impl/query_popular_subscribes.py

@@ -17,7 +17,7 @@ MAX_PAGE_SIZE = 50
 
 class QueryPopularSubscribesInput(BaseModel):
     """查询热门订阅工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     media_type: str = Field(..., description="Allowed values: movie, tv")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
     count: Optional[int] = Field(30, description="Number of items per page (default: 30, max: 50)")

app/agent/tools/impl/query_rule_groups.py

@@ -18,10 +18,8 @@ from app.log import logger
 class QueryRuleGroupsInput(BaseModel):
     """查询规则组工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     group_names: Optional[List[str]] = Field(
         None,
         description="Optional list of rule group names to query. If omitted, return all rule groups.",

app/agent/tools/impl/query_schedulers.py

@@ -11,7 +11,7 @@ from app.log import logger
 
 class QuerySchedulersInput(BaseModel):
     """查询定时服务工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
 
 
 class QuerySchedulersTool(MoviePilotTool):

app/agent/tools/impl/query_site_userdata.py

@@ -23,10 +23,8 @@ def _preview_list(value, limit: int = SITE_USERDATA_DETAIL_PREVIEW_LIMIT) -> tup
 class QuerySiteUserdataInput(BaseModel):
     """查询站点用户数据工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     site_id: int = Field(
         ...,
         description="The ID of the site to query user data for (can be obtained from query_sites tool)",

app/agent/tools/impl/query_sites.py

@@ -13,10 +13,8 @@ from app.log import logger
 class QuerySitesInput(BaseModel):
     """查询站点工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     status: Optional[str] = Field(
         "all",
         description="Filter sites by status: 'active' for enabled sites, 'inactive' for disabled sites, 'all' for all sites",

app/agent/tools/impl/query_subscribe_history.py

@@ -17,10 +17,8 @@ PAGE_SIZE = 20
 class QuerySubscribeHistoryInput(BaseModel):
     """查询订阅历史工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     media_type: Optional[str] = Field(
         "all", description="Allowed values: movie, tv, all"
     )

app/agent/tools/impl/query_subscribe_shares.py

@@ -14,7 +14,7 @@ MAX_PAGE_SIZE = 50
 
 class QuerySubscribeSharesInput(BaseModel):
     """查询订阅分享工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: Optional[str] = Field(None, description="Filter shares by media name (partial match, optional)")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")
     count: Optional[int] = Field(30, description="Number of items per page (default: 30, max: 50)")

app/agent/tools/impl/query_subscribes.py

@@ -47,10 +47,8 @@ QUERY_SUBSCRIBE_OUTPUT_FIELDS = [
 class QuerySubscribesInput(BaseModel):
     """查询订阅工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     status: Optional[str] = Field(
         "all",
         description="Filter subscriptions by status: 'R' for enabled subscriptions, 'S' for paused ones, 'all' for all subscriptions",

app/agent/tools/impl/query_system_settings.py

@@ -19,10 +19,8 @@ from app.log import logger
 class QuerySystemSettingsInput(BaseModel):
     """查询系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     setting_key: Optional[str] = Field(
         None,
         description=(

app/agent/tools/impl/query_transfer_history.py

@@ -15,7 +15,7 @@ from app.utils.jieba import cut as jieba_cut
 
 class QueryTransferHistoryInput(BaseModel):
     """查询整理历史记录工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="Search by title (optional, supports partial match)")
     status: Optional[str] = Field("all",
                                   description="Filter by status: 'success' for successful transfers, 'failed' for failed transfers, 'all' for all records (default: 'all')")

app/agent/tools/impl/query_workflows.py

@@ -13,7 +13,7 @@ from app.log import logger
 
 class QueryWorkflowsInput(BaseModel):
     """查询工作流工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     state: Optional[str] = Field("all", description="Filter workflows by state: 'W' for waiting, 'R' for running, 'P' for paused, 'S' for success, 'F' for failed, 'all' for all workflows (default: 'all')")
     name: Optional[str] = Field(None, description="Filter workflows by name (partial match, optional)")
     trigger_type: Optional[str] = Field("all", description="Filter workflows by trigger type: 'timer' for scheduled, 'event' for event-triggered, 'manual' for manual, 'all' for all types (default: 'all')")

app/agent/tools/impl/recognize_media.py

@@ -15,7 +15,7 @@ from app.schemas.types import media_type_to_agent
 
 class RecognizeMediaInput(BaseModel):
     """识别媒体信息工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: Optional[str] = Field(None, description="The title of the torrent/media to recognize (required for torrent recognition)")
     subtitle: Optional[str] = Field(None, description="The subtitle or description of the torrent (optional, helps improve recognition accuracy)")
     path: Optional[str] = Field(None, description="The file path to recognize (required for file recognition, mutually exclusive with title)")

app/agent/tools/impl/reload_plugin.py

@@ -16,10 +16,8 @@ from app.log import logger
 class ReloadPluginInput(BaseModel):
     """重载插件工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="The plugin ID to reload so the latest saved config takes effect.",

app/agent/tools/impl/run_scheduler.py

@@ -11,10 +11,8 @@ from app.log import logger
 class RunSchedulerInput(BaseModel):
     """运行定时服务工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     job_id: str = Field(
         ...,
         description="The ID of the scheduled job to run (can be obtained from query_schedulers tool)",

app/agent/tools/impl/run_slash_command.py

@@ -14,10 +14,8 @@ from app.schemas.types import EventType, MessageChannel
 class RunSlashCommandInput(BaseModel):
     """运行斜杠命令工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     command: str = Field(
         ...,
         description="The slash command to execute, e.g. '/cookiecloud'. "

app/agent/tools/impl/run_workflow.py

@@ -14,10 +14,8 @@ from app.log import logger
 class RunWorkflowInput(BaseModel):
     """执行工作流工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     workflow_id: int = Field(
         ..., description="Workflow ID (can be obtained from query_workflows tool)"
     )

app/agent/tools/impl/scrape_metadata.py

@@ -15,10 +15,8 @@ from app.schemas import FileItem
 class ScrapeMetadataInput(BaseModel):
     """刮削媒体元数据工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     path: str = Field(
         ...,
         description="Path to the file or directory to scrape metadata for (e.g., '/path/to/file.mkv' or '/path/to/directory')",

app/agent/tools/impl/search_media.py

@@ -13,7 +13,7 @@ from app.schemas.types import MediaType, media_type_to_agent
 
 class SearchMediaInput(BaseModel):
     """搜索媒体工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     title: str = Field(..., description="The title of the media to search for (e.g., 'The Matrix', 'Breaking Bad')")
     year: Optional[str] = Field(None, description="Release year of the media (optional, helps narrow down results)")
     media_type: Optional[str] = Field(None,

app/agent/tools/impl/search_person.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class SearchPersonInput(BaseModel):
     """搜索人物工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     name: str = Field(..., description="The name of the person to search for (e.g., 'Tom Hanks', '周杰伦')")
 
 

app/agent/tools/impl/search_person_credits.py

@@ -14,7 +14,7 @@ from app.log import logger
 
 class SearchPersonCreditsInput(BaseModel):
     """搜索演员参演作品工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     person_id: int = Field(..., description="The ID of the person/actor to search for credits (e.g., 31 for Tom Hanks in TMDB)")
     source: str = Field(..., description="The data source: 'tmdb' for TheMovieDB, 'douban' for Douban, 'bangumi' for Bangumi")
     page: Optional[int] = Field(1, description="Page number for pagination (default: 1)")

app/agent/tools/impl/search_subscribe.py

@@ -14,7 +14,7 @@ from app.schemas.types import media_type_to_agent
 
 class SearchSubscribeInput(BaseModel):
     """搜索订阅缺失剧集工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     subscribe_id: int = Field(..., description="The ID of the subscription to search for missing episodes (can be obtained from query_subscribes tool)")
     manual: Optional[bool] = Field(False, description="Whether this is a manual search (default: False)")
     filter_groups: Optional[List[str]] = Field(None,

app/agent/tools/impl/search_torrents.py

@@ -19,7 +19,7 @@ from ._torrent_search_utils import (
 
 class SearchTorrentsInput(BaseModel):
     """搜索种子工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     tmdb_id: Optional[int] = Field(None, description="TMDB ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     douban_id: Optional[str] = Field(None, description="Douban ID (can be obtained from search_media tool). Either tmdb_id or douban_id must be provided.")
     media_type: Optional[str] = Field(None, description="Allowed values: movie, tv")

app/agent/tools/impl/search_web.py

@@ -19,10 +19,8 @@ SEARCH_TIMEOUT = 20
 class SearchWebInput(BaseModel):
     """搜索网络内容工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     query: str = Field(
         ..., description="The search query string to search for on the web"
     )

app/agent/tools/impl/send_local_file.py

@@ -15,10 +15,8 @@ from app.schemas.types import MessageChannel
 class SendLocalFileInput(BaseModel):
     """发送本地附件工具输入。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why sending this local file helps the user",)
-        description="Clear explanation of why sending this local file helps the user",
-    )
     file_path: str = Field(
         ...,
         description="Absolute path to the local image or file to send to the user",

app/agent/tools/impl/send_message.py

@@ -11,10 +11,8 @@ from app.log import logger
 class SendMessageInput(BaseModel):
     """发送消息工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     message: Optional[str] = Field(
         None,
         description="The message content to send to the user (should be clear and informative)",

app/agent/tools/impl/send_voice_message.py

@@ -15,10 +15,8 @@ from app.schemas import Notification, NotificationType
 class SendVoiceMessageInput(BaseModel):
     """发送语音消息工具输入。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why a voice reply is the best fit in the current context",)
-        description="Clear explanation of why a voice reply is the best fit in the current context",
-    )
     message: str = Field(
         ...,
         description="The spoken content to send back to the user",

app/agent/tools/impl/switch_persona.py

@@ -1,7 +1,7 @@
 """切换当前激活人格工具。"""
 
 import json
-from typing import Type
+from typing import Type, Optional
 
 from pydantic import BaseModel, Field
 
@@ -13,10 +13,8 @@ from app.log import logger
 class SwitchPersonaInput(BaseModel):
     """切换人格工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     persona_id: str = Field(
         ...,
         description=(

app/agent/tools/impl/test_site.py

@@ -12,7 +12,7 @@ from app.log import logger
 
 class TestSiteInput(BaseModel):
     """测试站点连通性工具的输入参数模型"""
-    explanation: str = Field(..., description="Clear explanation of why this tool is being used in the current context")
+    explanation: Optional[str] = Field(None, description="Clear explanation of why this tool is being used in the current context")
     site_identifier: int = Field(..., description="Site ID to test (can be obtained from query_sites tool)")
 
 

app/agent/tools/impl/transfer_file.py

@@ -13,10 +13,8 @@ from app.schemas import FileItem, MediaType
 class TransferFileInput(BaseModel):
     """整理文件或目录工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     file_path: str = Field(
         ...,
         description="Path to the file or directory to transfer (e.g., '/path/to/file.mkv' or '/path/to/directory')",

app/agent/tools/impl/uninstall_plugin.py

@@ -17,10 +17,8 @@ from app.log import logger
 class UninstallPluginInput(BaseModel):
     """卸载插件工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="Exact plugin ID to uninstall. Use query_installed_plugins first to find the correct plugin_id.",

app/agent/tools/impl/update_custom_filter_rule.py

@@ -22,10 +22,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomFilterRuleInput(BaseModel):
     """更新自定义过滤规则工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     current_rule_id: str = Field(
         ..., description="Existing custom rule ID to update."
     )

app/agent/tools/impl/update_custom_identifiers.py

@@ -14,10 +14,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateCustomIdentifiersInput(BaseModel):
     """更新自定义识别词工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     identifiers: List[str] = Field(
         ...,
         description=(

app/agent/tools/impl/update_persona_definition.py

@@ -13,10 +13,8 @@ from app.log import logger
 class UpdatePersonaDefinitionInput(BaseModel):
     """更新人格定义工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     persona_id: str = Field(
         ...,
         description=(

app/agent/tools/impl/update_plugin_config.py

@@ -14,10 +14,8 @@ from app.log import logger
 class UpdatePluginConfigInput(BaseModel):
     """修改插件配置工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     plugin_id: str = Field(
         ...,
         description="The plugin ID to update. Use query_plugin_config first to inspect the current config.",

app/agent/tools/impl/update_rule_group.py

@@ -24,10 +24,8 @@ from app.schemas.types import SystemConfigKey
 class UpdateRuleGroupInput(BaseModel):
     """更新过滤规则组工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     current_name: str = Field(..., description="Existing rule group name to update.")
     new_name: Optional[str] = Field(
         None,

app/agent/tools/impl/update_site.py

@@ -17,10 +17,8 @@ from app.utils.string import StringUtils
 class UpdateSiteInput(BaseModel):
     """更新站点工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     site_id: int = Field(
         ...,
         description="The ID of the site to update (can be obtained from query_sites tool)",

app/agent/tools/impl/update_site_cookie.py

@@ -13,10 +13,8 @@ from app.log import logger
 class UpdateSiteCookieInput(BaseModel):
     """更新站点Cookie和UA工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     site_identifier: int = Field(
         ...,
         description="Site ID to update Cookie and User-Agent for (can be obtained from query_sites tool)",

app/agent/tools/impl/update_subscribe.py

@@ -16,10 +16,8 @@ from app.schemas.types import EventType
 class UpdateSubscribeInput(BaseModel):
     """更新订阅工具的输入参数模型"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     subscribe_id: int = Field(
         ...,
         description="The ID of the subscription to update (can be obtained from query_subscribes tool)",

app/agent/tools/impl/update_system_settings.py

@@ -25,10 +25,8 @@ SettingValue = Optional[Union[list, dict, bool, int, float, str]]
 class UpdateSystemSettingsInput(BaseModel):
     """更新系统设置工具的输入参数模型。"""
 
-    explanation: str = Field(
+    explanation: Optional[str] = Field(None,
-        ...,
+        description="Clear explanation of why this tool is being used in the current context",)
-        description="Clear explanation of why this tool is being used in the current context",
-    )
     setting_key: str = Field(
         ...,
         description=(