rootbrowse 0.2.0__py3-none-any.whl

rootbrowse/__init__.py

@@ -0,0 +1,39 @@
+"""RootBrowse - Python 浏览器自动化 MCP 框架"""
+
+from ._version import __version__
+from .browser import Browser
+from .tab_manager import TabManager
+from .element_operator import ElementOperator
+from .page_scanner import PageScanner
+from .types import Region, Element, RegionSummary, ElementPreview, OperationResult
+from .exceptions import (
+    RootBrowseError,
+    BrowserError,
+    ElementNotFoundError,
+    RegionNotFoundError,
+    TabNotFoundError,
+    OperationError,
+    StateFileError,
+    PageLoadError,
+)
+
+__all__ = [
+    "__version__",
+    "Browser",
+    "TabManager",
+    "ElementOperator",
+    "PageScanner",
+    "Region",
+    "Element",
+    "RegionSummary",
+    "ElementPreview",
+    "OperationResult",
+    "RootBrowseError",
+    "BrowserError",
+    "ElementNotFoundError",
+    "RegionNotFoundError",
+    "TabNotFoundError",
+    "OperationError",
+    "StateFileError",
+    "PageLoadError",
+]

rootbrowse/_version.py

@@ -0,0 +1,3 @@
+"""版本信息"""
+
+__version__ = "0.1.0"

rootbrowse/browser.py

@@ -0,0 +1,181 @@
+"""浏览器主入口"""
+
+import json
+from typing import Any
+
+from .constants import DEFAULT_URL
+from .tab_manager import TabManager
+from .element_operator import ElementOperator
+from .page_scanner import PageScanner
+from .types import Region, RegionSummary, Element, ElementPreview, OperationResult
+from .exceptions import BrowserError, StateFileError, PageLoadError
+
+
+class Browser:
+    """
+    浏览器主入口，组合 TabManager、ElementOperator、PageScanner
+
+    AI 调用方式：
+        browser = Browser()                    # 默认打开 bing.com
+        browser = Browser('https://example.com') # 指定 URL
+        browser.view.get_regions()
+        browser.act.click('r1')
+    """
+
+    def __init__(self, page: Any | None = None, url: str | None = None, headless: bool = True):
+        """
+        初始化 Browser
+
+        Args:
+            page: DrissionPage ChromiumPage 实例，None 则自动创建
+            url: 默认打开的 URL，配合 page 为 None 时使用
+            headless: 是否使用无头模式，默认 Ture（无头浏览器）
+        """
+        page_2 = page
+        if page is None:
+            from DrissionPage import ChromiumPage, ChromiumOptions
+            opts = ChromiumOptions()
+            # 有头还是无头浏览器
+            if headless:
+                opts.headless(True)
+            else:
+                opts.headless(False)
+
+            page = ChromiumPage(addr_or_opts=opts)
+
+        self._page = page
+        self._closed = False
+
+        # 初始化子模块
+        self._page_scanner = PageScanner(self._page)
+        self._tab_manager = TabManager(self._page)
+        self._element_operator = ElementOperator(self._page, self._page_scanner._element_map)
+
+        # 打开默认 URL（只有当 page 和 url 都没提供时才自动打开）
+        if page_2 is None and url is None:
+            self.get(DEFAULT_URL)
+
+    @classmethod
+    def create(cls, url: str | None = None) -> "Browser":
+        """
+        工厂方法：创建 Browser 并打开指定 URL
+
+        Args:
+            url: 目标 URL，None 则打开 DEFAULT_URL (bing.com)
+
+        Returns:
+            Browser 实例
+        """
+        if url is None:
+            url = DEFAULT_URL
+        return cls(url=url)
+
+    @property
+    def tabs(self) -> TabManager:
+        """标签页管理器"""
+        return self._tab_manager
+
+    @property
+    def view(self) -> PageScanner:
+        """页面扫描器"""
+        return self._page_scanner
+
+    @property
+    def act(self) -> ElementOperator:
+        """元素操作器"""
+        return self._element_operator
+
+    def get(self, url: str, timeout: float = 30) -> dict:
+        """
+        打开 URL
+
+        Args:
+            url: 目标 URL
+            timeout: 超时时间（秒）
+
+        Returns:
+            dict: {url, title}
+
+        Raises:
+            PageLoadError: 页面加载失败
+        """
+        try:
+            self._page.get(url, timeout=timeout)
+            title = self._page.title or ""
+            return {"url": url, "title": title}
+        except Exception as e:
+            raise PageLoadError(f"Failed to load page: {url}, error: {e}")
+
+    def screenshot(
+        self,
+        path: str | None = None,
+        annotate: list[list[int]] | None = None
+    ) -> str:
+        """
+        页面截图
+
+        Args:
+            path: 保存路径，None 则返回 base64 字符串
+            annotate: 标注区域列表 [[x1,y1,x2,y2], ...]
+
+        Returns:
+            str: 文件路径或 base64 字符串
+        """
+        if path:
+            self._page.get_screenshot(path=path)
+            return path
+        else:
+            return self._page.screenshot()
+
+    def save_state(self, path: str) -> None:
+        """
+        保存浏览器状态（cookies）
+
+        Args:
+            path: 保存路径
+
+        Raises:
+            StateFileError: 保存失败
+        """
+        try:
+            cookies = self._page.cookies()
+            data = {
+                'version': '0.1.0',
+                'cookies': cookies if isinstance(cookies, list) else list(cookies),
+                'saved_at': self._get_timestamp(),
+            }
+            with open(path, 'w', encoding='utf-8') as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+        except Exception as e:
+            raise StateFileError(f"Failed to save state: {e}")
+
+    def load_state(self, path: str) -> None:
+        """
+        恢复浏览器状态（cookies）
+
+        Args:
+            path: 状态文件路径
+
+        Raises:
+            StateFileError: 恢复失败
+        """
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+            cookies = data.get('cookies', [])
+            if cookies:
+                self._page.set.cookies(cookies)
+        except Exception as e:
+            raise StateFileError(f"Failed to load state: {e}")
+
+    @staticmethod
+    def _get_timestamp() -> str:
+        """返回当前时间戳 ISO 格式"""
+        from datetime import datetime, timezone
+        return datetime.now(timezone.utc).isoformat()
+
+    def close(self) -> None:
+        """关闭浏览器"""
+        if not self._closed:
+            self._page.quit()
+            self._closed = True

