refactor(browser): decouple Playwright types with protocol interfaces and remove direct dependency

app/helper/browser.py

@@ -1,13 +1,77 @@
 import uuid
-from typing import Callable, Any, Optional
-
-from playwright.sync_api import BrowserContext, Page
+from typing import Callable, Any, Optional, Protocol
 
 from app.core.config import settings
 from app.log import logger
 from app.utils.http import RequestUtils, cookie_parse
 
 
+class BrowserElement(Protocol):
+    """
+    页面元素的最小接口，避免为了类型标注直接导入 Playwright。
+    """
+
+    def is_visible(self) -> bool:
+        ...
+
+    def fill(self, value: str) -> None:
+        ...
+
+
+class BrowserContext(Protocol):
+    """
+    CloakBrowser 返回的上下文只需要满足这些能力即可。
+    """
+
+    def new_page(self) -> "BrowserPage":
+        ...
+
+    def cookies(self) -> list[dict[str, Any]]:
+        ...
+
+    def close(self) -> None:
+        ...
+
+
+class BrowserPage(Protocol):
+    """
+    CloakBrowser 页面对象的最小接口，覆盖 helper 和登录流程当前用到的方法。
+    """
+
+    context: BrowserContext
+    url: str
+
+    def set_extra_http_headers(self, headers: dict[str, str]) -> None:
+        ...
+
+    def goto(self, url: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def wait_for_load_state(self, state: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def wait_for_selector(self, selector: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def fill(self, selector: str, value: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def click(self, selector: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def query_selector(self, selector: str) -> Optional[BrowserElement]:
+        ...
+
+    def content(self) -> str:
+        ...
+
+    def evaluate(self, expression: str, *args: Any, **kwargs: Any) -> Any:
+        ...
+
+    def close(self) -> None:
+        ...
+
+
 class PlaywrightHelper:
     def __init__(self, browser_type: Optional[str] = None, *args, **kwargs):
         """
@@ -145,7 +209,7 @@ class PlaywrightHelper:
                     logger.warning(f"清理 FlareSolverr 会话失败: {str(e)}")
 
     def action(self, url: str,
-               callback: Callable,
+               callback: Callable[[BrowserPage], Any],
                cookies: Optional[str] = None,
                ua: Optional[str] = None,
                proxies: Optional[dict] = None,

app/helper/cookie.py

@@ -2,9 +2,8 @@ import base64
 from typing import Tuple, Optional
 
 from lxml import etree
-from playwright.sync_api import Page
 
-from app.helper.browser import PlaywrightHelper
+from app.helper.browser import BrowserPage, PlaywrightHelper
 from app.helper.ocr import OcrHelper
 from app.helper.twofa import TwoFactorAuth
 from app.log import logger
@@ -88,7 +87,7 @@ class CookieHelper:
         :return: cookie、ua、message
         """
 
-        def __page_handler(page: Page) -> Tuple[Optional[str], Optional[str], str]:
+        def __page_handler(page: BrowserPage) -> Tuple[Optional[str], Optional[str], str]:
             """
             页面处理
             :return: Cookie和UA

requirements.in

@@ -39,7 +39,6 @@ pillow-avif-plugin~=1.5.2
 pyTelegramBotAPI~=4.27.0
 telegramify-markdown~=0.5.2
 cloakbrowser~=0.3.28
-playwright~=1.53.0
 torrentool~=1.2.0
 slack-bolt~=1.23.0
 slack-sdk~=3.35.0