"""字符串模块方法协议的可检查契约清单。""" from __future__ import annotations import inspect from collections.abc import Callable from dataclasses import dataclass from enum import StrEnum from typing import Any, Protocol class ModuleResultAggregation(StrEnum): """描述多模块结果沿调用链的兼容聚合方式。""" LEGACY = "legacy" FIRST_NON_EMPTY = "first_non_empty" ORDERED_LIST_MERGE = "ordered_list_merge" ORDERED_MAPPING_MERGE = "ordered_mapping_merge" PIPELINE_RELAY = "pipeline_relay" class ModuleResultShape(StrEnum): """描述模块 provider 返回值的基础 Python 形状。""" ANY = "any" LIST = "list" STRING = "string" MAPPING = "mapping" BOOLEAN = "boolean" BYTES = "bytes" class ModuleExecutionMode(StrEnum): """描述 provider 可以采用的执行形态。""" SYNC_OR_ASYNC = "sync_or_async" class ModuleErrorPolicy(StrEnum): """描述单个 provider 失败后的兼容处理策略。""" ISOLATE_PROVIDER = "isolate_provider" class ModuleCapability(Protocol): """宿主和新插件可用于声明动态能力的最小 Protocol。""" def __call__(self, *args: Any, **kwargs: Any) -> Any: """执行模块能力并返回契约声明的结果。""" @dataclass(frozen=True, slots=True) class ModuleMethodContract: """记录模块方法的输入、结果、执行与兼容错误协议。""" family: str aggregation: ModuleResultAggregation = ModuleResultAggregation.LEGACY version: int = 1 input_contract: str = "legacy_args" result_contract: str = "Any" result_shape: ModuleResultShape = ModuleResultShape.ANY required_parameters: tuple[str, ...] = () execution: ModuleExecutionMode = ModuleExecutionMode.SYNC_OR_ASYNC timeout_policy: str = "caller_budget" error_policy: ModuleErrorPolicy = ModuleErrorPolicy.ISOLATE_PROVIDER public_to_plugins: bool = True supports_sync: bool = True supports_async: bool = True plugin_short_circuit: bool = True _DEFAULT_CONTRACT = ModuleMethodContract(family="legacy") # 首批登记高频能力族。方法名仍保持开放字符串，以兼容第三方插件自定义模块能力； # 未命中项继续使用冻结的 legacy 规则，并由架构快照记录新增调用位置。 _METHOD_CONTRACTS = { "recognize_media": ModuleMethodContract( family="media-recognition", input_contract="MediaRecognitionRequest", result_contract="MediaInfo | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("meta", "mtype", "media_source", "media_id", "episode_group", "cache"), ), "search_medias": ModuleMethodContract( family="media-recognition", input_contract="MediaSearchRequest", result_contract="list[MediaInfo]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("meta", "media_source"), ), "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="CategoryConfig | None"), "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")), "mediaserver_iteminfo": ModuleMethodContract(family="media-server", input_contract="MediaServerItemRequest", result_contract="MediaServerItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "item_id")), "mediaserver_play_url": ModuleMethodContract(family="media-server", input_contract="MediaServerPlayRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "item_id")), "mediaserver_tv_episodes": ModuleMethodContract(family="media-server", input_contract="MediaServerEpisodesRequest", result_contract="list[MediaServerPlayItem]", aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server", "item_id")), "media_exists": ModuleMethodContract(family="media-server", input_contract="MediaExistsRequest", result_contract="ExistMediaInfo | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("mediainfo", "itemid", "server")), "media_statistic": ModuleMethodContract(family="media-server", input_contract="MediaStatisticRequest", result_contract="list[Statistic]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server",)), "mediaserver_image_cookies": ModuleMethodContract(family="media-server", input_contract="MediaServerImageCookiesRequest", result_contract="str | dict | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "image_url")), "mediaserver_items_count": ModuleMethodContract(family="media-server", input_contract="MediaServerItemsCountRequest", result_contract="int | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "library_id")), "mediaserver_latest": ModuleMethodContract(family="media-server", input_contract="MediaServerRecentRequest", result_contract="list[MediaServerPlayItem]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server", "count", "username")), "mediaserver_latest_images": ModuleMethodContract(family="media-server", input_contract="MediaServerRecentImagesRequest", result_contract="list[str]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server", "count", "remote", "username")), "mediaserver_librarys": ModuleMethodContract(family="media-server", input_contract="MediaServerLibrariesRequest", result_contract="list[MediaServerLibrary]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server", "username", "hidden")), "mediaserver_playing": ModuleMethodContract(family="media-server", input_contract="MediaServerRecentRequest", result_contract="list[MediaServerPlayItem]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("server", "count", "username")), "mediaserver_season_episode_ids": ModuleMethodContract(family="media-server", input_contract="MediaServerSeasonEpisodesRequest", result_contract="dict[int, str] | None", result_shape=ModuleResultShape.MAPPING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("server", "item_id", "season")), "any_files": ModuleMethodContract(family="storage", input_contract="StorageAnyFilesRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "extensions")), "create_folder": ModuleMethodContract(family="storage", input_contract="StorageCreateFolderRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "name")), "delete_file": ModuleMethodContract(family="storage", input_contract="StorageDeleteRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem",)), "download_file": ModuleMethodContract(family="storage", input_contract="StorageDownloadRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "path")), "upload_file": ModuleMethodContract(family="storage", input_contract="StorageUploadRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "path", "new_name")), "list_files": ModuleMethodContract(family="storage", input_contract="StorageListRequest", result_contract="list[FileItem]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("fileitem", "recursion")), "media_files": ModuleMethodContract(family="storage", input_contract="MediaFilesRequest", result_contract="list[FileItem]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("mediainfo",)), "get_file_item": ModuleMethodContract(family="storage", input_contract="StorageItemRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("storage", "path")), "get_folder": ModuleMethodContract(family="storage", input_contract="StorageFolderRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("storage", "path")), "get_parent_item": ModuleMethodContract(family="storage", input_contract="StorageParentRequest", result_contract="FileItem | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem",)), "rename_file": ModuleMethodContract(family="storage", input_contract="StorageRenameRequest", result_contract="bool | FileItem", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "name")), "storage_manage": ModuleMethodContract(family="storage", input_contract="StorageManageRequest", result_contract="StorageProviderResult", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("storage", "action")), "snapshot_storage": ModuleMethodContract(family="storage", input_contract="StorageSnapshotRequest", result_contract="dict[str, dict] | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("storage", "path", "last_snapshot_time", "max_depth", "previous_snapshot")), "transfer": ModuleMethodContract(family="storage", input_contract="TransferRequest", result_contract="TransferInfo | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("fileitem", "meta", "mediainfo", "target_directory", "target_storage", "target_path", "transfer_type", "scrape", "library_type_folder", "library_category_folder", "episodes_info", "source_oper", "target_oper", "preview")), "send_message": ModuleMethodContract(family="messaging", input_contract="MessageSendRequest", result_contract="Message | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY), "finalize_message": ModuleMethodContract(family="messaging", input_contract="MessageFinalizeRequest", result_contract="Message | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("response",)), "register_commands": ModuleMethodContract(family="messaging", input_contract="CommandRegistrationRequest", result_contract="None", required_parameters=("commands",)), "scheduler_job": ModuleMethodContract(family="scheduling", input_contract="SchedulerJobRequest", result_contract="None"), "webhook_parser": ModuleMethodContract(family="integration", input_contract="WebhookRequest", result_contract="WebhookEventInfo | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("body", "form", "args")), "download_discord_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_feishu_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_feishu_image_to_data_url": ModuleMethodContract(family="messaging", input_contract="MessageImageDownloadRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("image_ref", "source")), "download_qq_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_slack_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_slack_file_to_data_url": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_url", "source")), "download_synologychat_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_telegram_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_id", "source")), "download_telegram_file_to_base64": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_id", "source")), "download_vocechat_file_bytes": ModuleMethodContract(family="messaging", input_contract="MessageFileDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("file_ref", "source")), "download_vocechat_image_to_data_url": ModuleMethodContract(family="messaging", input_contract="MessageImageDownloadRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("image_ref", "source")), "download_wechat_image_to_data_url": ModuleMethodContract(family="messaging", input_contract="MessageImageDownloadRequest", result_contract="str | None", result_shape=ModuleResultShape.STRING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("image_ref", "source")), "download_wechat_media_bytes": ModuleMethodContract(family="messaging", input_contract="MessageMediaDownloadRequest", result_contract="bytes | None", result_shape=ModuleResultShape.BYTES, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("media_ref", "source")), "downloader_info": ModuleMethodContract(family="downloader", input_contract="DownloaderInfoRequest", result_contract="list[DownloaderInfo]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("downloader",)), "list_torrents": ModuleMethodContract(family="downloader", input_contract="TorrentListRequest", result_contract="list[DownloaderTorrent]", result_shape=ModuleResultShape.LIST, aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, required_parameters=("status", "hashs", "downloader", "include_all_tags")), "torrent_files": ModuleMethodContract(family="downloader", input_contract="TorrentFilesRequest", result_contract="DownloaderFileCollection | None", required_parameters=("tid", "downloader")), "get_torrent_trackers": ModuleMethodContract(family="downloader", input_contract="TorrentTrackersRequest", result_contract="dict[str, list[str]] | None", result_shape=ModuleResultShape.MAPPING, aggregation=ModuleResultAggregation.ORDERED_MAPPING_MERGE, required_parameters=("hash_string", "downloader")), "download": ModuleMethodContract(family="downloader", input_contract="DownloadTaskRequest", result_contract="DownloadTaskResult | None", aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("content", "download_dir", "cookie", "episodes", "category", "label", "downloader")), "remove_torrents": ModuleMethodContract(family="downloader", input_contract="TorrentRemoveRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("hashs", "delete_file", "downloader")), "set_torrents_tag": ModuleMethodContract(family="downloader", input_contract="TorrentTagRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("hashs", "tags", "downloader")), "start_torrents": ModuleMethodContract(family="downloader", input_contract="TorrentControlRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("hashs", "downloader")), "stop_torrents": ModuleMethodContract(family="downloader", input_contract="TorrentControlRequest", result_contract="bool | None", result_shape=ModuleResultShape.BOOLEAN, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("hashs", "downloader")), "update_torrent": ModuleMethodContract(family="downloader", input_contract="TorrentUpdateRequest", result_contract="dict[str, bool] | None", result_shape=ModuleResultShape.MAPPING, aggregation=ModuleResultAggregation.FIRST_NON_EMPTY, required_parameters=("hash_string", "downloader", "download_limit", "upload_limit", "tracker_list", "save_path", "category", "ratio_limit", "seeding_time_limit")), } # 同一能力的同步/异步入口共享不可变契约对象，避免参数和聚合语义各自漂移。 _METHOD_CONTRACTS.update({ "async_recognize_media": _METHOD_CONTRACTS["recognize_media"], "async_search_medias": _METHOD_CONTRACTS["search_medias"], "async_obtain_images": _METHOD_CONTRACTS["obtain_images"], }) _PREFIX_CONTRACTS = ( ("async_tmdb_", ModuleMethodContract(family="tmdb")), ("tmdb_", ModuleMethodContract(family="tmdb")), ("async_douban_", ModuleMethodContract(family="douban")), ("douban_", ModuleMethodContract(family="douban")), ("async_bangumi_", ModuleMethodContract(family="bangumi")), ("bangumi_", ModuleMethodContract(family="bangumi")), ("async_anilist_", ModuleMethodContract(family="anilist")), ("anilist_", ModuleMethodContract(family="anilist")), ("tvdb_", ModuleMethodContract(family="tvdb")), ("music_", ModuleMethodContract(family="music")), ("torrent_", ModuleMethodContract(family="downloader")), ) # 宿主静态扫描到的全部字符串能力名。第三方插件仍可声明未在这里出现的自定义方法， # 自定义方法继续走开放的 legacy contract；宿主新增调用则必须先进入本清单。 _OBSERVED_HOST_METHODS = ( 'anilist_credits', 'anilist_discover', 'anilist_info', 'anilist_person_credits', 'anilist_person_detail', 'anilist_popular_this_season', 'anilist_recommendations', 'anilist_trending', 'any_files', 'async_anilist_credits', 'async_anilist_discover', 'async_anilist_info', 'async_anilist_person_credits', 'async_anilist_person_detail', 'async_anilist_popular_this_season', 'async_anilist_recommendations', 'async_anilist_trending', 'async_bangumi_calendar', 'async_bangumi_credits', 'async_bangumi_discover', 'async_bangumi_info', 'async_bangumi_person_credits', 'async_bangumi_person_detail', 'async_bangumi_recommend', 'async_douban_discover', 'async_douban_info', 'async_douban_movie_credits', 'async_douban_movie_recommend', 'async_douban_person_credits', 'async_douban_person_detail', 'async_douban_tv_credits', 'async_douban_tv_recommend', 'async_identify_music_by_fingerprint', 'async_match_doubaninfo', 'async_match_music_album', 'async_match_tmdbinfo', 'async_movie_hot', 'async_movie_showing', 'async_movie_top250', 'async_obtain_images', 'async_recognize_media', 'async_refresh_torrents', 'async_search_collections', 'async_search_medias', 'async_search_persons', 'async_search_subtitles', 'async_search_torrents', 'async_tmdb_collection', 'async_tmdb_discover', 'async_tmdb_episodes', 'async_tmdb_group_seasons', 'async_tmdb_info', 'async_tmdb_movie_credits', 'async_tmdb_movie_recommend', 'async_tmdb_movie_similar', 'async_tmdb_person_credits', 'async_tmdb_person_detail', 'async_tmdb_seasons', 'async_tmdb_trending', 'async_tmdb_tv_credits', 'async_tmdb_tv_recommend', 'async_tmdb_tv_similar', 'async_tv_animation', 'async_tv_hot', 'async_tv_weekly_chinese', 'async_tv_weekly_global', 'async_update_recognize_cache', 'bangumi_calendar', 'bangumi_credits', 'bangumi_discover', 'bangumi_info', 'bangumi_person_credits', 'bangumi_person_detail', 'bangumi_recommend', 'channel_manage', 'clear_cache', 'create_folder', 'delete_file', 'delete_message', 'douban_discover', 'douban_info', 'douban_movie_credits', 'douban_movie_recommend', 'douban_person_credits', 'douban_person_detail', 'douban_tv_credits', 'douban_tv_recommend', 'download', 'download_added', 'download_discord_file_bytes', 'download_feishu_file_bytes', 'download_feishu_image_to_data_url', 'download_file', 'download_qq_file_bytes', 'download_slack_file_bytes', 'download_slack_file_to_data_url', 'download_synologychat_file_bytes', 'download_telegram_file_bytes', 'download_telegram_file_to_base64', 'download_vocechat_file_bytes', 'download_vocechat_image_to_data_url', 'download_wechat_image_to_data_url', 'download_wechat_media_bytes', 'downloader_info', 'edit_message', 'filter_torrents', 'finalize_message', 'get_file_item', 'get_folder', 'get_parent_item', 'get_search_page_size', 'get_torrent_trackers', 'identify_music_by_fingerprint', 'list_files', 'list_torrents', 'load_category_config', 'mark_message_processing_finished', 'mark_message_processing_started', 'match_doubaninfo', 'match_music_album', 'match_tmdbinfo', 'media_category', 'media_exists', 'media_files', 'media_statistic', 'mediaserver_image_cookies', 'mediaserver_iteminfo', 'mediaserver_items', 'mediaserver_items_count', 'mediaserver_latest', 'mediaserver_latest_images', 'mediaserver_librarys', 'mediaserver_play_url', 'mediaserver_playing', 'mediaserver_season_episode_ids', 'mediaserver_tv_episodes', 'message_parser', 'metadata_img', 'metadata_nfo', 'movie_hot', 'movie_showing', 'movie_top250', 'music_album', 'music_album_related', 'music_artist', 'music_artist_albums', 'music_artist_related', 'music_cache_clear', 'music_cache_delete', 'music_cache_items', 'music_chart', 'music_discover', 'music_fresh_releases', 'music_lyrics', 'obtain_images', 'obtain_specific_image', 'recognize_media', 'recommend_name', 'refresh_torrents', 'refresh_userdata', 'register_commands', 'remove_torrents', 'rename_file', 'save_category_config', 'scheduler_job', 'search_collections', 'search_medias', 'search_music', 'search_persons', 'search_subtitles', 'search_torrents', 'search_tvdb', 'send_direct_message', 'set_torrents_tag', 'site_subtitle_links', 'snapshot_storage', 'start_torrents', 'stop_torrents', 'storage_manage', 'tmdb_cache_clear', 'tmdb_cache_delete', 'tmdb_cache_items', 'tmdb_collection', 'tmdb_discover', 'tmdb_episodes', 'tmdb_group_seasons', 'tmdb_info', 'tmdb_movie_credits', 'tmdb_movie_recommend', 'tmdb_movie_similar', 'tmdb_person_credits', 'tmdb_person_detail', 'tmdb_seasons', 'tmdb_trending', 'tmdb_tv_credits', 'tmdb_tv_recommend', 'tmdb_tv_similar', 'torrent_files', 'transfer', 'transfer_completed', 'tv_animation', 'tv_hot', 'tv_weekly_chinese', 'tv_weekly_global', 'tvdb_info', 'tvdb_slug', 'update_recognize_cache', 'update_torrent', 'upload_file', 'user_authenticate', 'webhook_parser', ) _FAMILY_IO_CONTRACTS = { "anilist": ("AniListKeywordArguments", "AniListProviderResult"), "authentication": ("AuthenticationKeywordArguments", "AuthenticationResult"), "bangumi": ("BangumiKeywordArguments", "BangumiProviderResult"), "category": ("CategoryKeywordArguments", "CategoryProviderResult"), "douban": ("DoubanKeywordArguments", "DoubanProviderResult"), "downloader": ("DownloaderKeywordArguments", "DownloaderProviderResult"), "integration": ("IntegrationKeywordArguments", "IntegrationProviderResult"), "media-discovery": ("MediaDiscoveryKeywordArguments", "MediaDiscoveryProviderResult"), "media-recognition": ("MediaRecognitionKeywordArguments", "MediaRecognitionProviderResult"), "media-server": ("MediaServerKeywordArguments", "MediaServerProviderResult"), "messaging": ("MessagingKeywordArguments", "MessagingProviderResult"), "metadata": ("MetadataKeywordArguments", "MetadataProviderResult"), "music": ("MusicKeywordArguments", "MusicProviderResult"), "site": ("SiteKeywordArguments", "SiteProviderResult"), "storage": ("StorageKeywordArguments", "StorageProviderResult"), "tmdb": ("TmdbKeywordArguments", "TmdbProviderResult"), "tvdb": ("TvdbKeywordArguments", "TvdbProviderResult"), } def _infer_observed_family(method: str) -> str: """按稳定能力前缀把已观察宿主方法归入可审计的输入/结果族。""" for prefix, contract in _PREFIX_CONTRACTS: if method.startswith(prefix): return contract.family if method.startswith(("mediaserver_", "media_exists", "media_statistic")): return "media-server" if method.startswith(( "download", "torrent_", "list_torrents", "refresh_torrents", "remove_torrents", "start_torrents", "stop_torrents", "set_torrents_tag", "update_torrent", "get_torrent_trackers", "downloader_info", "filter_torrents", "transfer_completed", )): return "downloader" if method.startswith(( "channel_", "delete_message", "edit_message", "finalize_message", "mark_message_", "message_parser", "register_commands", "send_direct_message", "send_message", )): return "messaging" if method.startswith(( "any_files", "create_folder", "delete_file", "get_file_item", "get_folder", "get_parent_item", "list_files", "media_files", "rename_file", "snapshot_storage", "storage_manage", "transfer", "upload_file", )): return "storage" if method.startswith(( "metadata_", "obtain_specific_image", "recommend_name", )): return "metadata" if method.startswith(( "async_identify_music", "async_match_music", "identify_music", "match_music", "search_music", )): return "music" if method.startswith(( "async_match_", "async_obtain_images", "async_recognize_media", "async_update_recognize_cache", "match_", "obtain_images", "recognize_media", "update_recognize_cache", )): return "media-recognition" if method.startswith(( "async_movie_", "async_search_", "async_tv_", "movie_", "search_collections", "search_medias", "search_persons", "search_subtitles", "search_torrents", "tv_", )): return "media-discovery" if method in {"clear_cache", "load_category_config", "save_category_config"}: return "category" if method in {"get_search_page_size", "refresh_userdata", "site_subtitle_links"}: return "site" if method == "user_authenticate": return "authentication" return "integration" def _register_observed_host_contracts() -> None: """为全部宿主字符串调用登记完整 V2 字段，保留未知插件方法的 legacy fallback。""" for method in _OBSERVED_HOST_METHODS: if method in _METHOD_CONTRACTS: continue family = _infer_observed_family(method) input_contract, result_contract = _FAMILY_IO_CONTRACTS[family] _METHOD_CONTRACTS[method] = ModuleMethodContract( family=family, input_contract=input_contract, result_contract=result_contract, ) _register_observed_host_contracts() def get_module_method_contract(method: str) -> ModuleMethodContract: """返回方法的显式能力族契约，未知方法保持既有 legacy 协议。""" if contract := _METHOD_CONTRACTS.get(method): return contract for prefix, contract in _PREFIX_CONTRACTS: if method.startswith(prefix): return contract return _DEFAULT_CONTRACT def is_explicit_module_method(method: str) -> bool: """判断方法是否已进入首批显式能力族清单。""" return get_module_method_contract(method) is not _DEFAULT_CONTRACT def diagnose_module_callable(method: str, callback: Callable[..., Any]) -> tuple[str, ...]: """诊断显式能力的基础签名；兼容阶段只返回问题，不拒绝 provider。""" contract = get_module_method_contract(method) if contract is _DEFAULT_CONTRACT: return () try: parameters = inspect.signature(callback).parameters except (TypeError, ValueError): return ("signature-unavailable",) missing = tuple( name for name in contract.required_parameters if name not in parameters and not any( parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in parameters.values() ) ) return tuple(f"missing-parameter:{name}" for name in missing) def diagnose_module_result(method: str, result: Any) -> tuple[str, ...]: """诊断显式模块结果的基础形状，兼容阶段只告警而不改写返回值。""" shape = get_module_method_contract(method).result_shape if shape is ModuleResultShape.ANY or result is None: return () matches = { ModuleResultShape.LIST: isinstance(result, list), ModuleResultShape.STRING: isinstance(result, str), ModuleResultShape.MAPPING: isinstance(result, dict), ModuleResultShape.BOOLEAN: isinstance(result, bool), ModuleResultShape.BYTES: isinstance(result, bytes), } if matches.get(shape, True): return () return (f"unexpected-result:{shape.value}:{type(result).__name__}",) def list_explicit_module_contracts() -> dict[str, ModuleMethodContract]: """返回显式方法清单的副本，供架构基线和 SDK 文档使用。""" return dict(_METHOD_CONTRACTS)