MoviePilot/app/runtime/extensions/module/contracts.py

"""
字符串模块方法协议的可检查契约清单。
"""

from __future__ import annotations

import inspect
from collections.abc import Callable
from dataclasses import dataclass
from enum import StrEnum
from typing import Any, Protocol

from pydantic import BaseModel


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"
    # 向各实现方分发同一调用
    FAN_OUT = "fan_out"


class ModuleResultShape(StrEnum):
    """
    描述模块 provider 返回值的基础 Python 形状或模型对象。

    MODEL 用于 Pydantic 分页等模型对象，MAPPING 仍只接受字典。
    """

    # 接受任意结果形状
    ANY = "any"
    # 结果应为列表
    LIST = "list"
    # 结果应为字符串
    STRING = "string"
    # 结果应为键值映射
    MAPPING = "mapping"
    MODEL = "model"
    # 结果应为布尔值
    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:
        """
        执行模块能力并返回契约声明的结果。

        :param args: 模块方法契约规定的位置参数
        :param kwargs: 模块方法契约规定的关键字参数
        :return: 该模块方法契约规定的业务结果；异步实现返回供调度器等待的对象
        """


@dataclass(frozen=True, slots=True)
class ModuleMethodContract:
    """
    记录模块方法的输入、结果、执行与兼容错误协议。

    :param family: 方法所属的业务能力族
    :param aggregation: 多个提供方返回结果的聚合策略
    :param version: 模块方法协议版本，默认从 1 开始
    :param input_contract: 输入参数协议名称
    :param result_contract: 返回值业务协议名称
    :param result_shape: 用于运行时检查的返回值基础形状
    :param required_parameters: 调用该能力必须提供的参数名
    :param execution: 允许使用的同步或异步执行形态
    :param timeout_policy: 执行预算的归属策略，默认沿用调用方预算
    :param error_policy: 单个提供方失败时的隔离策略
    :param public_to_plugins: 是否允许插件实现此模块能力
    :param supports_sync: 是否支持同步调用入口
    :param supports_async: 是否支持异步调用入口
    :param plugin_short_circuit: 插件返回有效结果后是否短路宿主模块调用
    :param optional_parameters: 兼容调用时可选择传入的参数名
    """

    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
    optional_parameters: tuple[str, ...] = ()


