MoviePilot/app/agent/tools/impl/api.py

"""MoviePilot 结构化 API 网关工具。"""

import json
from copy import deepcopy
from functools import lru_cache
from pathlib import Path
from typing import Any, Dict, Literal, Optional, Type, Union, cast

from langchain_core.tools import ToolException
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator

from app.agent.api.arguments import (
    api_input_contract,
    canonical_api_arguments,
    coerce_string_body,
)
from app.agent.api.executor import ApiExecutionContext, ApiExecutionError, MoviePilotApiExecutor
from app.agent.policy.api import API_UNBOUND_READ_OPERATIONS, resolve_api_operation
from app.agent.policy.contracts import ExecutionOutcome, PrincipalRole
from app.agent.policy.sanitizer import summarize_input
from app.agent.tools.base import MoviePilotTool
from app.agent.tools.result import inspect_tool_result
from app.agent.tools.tags import ToolTag
from app.schemas.common import JsonData
from app.schemas.types import NotificationChannel

_TOOL_MESSAGE_OPERATION_MAX_CHARS = 96
_TOOL_MESSAGE_PARAMETER_MAX_CHARS = 320
_SEARCH_TORRENTS_TOOL_TIMEOUT_SECONDS = 300.0

# API 网关顶层请求体只开放对象、数组和 system.upgrade.dev 的固定字符串。
MoviePilotApiBody = Union[Dict[str, JsonData], list[JsonData], Literal["dev"], None]


@lru_cache(maxsize=1)
def _load_api_mcp_input_schema() -> dict[str, Any]:
    """读取由业务 OpenAPI 生成并经漂移测试锁定的外部 MCP schema。"""
    schema_path = (
        Path(__file__).resolve().parents[2]
        / "policy"
        / "resources"
        / "api_mcp_schema.json"
    )
    payload = json.loads(schema_path.read_text(encoding="utf-8"))
    if not isinstance(payload, dict) or not isinstance(payload.get("oneOf"), list):
        raise RuntimeError("moviepilot_api MCP schema 无效")
    return payload


class MoviePilotApiInput(BaseModel):  # type: ignore[misc]
    """MoviePilot API 网关的结构化输入参数。"""

    model_config = ConfigDict(extra="forbid")

    operation_id: str = Field(
        ...,
        description=(
            "Exact allowlisted MoviePilot operation ID selected from the loaded domain Skill. "
            "Never supply a URL, authentication header, or API token."
        ),
    )
    path_params: Dict[str, Any] = Field(
        default_factory=dict,
        description="Route placeholders only, e.g. media.detail uses {\"media_id\": \"27205\"}.",
    )
    query: Dict[str, Any] = Field(
        default_factory=dict,
        description=(
            "Query fields declared by this operation, never flattened at the top level. "
            "Pagination is operation-specific: subscription.execution.list uses limit, not page/count."
        ),
    )
    body: MoviePilotApiBody = Field(
        default=None,
        description=(
            "Request body declared by the selected operation and its loaded Skill contract. "
            "Pass objects and arrays, including nested file items, as native JSON values; "
            "pass null only when the selected operation allows it. "
            "The only string body is the exact value 'dev' for system.upgrade.dev."
        ),
    )

    @field_validator("body", mode="before")  # type: ignore[misc]
    @classmethod
    def _restore_json_string_body(cls, value: Any) -> Any:
        """模型在联合类型 schema 下可能把 body 编码为 JSON 字符串，入模前还原。"""
        return coerce_string_body(value)


