mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-11-13 09:10:45 +08:00
488 lines
20 KiB
Python
488 lines
20 KiB
Python
"""字符串模块方法协议的可检查契约清单。"""
|
||
|
||
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"
|
||
|
||
|
||
class ModuleResultShape(StrEnum):
|
||
"""描述模块 provider 返回值的基础 Python 形状。"""
|
||
|
||
ANY = "any"
|
||
LIST = "list"
|
||
STRING = "string"
|
||
MAPPING = "mapping"
|
||
BOOLEAN = "boolean"
|
||
|
||
|
||
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]", aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE,
|
||
required_parameters=("meta", "media_source"),
|
||
),
|
||
"obtain_images": ModuleMethodContract(family="media-recognition", input_contract="MediaInfo", result_contract="MediaInfo | None", 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="list[MediaServerItem]", aggregation=ModuleResultAggregation.ORDERED_LIST_MERGE, 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")),
|
||
"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")),
|
||
"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")),
|
||
"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")),
|
||
}
|
||
|
||
_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),
|
||
}
|
||
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)
|