_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"),
    ),
    "match_doubaninfo": ModuleMethodContract(
        family="media-recognition",
        input_contract="DoubanMatchRequest",
        result_contract="dict[str, Any] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("name", "imdbid", "mtype", "year", "season", "raise_exception"),
    ),
    "match_tmdbinfo": ModuleMethodContract(
        family="media-recognition",
        input_contract="TmdbMatchRequest",
        result_contract="dict[str, Any] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("name", "mtype", "year", "season"),
    ),
    "update_recognize_cache": ModuleMethodContract(
        family="media-recognition",
        input_contract="RecognitionCacheUpdateRequest",
        result_contract="bool | None",
        result_shape=ModuleResultShape.BOOLEAN,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("meta", "mediainfo"),
    ),
    "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"),
    ),
    "get_media_auxiliary_info": ModuleMethodContract(
        family="media-recognition",
        input_contract="MediaAuxiliaryInfoRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("mediainfo", "media_source", "metainfo"),
        plugin_short_circuit=False,
    ),
    "get_media_classification_facts": ModuleMethodContract(
        family="media-classification",
        version=1,
        input_contract="ClassificationEnrichmentRequest",
        result_contract="ClassificationEnrichmentResponse | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FAN_OUT,
        required_parameters=("request",),
        supports_async=False,
        plugin_short_circuit=False,
    ),
    "obtain_images": ModuleMethodContract(
        family="media-recognition",
        input_contract="MediaInfo",
        result_contract="MediaInfo | None",
        aggregation=ModuleResultAggregation.PIPELINE_RELAY,
        required_parameters=("mediainfo",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "mediaserver_iteminfo": ModuleMethodContract(
        family="media-server",
        input_contract="MediaServerItemRequest",
        result_contract="MediaServerItem | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("server", "item_id"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "media_exists": ModuleMethodContract(
        family="media-server",
        input_contract="MediaExistsRequest",
        result_contract="ExistMediaInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("mediainfo", "itemid", "server"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "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"),
        optional_parameters=("query",),
    ),
    "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"),
    ),
    "link_file": ModuleMethodContract(
        family="storage",
        input_contract="StorageLinkRequest",
        result_contract="bool | None",
        result_shape=ModuleResultShape.BOOLEAN,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("fileitem", "target_file"),
        public_to_plugins=False,
    ),
    "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_file_item_strict": ModuleMethodContract(
        family="storage",
        input_contract="StorageItemRequest",
        result_contract="FileItemQueryResult | None",
        result_shape=ModuleResultShape.MODEL,
        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"),
    ),
    "plan_transfer": ModuleMethodContract(
        family="storage",
        input_contract="TransferPlanningInput",
        result_contract="TransferPlanCheckpoint | 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",
            "preview",
            "planning_input",
        ),
        public_to_plugins=False,
    ),
    "execute_transfer_plan": ModuleMethodContract(
        family="storage",
        input_contract="TransferPlanCheckpoint",
        result_contract="TransferInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=(
            "checkpoint",
            "meta",
            "mediainfo",
            "source_oper",
            "target_oper",
        ),
        public_to_plugins=False,
    ),
    "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",
        ),
    ),
    "clear_cache": ModuleMethodContract(
        family="category",
        input_contract="CacheClearRequest",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        plugin_short_circuit=False,
    ),
    "get_search_page_size": ModuleMethodContract(
        family="site",
        input_contract="SiteSearchPageSizeRequest",
        result_contract="int | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("site", "keyword"),
    ),
    "restore_search_torrent": ModuleMethodContract(
        family="site",
        input_contract="SearchTorrentRestoreRequest",
        result_contract="TorrentInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("site", "record"),
        public_to_plugins=False,
    ),
    "refresh_userdata": ModuleMethodContract(
        family="site",
        input_contract="SiteUserDataRequest",
        result_contract="SiteUserData | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("site",),
    ),
    "site_subtitle_links": ModuleMethodContract(
        family="site",
        input_contract="SiteSubtitleLinksRequest",
        result_contract="list[str]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("context",),
    ),
    "metadata_img": ModuleMethodContract(
        family="metadata",
        input_contract="MetadataImageRequest",
        result_contract="dict[str, str] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("mediainfo", "season", "episode"),
    ),
    "metadata_nfo": ModuleMethodContract(
        family="metadata",
        input_contract="MetadataNfoRequest",
        result_contract="str | None",
        result_shape=ModuleResultShape.STRING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("meta", "mediainfo", "season", "episode"),
    ),
    "obtain_specific_image": ModuleMethodContract(
        family="metadata",
        input_contract="SpecificImageRequest",
        result_contract="str | None",
        result_shape=ModuleResultShape.STRING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("mediaid", "mtype", "image_type", "image_prefix", "season", "episode"),
    ),
    "recommend_name": ModuleMethodContract(
        family="metadata",
        input_contract="RecommendNameRequest",
        result_contract="str | None",
        result_shape=ModuleResultShape.STRING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("meta", "mediainfo", "episodes_info"),
    ),
    "user_authenticate": ModuleMethodContract(
        family="authentication",
        input_contract="UserAuthenticationRequest",
        result_contract="AuthCredentials | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("credentials",),
    ),
    "tvdb_info": ModuleMethodContract(
        family="tvdb",
        input_contract="TvdbInfoRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("tvdbid",),
    ),
    "tvdb_slug": ModuleMethodContract(
        family="tvdb",
        input_contract="TvdbInfoRequest",
        result_contract="str | None",
        result_shape=ModuleResultShape.STRING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("tvdbid",),
    ),
    "search_tvdb": ModuleMethodContract(
        family="tvdb",
        input_contract="TvdbSearchRequest",
        result_contract="list[dict]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("title",),
    ),
    "movie_hot": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "movie_showing": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "movie_top250": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "search_collections": ModuleMethodContract(
        family="media-discovery",
        input_contract="CollectionSearchRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("name", "media_source"),
    ),
    "search_persons": ModuleMethodContract(
        family="media-discovery",
        input_contract="PersonSearchRequest",
        result_contract="list[MediaPerson | MusicArtistInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("name", "media_source"),
    ),
    "search_subtitles": ModuleMethodContract(
        family="media-discovery",
        input_contract="SubtitleSearchRequest",
        result_contract="list[SubtitleInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("site", "keyword", "page"),
    ),
    "search_torrents": ModuleMethodContract(
        family="media-discovery",
        input_contract="TorrentSearchRequest",
        result_contract="list[TorrentInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("site", "keyword", "mtype", "page"),
    ),
    "tv_animation": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "tv_hot": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "tv_weekly_chinese": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "tv_weekly_global": ModuleMethodContract(
        family="media-discovery",
        input_contract="MediaRankingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "douban_discover": ModuleMethodContract(
        family="douban",
        input_contract="DoubanDiscoverRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("mtype", "sort", "tags", "page", "count"),
    ),
    "douban_info": ModuleMethodContract(
        family="douban",
        input_contract="DoubanInfoRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("doubanid", "mtype", "raise_exception"),
    ),
    "douban_movie_credits": ModuleMethodContract(
        family="douban",
        input_contract="DoubanMediaRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("doubanid",),
    ),
    "douban_movie_recommend": ModuleMethodContract(
        family="douban",
        input_contract="DoubanMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("doubanid",),
    ),
    "douban_person_credits": ModuleMethodContract(
        family="douban",
        input_contract="DoubanPersonCreditsRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("person_id", "page"),
    ),
    "douban_person_detail": ModuleMethodContract(
        family="douban",
        input_contract="DoubanPersonRequest",
        result_contract="MediaPerson | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("person_id",),
    ),
    "douban_tv_credits": ModuleMethodContract(
        family="douban",
        input_contract="DoubanMediaRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("doubanid",),
    ),
    "douban_tv_recommend": ModuleMethodContract(
        family="douban",
        input_contract="DoubanMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("doubanid",),
    ),
    "douban_movie_interests": ModuleMethodContract(
        family="douban",
        input_contract="DoubanCommentRequest",
        result_contract="MediaCommentPage",
        result_shape=ModuleResultShape.MODEL,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("doubanid", "start", "count"),
    ),
    "douban_tv_interests": ModuleMethodContract(
        family="douban",
        input_contract="DoubanCommentRequest",
        result_contract="MediaCommentPage",
        result_shape=ModuleResultShape.MODEL,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("doubanid", "start", "count"),
    ),
    "douban_movie_reviews": ModuleMethodContract(
        family="douban",
        input_contract="DoubanCommentRequest",
        result_contract="MediaReviewPage",
        result_shape=ModuleResultShape.MODEL,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("doubanid", "start", "count"),
    ),
    "douban_tv_reviews": ModuleMethodContract(
        family="douban",
        input_contract="DoubanCommentRequest",
        result_contract="MediaReviewPage",
        result_shape=ModuleResultShape.MODEL,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("doubanid", "start", "count"),
    ),
    "bangumi_calendar": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiCalendarRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
    ),
    "bangumi_credits": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiMediaRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("bangumiid",),
    ),
    "bangumi_discover": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiDiscoverArguments",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
    ),
    "bangumi_info": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiMediaRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("bangumiid",),
    ),
    "bangumi_person_credits": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiPersonRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("person_id",),
    ),
    "bangumi_person_detail": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiPersonRequest",
        result_contract="MediaPerson | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("person_id",),
    ),
    "bangumi_recommend": ModuleMethodContract(
        family="bangumi",
        input_contract="BangumiMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("bangumiid",),
    ),
    "anilist_credits": ModuleMethodContract(
        family="anilist",
        input_contract="AniListMediaPageRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("anilist_id", "page", "count"),
    ),
    "anilist_discover": ModuleMethodContract(
        family="anilist",
        input_contract="AniListDiscoverArguments",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
    ),
    "anilist_info": ModuleMethodContract(
        family="anilist",
        input_contract="AniListMediaRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("anilist_id",),
    ),
    "anilist_person_credits": ModuleMethodContract(
        family="anilist",
        input_contract="AniListPersonPageRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("person_id", "page", "count"),
    ),
    "anilist_person_detail": ModuleMethodContract(
        family="anilist",
        input_contract="AniListPersonRequest",
        result_contract="MediaPerson | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("person_id",),
    ),
    "anilist_popular_this_season": ModuleMethodContract(
        family="anilist",
        input_contract="AniListPageRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "anilist_recommendations": ModuleMethodContract(
        family="anilist",
        input_contract="AniListMediaPageRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("anilist_id", "page", "count"),
    ),
    "anilist_trending": ModuleMethodContract(
        family="anilist",
        input_contract="AniListPageRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page", "count"),
    ),
    "tmdb_collection": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbCollectionRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("collection_id",),
    ),
    "tmdb_discover": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbDiscoverRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=(
            "mtype",
            "sort_by",
            "with_genres",
            "with_original_language",
            "with_keywords",
            "with_watch_providers",
            "vote_average",
            "vote_count",
            "release_date",
            "page",
        ),
    ),
    "tmdb_episodes": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbEpisodesRequest",
        result_contract="list[TmdbEpisode]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid", "season", "episode_group"),
    ),
    "tmdb_group_seasons": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbGroupRequest",
        result_contract="list[TmdbSeason]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("group_id",),
    ),
    "tmdb_info": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbInfoRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("tmdbid", "mtype", "season"),
    ),
    "tmdb_movie_credits": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaPageRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid", "page"),
    ),
    "tmdb_movie_recommend": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid",),
    ),
    "tmdb_movie_similar": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid",),
    ),
    "tmdb_person_credits": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbPersonPageRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("person_id", "page"),
    ),
    "tmdb_person_detail": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbPersonRequest",
        result_contract="MediaPerson | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("person_id",),
    ),
    "tmdb_seasons": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaRequest",
        result_contract="list[TmdbSeason]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid",),
    ),
    "tmdb_trending": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbTrendingRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("page",),
    ),
    "tmdb_tv_credits": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaPageRequest",
        result_contract="list[MediaPerson]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid", "page"),
    ),
    "tmdb_tv_recommend": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid",),
    ),
    "tmdb_tv_similar": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbMediaRequest",
        result_contract="list[MediaInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("tmdbid",),
    ),
    "identify_music_by_fingerprint": ModuleMethodContract(
        family="music",
        input_contract="MusicFingerprintRequest",
        result_contract="str | None",
        result_shape=ModuleResultShape.STRING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("path",),
    ),
    "match_music_album": ModuleMethodContract(
        family="music",
        input_contract="MusicAlbumMatchRequest",
        result_contract="MusicAlbumInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("meta", "tracks", "limit"),
    ),
    "music_album": ModuleMethodContract(
        family="music",
        input_contract="MusicIdentityRequest",
        result_contract="MusicAlbumInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("media_source", "media_id"),
    ),
    "music_album_related": ModuleMethodContract(
        family="music",
        input_contract="MusicRelatedRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("media_source", "media_id", "count"),
    ),
    "music_artist": ModuleMethodContract(
        family="music",
        input_contract="MusicIdentityRequest",
        result_contract="MusicArtistInfo | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("media_source", "media_id"),
    ),
    "music_artist_albums": ModuleMethodContract(
        family="music",
        input_contract="MusicArtistAlbumsRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("media_source", "media_id", "page", "count", "album_type"),
    ),
    "music_artist_related": ModuleMethodContract(
        family="music",
        input_contract="MusicRelatedRequest",
        result_contract="list[MusicArtistInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("media_source", "media_id", "count"),
    ),
    "music_cache_delete": ModuleMethodContract(
        family="music",
        input_contract="MusicCacheDeleteRequest",
        result_contract="dict | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("cache_key",),
    ),
    "music_cache_items": ModuleMethodContract(
        family="music",
        input_contract="MusicCacheReadRequest",
        result_contract="list[dict]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
    ),
    "music_cache_clear": ModuleMethodContract(
        family="music",
        input_contract="MusicCacheClearRequest",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        plugin_short_circuit=False,
    ),
    "music_chart": ModuleMethodContract(
        family="music",
        input_contract="MusicChartRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("range_name", "offset", "count", "entity"),
    ),
    "music_discover": ModuleMethodContract(
        family="music",
        input_contract="MusicDiscoverRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("media_source", "page", "count", "entity", "mode", "tags", "sort"),
    ),
    "music_fresh_releases": ModuleMethodContract(
        family="music",
        input_contract="MusicFreshReleasesRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("days", "sort", "past", "future", "offset", "count"),
    ),
    "music_lyrics": ModuleMethodContract(
        family="music",
        input_contract="MusicLyricsRequest",
        result_contract="MusicLyrics | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("music",),
    ),
    "music_lyrics_candidates": ModuleMethodContract(
        family="music",
        input_contract="MusicLyricsRequest",
        result_contract="list[MusicLyrics]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("music",),
        plugin_short_circuit=False,
    ),
    "search_music": ModuleMethodContract(
        family="music",
        input_contract="MusicSearchRequest",
        result_contract="list[MusicInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("meta", "limit", "media_source"),
    ),
    "channel_manage": ModuleMethodContract(
        family="messaging",
        input_contract="ChannelManageRequest",
        result_contract="dict[str, Any] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("channel", "action"),
    ),
    "delete_message": ModuleMethodContract(
        family="messaging",
        input_contract="MessageDeleteRequest",
        result_contract="bool | None",
        result_shape=ModuleResultShape.BOOLEAN,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("channel", "source", "message_id", "chat_id"),
    ),
    "edit_message": ModuleMethodContract(
        family="messaging",
        input_contract="MessageEditRequest",
        result_contract="bool | None",
        result_shape=ModuleResultShape.BOOLEAN,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("channel", "source", "message_id", "chat_id", "text", "title", "buttons", "metadata"),
    ),
    "mark_message_processing_started": ModuleMethodContract(
        family="messaging",
        input_contract="MessageProcessingStartRequest",
        result_contract="dict[str, Any] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("channel", "source", "userid", "message_id", "chat_id", "text"),
    ),
    "mark_message_processing_finished": ModuleMethodContract(
        family="messaging",
        input_contract="MessageProcessingFinishRequest",
        result_contract="bool | None",
        result_shape=ModuleResultShape.BOOLEAN,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("channel", "source", "userid", "message_id", "chat_id", "status"),
    ),
    "message_parser": ModuleMethodContract(
        family="messaging",
        input_contract="MessageParseRequest",
        result_contract="IncomingMessage | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("source", "body", "form", "args"),
    ),
    "send_direct_message": ModuleMethodContract(
        family="messaging",
        input_contract="DirectMessageSendRequest",
        result_contract="MessageResponse | None",
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("message",),
    ),
    "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",
        aggregation=ModuleResultAggregation.FAN_OUT,
        required_parameters=("commands",),
        plugin_short_circuit=False,
    ),
    "scheduler_job": ModuleMethodContract(
        family="scheduling",
        input_contract="SchedulerJobRequest",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        plugin_short_circuit=False,
    ),
    "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"),
    ),
    "filter_torrents": ModuleMethodContract(
        family="downloader",
        input_contract="TorrentFilterRequest",
        result_contract="list[TorrentInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("rule_groups", "torrent_list", "mediainfo"),
    ),
    "refresh_torrents": ModuleMethodContract(
        family="downloader",
        input_contract="TorrentRefreshRequest",
        result_contract="list[TorrentInfo]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
        required_parameters=("site", "keyword", "cat", "page", "mtype"),
    ),
    "torrent_files": ModuleMethodContract(
        family="downloader",
        input_contract="TorrentFilesRequest",
        result_contract="list[DownloaderFile]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        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"),
        optional_parameters=("custom_words",),
    ),
    "download_added": ModuleMethodContract(
        family="downloader",
        input_contract="DownloadAddedHook",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        required_parameters=("context", "torrent_content", "download_dir"),
        plugin_short_circuit=False,
    ),
    "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",
        ),
    ),
    "transfer_completed": ModuleMethodContract(
        family="downloader",
        input_contract="TransferCompletedHook",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        required_parameters=("hashs", "downloader"),
        plugin_short_circuit=False,
    ),
    "tmdb_cache_items": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbCacheListRequest",
        result_contract="list[dict[str, Any]]",
        result_shape=ModuleResultShape.LIST,
        aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
    ),
    "tmdb_cache_delete": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbCacheDeleteRequest",
        result_contract="dict[str, Any] | None",
        result_shape=ModuleResultShape.MAPPING,
        aggregation=ModuleResultAggregation.FIRST_NON_EMPTY,
        required_parameters=("cache_key",),
    ),
    "tmdb_cache_clear": ModuleMethodContract(
        family="tmdb",
        input_contract="TmdbCacheClearRequest",
        result_contract="None",
        aggregation=ModuleResultAggregation.FAN_OUT,
        plugin_short_circuit=False,
    ),
}