rootbrowse/constants.py

@@ -0,0 +1,62 @@
+"""常量配置"""
+
+# 默认 URL
+DEFAULT_URL = "https://www.bing.com"
+
+# 可交互的 HTML 标签（可被点击、输入、选择的元素）
+INTERACTIVE_TAGS = [
+    'a',           # 链接
+    'button',      # 按钮
+    'input',       # 输入框
+    'select',      # 下拉框
+    'textarea',    # 文本域
+    'details',     # 可折叠
+    'summary',     # 可折叠标题
+    'menuitem',    # 菜单项
+]
+
+# 可输入的 HTML 标签
+INPUT_TAGS = [
+    'input',
+    'textarea',
+    'select',
+]
+
+# 可点击的 HTML 标签
+CLICKABLE_TAGS = [
+    'a',
+    'button',
+    'input',
+    'details',
+    'summary',
+    'menuitem',
+]
+
+# ARIA role 映射
+ROLE_TAG_MAP = {
+    'link': 'a',
+    'button': 'button',
+    'textbox': 'input',
+    'searchbox': 'input',
+    'checkbox': 'input',
+    'radio': 'input',
+    'menuitem': 'menuitem',
+}
+
+# 区域 ID 命名
+REGION_ID_HEADER = 'header'
+REGION_ID_MAIN = 'main'
+REGION_ID_SIDEBAR = 'sidebar'
+REGION_ID_FOOTER = 'footer'
+REGION_ID_NAV = 'nav'
+
+# 默认配置
+DEFAULT_LIMIT = 20
+DEFAULT_OFFSET = 0
+DEFAULT_TIMEOUT = 10
+
+# ref 前缀
+REF_PREFIX = 'r'
+
+# 状态文件扩展名
+STATE_FILE_EXTENSION = '.state.json'

rootbrowse/element_operator.py