class MoviePilotApiTool(MoviePilotTool):
    """
    MoviePilot 结构化 API 网关。

    网关只接受固定 operation ID 和结构化参数，由宿主注册表解析为固定 API
    方法与路径；模型不能提供 URL、认证头、令牌或任意 HTTP 方法。
    """

    name: str = "moviepilot_api"
    tags: list[str] = [
        ToolTag.Read,
        ToolTag.Media,
        ToolTag.Subscription,
        ToolTag.Download,
        ToolTag.Site,
        ToolTag.Plugin,
    ]
    description: str = (
        "Call allowlisted MoviePilot business APIs through operation-specific input contracts. "
        "Load the relevant domain Skill before calling and use operation error feedback to correct inputs. "
        "The ONLY top-level keys are operation_id, path_params, query, body. "
        "Examples (replace sample IDs with IDs from prior results): "
        '{"operation_id":"media.detail","path_params":{"media_id":"27205"},'
        '"query":{"media_source":"tmdb","type_name":"电影"}}; '
        '{"operation_id":"subscription.execution.list","query":{"limit":10}}; '
        '{"operation_id":"site.rss","query":{"page":1,"count":20}}. '
        "Never invent filters or copy pagination fields from another operation. "
        "Arbitrary URLs, commands, authentication endpoints, headers, and tokens are forbidden."
    )
    require_admin: bool = False
    args_schema: Type[BaseModel] = MoviePilotApiInput
    handle_tool_error: bool = True

    _executor: Optional[MoviePilotApiExecutor] = PrivateAttr(default=None)

    def __init__(
        self,
        session_id: str,
        user_id: str,
        *,
        executor: Optional[MoviePilotApiExecutor] = None,
        **kwargs: Any,
    ) -> None:
        """注入可测试的固定 API 执行器。"""
        super().__init__(session_id=session_id, user_id=user_id, **kwargs)
        self._executor = executor

    def get_tool_message(self, **kwargs: Any) -> Optional[str]:
        """生成包含脱敏、有界主要参数的结构化 API 调用提示。"""
        operation_id = summarize_input(
            kwargs.get("operation_id") or "未知操作",
            max_chars=_TOOL_MESSAGE_OPERATION_MAX_CHARS,
        )
        message = f"调用 MoviePilot API：{operation_id}"
        parameters = {
            field_name: field_value
            for field_name in ("path_params", "query", "body")
            if (field_value := kwargs.get(field_name)) is not None
            and not (isinstance(field_value, dict) and not field_value)
        }
        if not parameters:
            return message
        parameter_summary = summarize_input(
            parameters,
            max_chars=_TOOL_MESSAGE_PARAMETER_MAX_CHARS,
        )
        return f"{message}，主要参数：{parameter_summary}"

    def _get_run_timeout_seconds(self, **kwargs: Any) -> Optional[float]:
        """将 search.torrents 的总工具等待时间限制为五分钟。"""
        if kwargs.get("operation_id") == "search.torrents":
            return _SEARCH_TORRENTS_TOOL_TIMEOUT_SECONDS
        return super()._get_run_timeout_seconds(**kwargs)

    def get_mcp_input_schema(self) -> dict[str, Any]:
        """返回包含全部白名单 operation 精确参数的 MCP JSON Schema。"""
        return deepcopy(_load_api_mcp_input_schema())

    @property
    def tool_call_schema(self) -> Type[BaseModel]:
        """本工具没有注入参数，直接保留原模型，防止子集投影丢失 extra=forbid。"""
        return MoviePilotApiInput

    def _parse_input(
        self, tool_input: Union[str, dict[str, Any]], tool_call_id: Optional[str],
    ) -> Union[str, dict[str, Any]]:
        """在 LangChain 解析前校验原始参数，让只读调用也能收到安全纠错回执。"""
        if isinstance(tool_input, dict):
            operation_id = str(tool_input.get("operation_id") or "")
            try:
                self.canonical_arguments(tool_input)
            except (TypeError, ValueError) as error:
                raise ToolException(self._invalid_input_result(operation_id, error)) from error
        return cast(Union[str, dict[str, Any]], super()._parse_input(tool_input, tool_call_id))

    def canonical_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]:
        """用缓存的 operation 合同生成实际执行与持久指纹共用的参数。"""
        return canonical_api_arguments(arguments, _load_api_mcp_input_schema())

    def get_operation_input_contract(self, operation_id: str) -> dict[str, Any]:
        """返回单个 operation 的有界参数合同，供失败回执指导模型重试。"""
        return api_input_contract(operation_id, _load_api_mcp_input_schema())

    def _invalid_input_result(self, operation_id: str, error: Exception) -> str:
        """把参数合同错误转换为不包含原始请求值的模型纠错回执。"""
        contract = self.get_operation_input_contract(operation_id)
        return json.dumps(
            {
                "success": False,
                "error": "invalid_input",
                "operation_id": operation_id,
                "message": (
                    f"{operation_id} 的输入不符合已声明合同（{str(error)}）。"
                    "请按 input_contract 只提交允许字段并补齐 required 字段后重试。"
                ),
                "input_contract": contract,
            },
            ensure_ascii=False,
        )

    async def _resolve_superuser_integration_identity(
        self,
    ) -> tuple[str, Optional[str], bool]:
        """为已验证的管理员集成解析一个真实持久化超级管理员身份。"""
        from app.application.security.auth import build_superuser_token_payload

        payload = await self.run_blocking(
            "db",
            build_superuser_token_payload,
        )
        if payload.sub is None:
            raise ApiExecutionError("管理员集成身份没有持久化用户 ID")
        return str(payload.sub), payload.username, bool(payload.super_user)

    async def _resolve_api_identity(
        self,
        *,
        require_system_admin: bool = False,
    ) -> tuple[str, Optional[str], bool]:
        """把 Web、渠道或集成身份解析为真实 MoviePilot API 用户身份。"""
        raw_user_id = str(self._user_id or "")
        is_authenticated_integration = self._source == "api" or (
            self._channel == NotificationChannel.Web.value
            and self._source in {"openai", "openai.responses", "anthropic"}
        )
        if is_authenticated_integration and bool(self._agent_context.get("is_admin")):
            return await self._resolve_superuser_integration_identity()
        direct_user_channels = {
            NotificationChannel.Web.value,
            NotificationChannel.WebAgent.value,
        }
        is_direct_user_channel = self._channel in direct_user_channels
        if (
            require_system_admin
            and bool(self._agent_context.get("is_admin"))
            and not is_direct_user_channel
        ):
            # 通知渠道管理员延续旧管理员工具语义，但只在管理员 operation
            # 上借用系统管理员集成身份；普通 operation 仍解析其绑定用户。
            return await self._resolve_superuser_integration_identity()
        if self._data is None:
            if is_direct_user_channel and raw_user_id.isdigit():
                return raw_user_id, self._username, bool(self._agent_context.get("is_admin"))
            raise ApiExecutionError("Agent 数据上下文未装配，无法解析 API 用户身份")

        if is_direct_user_channel:
            # Web 入口的持久化用户 ID 是事实源，旧会话用户名不能切换到同名新账号。
            user = await self._data.users.async_get_by_id(int(raw_user_id)) if raw_user_id.isdigit() else None
        elif not self._channel and not self._source:
            # 无渠道的后台任务使用宿主持久化的用户名，保留定时任务的执行身份。
            user = await self._data.users.async_get_by_name(self._username) if self._username else None
        else:
            user = await self._resolve_channel_api_user(raw_user_id)
        if user is None:
            raise ApiExecutionError(self._identity_unavailable_message())
        if not user.is_active:
            raise ApiExecutionError("当前 MoviePilot 用户已停用，请联系管理员启用该用户后重试。重新绑定不能解除停用。")
        return str(user.id), user.name, bool(user.is_superuser)

    def _identity_unavailable_message(self) -> str:
        """按真实前端入口提示绑定步骤；查询仅能确定没有唯一启用绑定，不臆断具体原因。"""
        labels = {
            NotificationChannel.Telegram.value: "Telegram用户",
            NotificationChannel.Discord.value: "Discord用户",
            NotificationChannel.Wechat.value: "企业微信用户",
            NotificationChannel.Feishu.value: "飞书用户",
            NotificationChannel.WechatClawBot.value: "微信 ClawBot 用户",
            NotificationChannel.Slack.value: "Slack用户",
            NotificationChannel.VoceChat.value: "VoceChat用户",
            NotificationChannel.SynologyChat.value: "SynologyChat用户",
            NotificationChannel.QQ.value: "QQ 用户 ID 或 QQ 用户 OpenID（填写与当前发送者 ID 对应的一项）",
        }
        label = labels.get(self._channel or "")
        if label is None:
            if self._channel in {NotificationChannel.Web.value, NotificationChannel.WebAgent.value}:
                return "当前登录身份未对应有效的 MoviePilot 用户，请重新登录；若账号已删除，请联系管理员。此入口无需绑定通知渠道。"
            return "当前任务身份未对应有效的 MoviePilot 用户，请联系管理员检查任务所属账号及身份配置。"
        sender_id = json.dumps(str(self._user_id or ""), ensure_ascii=False)
        return (
            "当前渠道账号未绑定唯一且已启用的 MoviePilot 用户，可能尚未绑定、绑定用户已停用或存在重复绑定。"
            f"请登录要使用的 MoviePilot 账号，打开右上角头像 → 个人信息 → 账号绑定，在「{label}」中填写"
            f"当前渠道发送者 ID {sender_id}，然后保存并重试。请填写完整 ID，不要填写昵称、群 ID 或机器人 ID。"
            "若已经填写，请管理员确认该用户已启用，且同一渠道 ID 没有绑定到多个启用用户。"
        )

    async def _resolve_channel_api_user(self, raw_user_id: str) -> Any:
        """只按渠道稳定 ID 查找绑定用户，昵称和展示用户名不构成认证依据。"""
        data = self._data
        if data is None:
            return None
        try:
            channel = NotificationChannel(self._channel)
        except (TypeError, ValueError):
            return None
        binding_keys = {
            NotificationChannel.Telegram: ("telegram_userid",),
            NotificationChannel.Discord: ("discord_userid",),
            NotificationChannel.Wechat: ("wechat_userid",),
            NotificationChannel.Feishu: ("feishu_userid", "feishu_openid"),
            NotificationChannel.WechatClawBot: ("wechatclawbot_userid",),
            NotificationChannel.Slack: ("slack_userid",),
            NotificationChannel.VoceChat: ("vocechat_userid",),
            NotificationChannel.SynologyChat: ("synologychat_userid",),
            NotificationChannel.QQ: ("qq_userid", "qq_openid"),
        }.get(channel)
        if not binding_keys or not raw_user_id:
            return None
        # userid/openid 是候选字段，仓储必须拒绝匹配到多个用户的歧义绑定。
        username = await self.run_blocking(
            "db", data.users.find_name_by_bindings,
            {key: raw_user_id for key in binding_keys}, match_any=True,
        )
        return await data.users.async_get_by_name(username) if username else None

    async def _get_executor(
        self,
        *,
        require_system_admin: bool = False,
        public_read_only: bool = False,
    ) -> tuple[MoviePilotApiExecutor, bool]:
        """解析执行身份；公共资料使用只能执行白名单读取的宿主认证通道。"""
        if self._executor is not None:
            return self._executor, await self.is_admin_user()
        if public_read_only:
            user_id, username, is_admin = await self._resolve_superuser_integration_identity()
        else:
            user_id, username, is_admin = await self._resolve_api_identity(
                require_system_admin=require_system_admin,
            )
        return (
            MoviePilotApiExecutor(
                context=ApiExecutionContext(
                    user_id=user_id,
                    username=username,
                    is_admin=is_admin,
                    session_id=self._session_id,
                    channel=self._channel,
                    source=self._source,
                    public_read_only=public_read_only,
                )
            ),
            is_admin,
        )

    async def run(  # type: ignore[override]
        self,
        operation_id: str,
        path_params: Optional[Dict[str, Any]] = None,
        query: Optional[Dict[str, Any]] = None,
        body: Any = None,
        **kwargs: Any,
    ) -> str:
        """
        执行一个白名单 MoviePilot API 操作。

        :param operation_id: 稳定 API 操作标识
        :param path_params: 路径参数
        :param query: 查询参数
        :param body: JSON 请求体
        :return: 结构化业务结果或安全错误消息
        """
        spec = resolve_api_operation(operation_id)
        if spec is None:
            return json.dumps(
                {
                    "success": False,
                    "error": "unknown_operation",
                    "message": f"未允许的 MoviePilot API 操作：{operation_id}",
                },
                ensure_ascii=False,
            )
        try:
            arguments: dict[str, Any] = {"operation_id": operation_id, **kwargs}
            if path_params is not None:
                arguments["path_params"] = path_params
            if query is not None:
                arguments["query"] = query
            if body is not None:
                arguments["body"] = body
            self.canonical_arguments(arguments)
        except (TypeError, ValueError) as error:
            return self._invalid_input_result(operation_id, error)
        try:
            requires_system_admin = spec.required_role is PrincipalRole.SYSTEM_ADMIN
            executor, is_admin = await self._get_executor(
                require_system_admin=requires_system_admin,
                public_read_only=operation_id in API_UNBOUND_READ_OPERATIONS,
            )
            if requires_system_admin and not is_admin:
                return json.dumps(
                    {
                        "success": False,
                        "error": "permission_denied",
                        "message": "This MoviePilot API operation requires a system administrator.",
                    },
                    ensure_ascii=False,
                )
            result = await executor.execute(
                operation_id,
                path_params=path_params,
                query=query,
                body=body,
            )
            try:
                payload = json.loads(result)
            except (TypeError, ValueError):
                payload = None
            if (
                isinstance(payload, dict)
                and payload.get("error") == "api_error"
                and payload.get("status_code") in {400, 422}
            ):
                payload["operation_id"] = operation_id
                payload["message"] = (
                    f"{operation_id} 被 API 拒绝，请根据 input_contract 修正输入后重试。"
                )
                payload["input_contract"] = self.get_operation_input_contract(operation_id)
                result = json.dumps(payload, ensure_ascii=False)
            if operation_id == "scheduler.run" and inspect_tool_result(result) is ExecutionOutcome.SUCCEEDED:
                payload = json.loads(result)
                if isinstance(payload, dict) and payload.get("success") is True:
                    payload["execution_outcome"] = "pending"
                    return json.dumps(payload, ensure_ascii=False)
            return result
        except ApiExecutionError as error:
            failure: dict[str, Any] = {
                "success": False,
                "error": "operation_unavailable",
                "message": str(error),
            }
            if error.external_may_continue:
                failure["execution_outcome"] = "unknown"
                failure["message"] += "；操作可能已生效，请先只读核验实际状态，避免重复执行。"
            return json.dumps(
                failure,
                ensure_ascii=False,
            )


__all__ = ["MoviePilotApiInput", "MoviePilotApiTool"]