# 同一能力的同步/异步入口共享不可变契约对象，避免参数和聚合语义各自漂移。
_METHOD_CONTRACTS.update(
    {
        "async_recognize_media": _METHOD_CONTRACTS["recognize_media"],
        "async_match_doubaninfo": _METHOD_CONTRACTS["match_doubaninfo"],
        "async_match_tmdbinfo": _METHOD_CONTRACTS["match_tmdbinfo"],
        "async_update_recognize_cache": _METHOD_CONTRACTS["update_recognize_cache"],
        "async_search_medias": _METHOD_CONTRACTS["search_medias"],
        "async_get_media_auxiliary_info": _METHOD_CONTRACTS["get_media_auxiliary_info"],
        "async_obtain_images": _METHOD_CONTRACTS["obtain_images"],
        "async_movie_hot": _METHOD_CONTRACTS["movie_hot"],
        "async_movie_showing": _METHOD_CONTRACTS["movie_showing"],
        "async_movie_top250": _METHOD_CONTRACTS["movie_top250"],
        "async_search_collections": _METHOD_CONTRACTS["search_collections"],
        "async_search_persons": _METHOD_CONTRACTS["search_persons"],
        "async_search_subtitles": _METHOD_CONTRACTS["search_subtitles"],
        "async_search_torrents": _METHOD_CONTRACTS["search_torrents"],
        "async_tv_animation": _METHOD_CONTRACTS["tv_animation"],
        "async_tv_hot": _METHOD_CONTRACTS["tv_hot"],
        "async_tv_weekly_chinese": _METHOD_CONTRACTS["tv_weekly_chinese"],
        "async_tv_weekly_global": _METHOD_CONTRACTS["tv_weekly_global"],
        "async_douban_discover": _METHOD_CONTRACTS["douban_discover"],
        "async_douban_info": _METHOD_CONTRACTS["douban_info"],
        "async_douban_movie_credits": _METHOD_CONTRACTS["douban_movie_credits"],
        "async_douban_movie_interests": _METHOD_CONTRACTS["douban_movie_interests"],
        "async_douban_movie_recommend": _METHOD_CONTRACTS["douban_movie_recommend"],
        "async_douban_movie_reviews": _METHOD_CONTRACTS["douban_movie_reviews"],
        "async_douban_person_credits": _METHOD_CONTRACTS["douban_person_credits"],
        "async_douban_person_detail": _METHOD_CONTRACTS["douban_person_detail"],
        "async_douban_tv_credits": _METHOD_CONTRACTS["douban_tv_credits"],
        "async_douban_tv_interests": _METHOD_CONTRACTS["douban_tv_interests"],
        "async_douban_tv_recommend": _METHOD_CONTRACTS["douban_tv_recommend"],
        "async_douban_tv_reviews": _METHOD_CONTRACTS["douban_tv_reviews"],
        "async_bangumi_calendar": _METHOD_CONTRACTS["bangumi_calendar"],
        "async_bangumi_credits": _METHOD_CONTRACTS["bangumi_credits"],
        "async_bangumi_discover": _METHOD_CONTRACTS["bangumi_discover"],
        "async_bangumi_info": _METHOD_CONTRACTS["bangumi_info"],
        "async_bangumi_person_credits": _METHOD_CONTRACTS["bangumi_person_credits"],
        "async_bangumi_person_detail": _METHOD_CONTRACTS["bangumi_person_detail"],
        "async_bangumi_recommend": _METHOD_CONTRACTS["bangumi_recommend"],
        "async_anilist_credits": _METHOD_CONTRACTS["anilist_credits"],
        "async_anilist_discover": _METHOD_CONTRACTS["anilist_discover"],
        "async_anilist_info": _METHOD_CONTRACTS["anilist_info"],
        "async_anilist_person_credits": _METHOD_CONTRACTS["anilist_person_credits"],
        "async_anilist_person_detail": _METHOD_CONTRACTS["anilist_person_detail"],
        "async_anilist_popular_this_season": _METHOD_CONTRACTS["anilist_popular_this_season"],
        "async_anilist_recommendations": _METHOD_CONTRACTS["anilist_recommendations"],
        "async_anilist_trending": _METHOD_CONTRACTS["anilist_trending"],
        "async_tmdb_collection": _METHOD_CONTRACTS["tmdb_collection"],
        "async_tmdb_discover": _METHOD_CONTRACTS["tmdb_discover"],
        "async_tmdb_episodes": _METHOD_CONTRACTS["tmdb_episodes"],
        "async_tmdb_group_seasons": _METHOD_CONTRACTS["tmdb_group_seasons"],
        "async_tmdb_info": _METHOD_CONTRACTS["tmdb_info"],
        "async_tmdb_movie_credits": _METHOD_CONTRACTS["tmdb_movie_credits"],
        "async_tmdb_movie_recommend": _METHOD_CONTRACTS["tmdb_movie_recommend"],
        "async_tmdb_movie_similar": _METHOD_CONTRACTS["tmdb_movie_similar"],
        "async_tmdb_person_credits": _METHOD_CONTRACTS["tmdb_person_credits"],
        "async_tmdb_person_detail": _METHOD_CONTRACTS["tmdb_person_detail"],
        "async_tmdb_seasons": _METHOD_CONTRACTS["tmdb_seasons"],
        "async_tmdb_trending": _METHOD_CONTRACTS["tmdb_trending"],
        "async_tmdb_tv_credits": _METHOD_CONTRACTS["tmdb_tv_credits"],
        "async_tmdb_tv_recommend": _METHOD_CONTRACTS["tmdb_tv_recommend"],
        "async_tmdb_tv_similar": _METHOD_CONTRACTS["tmdb_tv_similar"],
        "async_identify_music_by_fingerprint": _METHOD_CONTRACTS["identify_music_by_fingerprint"],
        "async_match_music_album": _METHOD_CONTRACTS["match_music_album"],
        "async_refresh_torrents": _METHOD_CONTRACTS["refresh_torrents"],
    }
)

