feat: add captcha recognition agent tool

app/agent/tools/factory.py

@@ -37,6 +37,7 @@ from app.agent.tools.impl.query_media_detail import QueryMediaDetailTool
 from app.agent.tools.impl.search_torrents import SearchTorrentsTool
 from app.agent.tools.impl.get_search_results import GetSearchResultsTool
 from app.agent.tools.impl.search_web import SearchWebTool
+from app.agent.tools.impl.recognize_captcha import RecognizeCaptchaTool
 from app.agent.tools.impl.send_message import SendMessageTool
 from app.agent.tools.impl.ask_user_choice import AskUserChoiceTool
 from app.agent.tools.impl.send_local_file import SendLocalFileTool
@@ -165,6 +166,7 @@ class MoviePilotToolFactory:
             SearchTorrentsTool,
             GetSearchResultsTool,
             SearchWebTool,
+            RecognizeCaptchaTool,
             AddDownloadTool,
             QuerySubscribesTool,
             QuerySubscribeSharesTool,

app/agent/tools/impl/recognize_captcha.py

@@ -0,0 +1,167 @@
+"""识别图形验证码工具。"""
+
+import json
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field
+
+from app.agent.tools.base import MoviePilotTool
+from app.agent.tools.tags import ToolTag
+from app.helper.browser import BrowserSessionHelper
+from app.helper.ocr import OcrHelper
+from app.log import logger
+
+
+class RecognizeCaptchaInput(BaseModel):
+    """识别图形验证码工具的输入参数模型。"""
+
+    explanation: Optional[str] = Field(
+        None,
+        description="Clear explanation of why this captcha image needs to be recognized",
+    )
+    image_url: str = Field(
+        ...,
+        description=(
+            "Captcha image URL obtained from the browser page, usually an img.src value. "
+            "Supports http/https URLs and data:image/...;base64,... URLs."
+        ),
+    )
+    cookie: Optional[str] = Field(
+        None,
+        description=(
+            "Optional Cookie header used to download the captcha image when the image URL "
+            "requires the same authenticated browser session."
+        ),
+    )
+    user_agent: Optional[str] = Field(
+        None,
+        description="Optional User-Agent used when downloading the captcha image.",
+    )
+    allow_private_network: bool = Field(
+        False,
+        description="Allow captcha image URLs on localhost, loopback, private, or link-local addresses.",
+    )
+
+
+class RecognizeCaptchaTool(MoviePilotTool):
+    """
+    图形验证码识别工具，供 Agent 在浏览器自动化登录时读取验证码文本。
+    """
+
+    name: str = "recognize_captcha"
+    tags: list[str] = [
+        ToolTag.Read,
+        ToolTag.Web,
+    ]
+    description: str = (
+        "Recognize a graphic captcha image and return the captcha text. "
+        "Use this after browser automation extracts a captcha img.src from the page. "
+        "Pass cookie and user_agent when the image URL requires the current browser session. "
+        "Supports http/https image URLs and data:image/...;base64,... URLs. "
+        "For safety, localhost and private network URLs are blocked by default unless "
+        "allow_private_network is true."
+    )
+    args_schema: Type[BaseModel] = RecognizeCaptchaInput
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        """根据验证码图片参数生成友好的提示消息。"""
+        image_url = str(kwargs.get("image_url") or "")
+        if image_url.lower().startswith("data:image/"):
+            return "识别图形验证码: data image"
+        return f"识别图形验证码: {image_url}"
+
+    @staticmethod
+    def _recognize_captcha_sync(
+        image_url: str,
+        cookie: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        allow_private_network: bool = False,
+    ) -> str:
+        """
+        在线程池中下载并识别验证码图片。
+
+        :param image_url: 验证码图片地址
+        :param cookie: 下载图片时使用的 Cookie
+        :param user_agent: 下载图片时使用的 User-Agent
+        :param allow_private_network: 是否允许访问本机或私网地址
+        :return: 验证码文本，失败时返回空字符串
+        """
+        clean_url = (image_url or "").strip()
+        if not clean_url:
+            return ""
+        if not clean_url.lower().startswith("data:image/"):
+            BrowserSessionHelper.validate_url(
+                clean_url,
+                allow_private_network=allow_private_network,
+            )
+        return OcrHelper().get_captcha_text(
+            image_url=clean_url,
+            cookie=cookie,
+            ua=user_agent,
+        )
+
+    async def run(
+        self,
+        image_url: str,
+        cookie: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        allow_private_network: bool = False,
+        **kwargs,
+    ) -> str:
+        """
+        识别指定图片地址中的图形验证码文本。
+
+        :param image_url: 验证码图片地址
+        :param cookie: 下载图片时使用的 Cookie
+        :param user_agent: 下载图片时使用的 User-Agent
+        :param allow_private_network: 是否允许访问本机或私网地址
+        :return: JSON 格式的识别结果
+        """
+        logger.info(f"执行工具: {self.name}, 参数: image_url={image_url}")
+
+        try:
+            captcha_text = await self.run_blocking(
+                "web",
+                self._recognize_captcha_sync,
+                image_url,
+                cookie,
+                user_agent,
+                allow_private_network,
+            )
+            if captcha_text:
+                return json.dumps(
+                    {
+                        "success": True,
+                        "captcha_text": captcha_text,
+                        "message": "验证码识别成功",
+                    },
+                    ensure_ascii=False,
+                )
+            return json.dumps(
+                {
+                    "success": False,
+                    "captcha_text": "",
+                    "message": "验证码识别失败或未返回内容",
+                },
+                ensure_ascii=False,
+            )
+        except ValueError as err:
+            logger.warning(f"验证码图片地址校验失败: {str(err)}")
+            return json.dumps(
+                {
+                    "success": False,
+                    "captcha_text": "",
+                    "message": str(err),
+                },
+                ensure_ascii=False,
+            )
+        except Exception as err:
+            logger.error(f"识别图形验证码失败: {str(err)}", exc_info=True)
+            return json.dumps(
+                {
+                    "success": False,
+                    "captcha_text": "",
+                    "message": f"识别图形验证码时发生错误: {str(err)}",
+                },
+                ensure_ascii=False,
+            )