@@ -0,0 +1,219 @@
+"""元素操作器"""
+
+from typing import Any
+
+from .types import Element, OperationResult
+from .exceptions import ElementNotFoundError
+
+
+class ElementOperator:
+    """元素操作器，执行点击、输入、悬停等操作"""
+
+    def __init__(self, page: Any, element_map: dict[str, Element]):
+        """
+        初始化 ElementOperator
+
+        Args:
+            page: DrissionPage ChromiumPage 实例
+            element_map: ref -> Element 映射表
+        """
+        self._page = page
+        self._element_map = element_map
+
+    def click(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        点击元素
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型，不指定则自动推断
+
+        Returns:
+            OperationResult: {success, new_url?, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').click()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def input_by_ref(
+        self, locator: str, text: str, clear: bool = False, locator_type: str | None = None
+    ) -> OperationResult:
+        """
+        向输入框写入文字
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            text: 要输入的文字
+            clear: 是否先清空输入框
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            ele = self._page.ele(f'xpath={xpath}')
+            if clear:
+                ele.clear()
+            ele.input(text)
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def hover(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        悬停在元素上
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').hover()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def double_click(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        双击元素
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').double_click()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def right_click(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        右键点击元素
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').right_click()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def submit(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        提交表单
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').submit()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def clear(self, locator: str, locator_type: str | None = None) -> OperationResult:
+        """
+        清空输入框
+
+        Args:
+            locator: 定位符（ref / xpath / role / text）
+            locator_type: 定位类型
+
+        Returns:
+            OperationResult: {success, error?}
+        """
+        try:
+            xpath = self._resolve_locator(locator, locator_type)
+            self._page.ele(f'xpath={xpath}').clear()
+            return OperationResult(success=True)
+        except Exception as e:
+            return OperationResult(success=False, error=str(e))
+
+    def send_enter(self) -> None:
+        """发送回车键"""
+        self._page.run_js(
+            "document.activeElement.dispatchEvent(new KeyboardEvent('keydown', {key: 'Enter', code: 'Enter', keyCode: 13}));"
+        )
+        self._page.wait(0.1)
+
+    def ref_to_xpath(self, ref: str) -> str:
+        """
+        通过 ref 获取 xpath（内部方法，供外部调用）
+
+        Args:
+            ref: 元素引用 ID
+
+        Returns:
+            xpath 路径
+
+        Raises:
+            ElementNotFoundError: 元素不存在
+        """
+        if ref not in self._element_map:
+            raise ElementNotFoundError(f"Element not found: {ref}")
+        return self._element_map[ref].xpath
+
+    def _resolve_locator(self, locator: str, locator_type: str | None = None) -> str:
+        """
+        解析定位符，ref 需要查表转 xpath，其他直接返回
+
+        Args:
+            locator: 定位符
+            locator_type: 定位类型
+
+        Returns:
+            xpath 字符串
+
+        Raises:
+            ElementNotFoundError: ref 不存在
+        """
+        # 指定了类型
+        if locator_type == "ref":
+            return self.ref_to_xpath(locator)
+        elif locator_type:
+            return locator
+
+        # 自动推断：ref 查表，其他直接返回
+        if self._is_ref(locator):
+            return self.ref_to_xpath(locator)
+        return locator
+
+    def _is_ref(self, locator: str) -> bool:
+        """
+        判断是否为 ref（格式：r + 数字）
+
+        Args:
+            locator: 定位符
+
+        Returns:
+            是否为 ref
+        """
+        if not locator:
+            return False
+        if locator.startswith("r") and locator[1:].isdigit():
+            return True
+        return False

rootbrowse/exceptions.py

@@ -0,0 +1,41 @@
+"""自定义异常"""
+
+
+class RootBrowseError(Exception):
+    """RootBrowse 基异常"""
+    pass
+
+
+class BrowserError(RootBrowseError):
+    """浏览器相关错误"""
+    pass
+
+
+class ElementNotFoundError(RootBrowseError):
+    """元素未找到"""
+    pass
+
+
+class RegionNotFoundError(RootBrowseError):
+    """区域未找到"""
+    pass
+
+
+class TabNotFoundError(RootBrowseError):
+    """标签页未找到"""
+    pass
+
+
+class OperationError(RootBrowseError):
+    """操作失败"""
+    pass
+
+
+class StateFileError(RootBrowseError):
+    """状态文件相关错误"""
+    pass
+
+
+class PageLoadError(RootBrowseError):
+    """页面加载失败"""
+    pass