_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_interests",
    "async_douban_movie_recommend",
    "async_douban_movie_reviews",
    "async_douban_person_credits",
    "async_douban_person_detail",
    "async_douban_tv_credits",
    "async_douban_tv_interests",
    "async_douban_tv_recommend",
    "async_douban_tv_reviews",
    "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_interests",
    "douban_movie_recommend",
    "douban_movie_reviews",
    "douban_person_credits",
    "douban_person_detail",
    "douban_tv_credits",
    "douban_tv_interests",
    "douban_tv_recommend",
    "douban_tv_reviews",
    "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",
    "mark_message_processing_finished",
    "mark_message_processing_started",
    "match_doubaninfo",
    "match_music_album",
    "match_tmdbinfo",
    "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",
    "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_get_media_auxiliary_info",
            "async_match_",
            "async_obtain_images",
            "async_recognize_media",
            "async_update_recognize_cache",
            "match_",
            "obtain_images",
            "get_media_auxiliary_info",
            "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 == "clear_cache":
        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 compatible_module_kwargs(
    method: str, callback: Callable[..., Any], kwargs: dict[str, Any],
) -> dict[str, Any]:
    """
    仅移除显式登记的新可选参数，保留旧 provider 签名和其它参数错误。

    接受该参数或 **kwargs 的 provider 收到完整输入；无法检查签名时不推断兼容性。
    """
    optional = get_module_method_contract(method).optional_parameters
    if not optional or not any(name in kwargs for name in optional):
        return kwargs
    try:
        parameters = inspect.signature(callback).parameters
    except (TypeError, ValueError):
        return kwargs
    if any(parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in parameters.values()):
        return kwargs
    return {name: value for name, value in kwargs.items() if name not in optional or name in parameters}


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.MODEL: isinstance(result, BaseModel),
        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)