app/helper/ocr.py

@@ -6,31 +6,63 @@ from app.utils.http import RequestUtils
 
 
 class OcrHelper:
+    """
+    OCR 辅助类，负责获取验证码图片并调用 OCR 服务识别文本。
+    """
 
     _ocr_b64_url = f"{settings.OCR_HOST}/captcha/base64"
 
-    def get_captcha_text(self, image_url: Optional[str] = None, image_b64: Optional[str] = None,
-                         cookie: Optional[str] = None, ua: Optional[str] = None):
+    def get_captcha_text(
+            self,
+            image_url: Optional[str] = None,
+            image_b64: Optional[str] = None,
+            cookie: Optional[str] = None,
+            ua: Optional[str] = None,
+    ) -> str:
         """
         根据图片地址，获取验证码图片，并识别内容
         :param image_url: 图片地址
         :param image_b64: 图片base64，跳过图片地址下载
         :param cookie: 下载图片使用的cookie
         :param ua: 下载图片使用的ua
+        :return: 验证码识别结果，失败时返回空字符串
         """
+        image_b64 = self._normalize_image_base64(image_b64)
         if image_url:
-            ret = RequestUtils(ua=ua,
-                               cookies=cookie).get_res(image_url)
-            if ret is not None:
-                image_bin = ret.content
-                if not image_bin:
-                    return ""
-                image_b64 = base64.b64encode(image_bin).decode()
+            data_url_b64 = self._extract_data_url_base64(image_url)
+            if data_url_b64:
+                image_b64 = data_url_b64
+            else:
+                ret = RequestUtils(ua=ua,
+                                   cookies=cookie).get_res(image_url)
+                if ret is not None:
+                    image_bin = ret.content
+                    if not image_bin:
+                        return ""
+                    image_b64 = base64.b64encode(image_bin).decode()
         if not image_b64:
             return ""
         ret = RequestUtils(content_type="application/json").post_res(
             url=self._ocr_b64_url,
             json={"base64_img": image_b64})
         if ret:
-            return ret.json().get("result")
+            return ret.json().get("result") or ""
         return ""
+
+    @staticmethod
+    def _normalize_image_base64(image_b64: Optional[str]) -> str:
+        """规范化外部传入的图片 base64 内容。"""
+        if not image_b64:
+            return ""
+        return OcrHelper._extract_data_url_base64(image_b64) or image_b64.strip()
+
+    @staticmethod
+    def _extract_data_url_base64(image_url: Optional[str]) -> str:
+        """从 data:image/...;base64,... 地址中提取纯 base64 内容。"""
+        image_url = (image_url or "").strip()
+        if not image_url.lower().startswith("data:image/"):
+            return ""
+        metadata, separator, data = image_url.partition(",")
+        if not separator or ";base64" not in metadata.lower():
+            return ""
+        return data.strip()