rootbrowse 0.2.0__tar.gz

rootbrowse-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+
+# IDE
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+learn-drissionpage/
+project_idea.md

rootbrowse-0.2.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-16
+
+### Added
+
+- **区域识别** — 实现真正的语义区域检测
+  - `browser.page` → `browser.view` 属性重命名
+  - `_detect_regions()`: body 直接子元素动态检测，排除噪音标签
+  - `_guess_region_label()`: 根据 id/class 关键词猜测区域名称
+  - `_element_to_region`: 记录元素与区域的归属关系
+  - `_get_refs_in_region()`: 按 region_id 过滤元素
+  - `save_state(path)`: cookies 序列化到 JSON 文件
+  - `load_state(path)`: 从 JSON 文件恢复 cookies
+
+### Changed
+
+- `Browser.page` 属性重命名为 `Browser.view`
+- Region id 格式从 `"main"` 改为 `"region_N"`
+
+## [0.1.0] - 2026-05-10
+
+### Added
+
+- **types.py** — 数据类定义
+  - `Region`: 页面语义区块
+  - `Element`: 可交互元素
+  - `RegionSummary`: 区域摘要
+  - `ElementPreview`: 元素摘要
+  - `OperationResult`: 操作结果
+
+- **constants.py** — 常量配置
+  - `INTERACTIVE_TAGS`: 可交互 HTML 标签列表
+  - `INPUT_TAGS`: 可输入标签列表
+  - `CLICKABLE_TAGS`: 可点击标签列表
+  - `ROLE_TAG_MAP`: ARIA role 映射
+  - `DEFAULT_LIMIT`, `DEFAULT_OFFSET`: 分页配置
+  - `REF_PREFIX`: ref 前缀 ('r')
+
+- **exceptions.py** — 自定义异常
+  - `RootBrowseError` (基异常)
+  - `BrowserError`, `ElementNotFoundError`, `RegionNotFoundError`
+  - `TabNotFoundError`, `OperationError`, `StateFileError`, `PageLoadError`
+
+- **tab_manager.py** — 标签页管理器
+  - `new_tab(url)`: 打开新标签页
+  - `close_tab(index)`: 关闭标签页
+  - `switch_to_tab(index)`: 切换标签页
+  - `tabs_count()`: 获取标签页数量
+  - `current_index()`: 获取当前索引
+
+- **element_operator.py** — 元素操作器
+  - `click(locator)`: 点击元素
+  - `input_by_ref(locator, text, clear)`: 向输入框写入文字
+  - `hover(locator)`: 悬停
+  - `double_click(locator)`: 双击
+  - `right_click(locator)`: 右键
+  - `submit(locator)`: 提交表单
+  - `clear(locator)`: 清空输入框
+  - `send_enter()`: 发送回车键
+  - `ref_to_xpath(ref)`: 通过 ref 获取 xpath
+
+- **page_scanner.py** — 页面扫描器
+  - `get_regions()`: 获取页面语义区块列表
+  - `get_region_summary(region_id)`: 获取区域统计摘要
+  - `match_element(**filters)`: 按条件筛选元素摘要列表
+  - `get_element(ref)`: 获取完整元素信息
+  - `find_element(by, value, filter)`: 多维度精确定位元素
+
+- **browser.py** — 浏览器主入口
+  - `get(url, timeout)`: 打开 URL
+  - `screenshot(path, annotate)`: 页面截图
+  - `save_state(path)`: 保存浏览器状态
+  - `load_state(path)`: 恢复浏览器状态
+  - `close()`: 关闭浏览器
+
+- **test/** — 完整测试套件
+  - 124 tests covering all modules

rootbrowse-0.2.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: rootbrowse
+Version: 0.2.0
+Summary: Python browser automation MCP framework for AI Agents
+Project-URL: Homepage, https://github.com/zimvir/RootBrowse
+Project-URL: Repository, https://github.com/zimvir/RootBrowse
+Author: zimvir
+License-Expression: MIT
+Keywords: agent,ai,automation,browser,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RootBrowse
+
+Python 浏览器自动化 MCP 框架，为 AI Agent 提供结构化的浏览器交互能力。基于 DrissionPage 构建。
+
+## 核心特性
+
+- **区域化拆分** — 将页面 DOM 按语义区块分组，解决复杂页面的信息过载问题
+- **ref 精确引用** — 为每个可交互元素生成内部 ID (r1, r2, r3...)，避免文字匹配的不确定性
+- **渐进式获取** — get_regions → get_region_summary → match_element → get_element，按需逐步深入
+- **TabManager 状态自管理** — 内部维护标签页状态，不依赖 DrissionPage API 查询
+
+## 安装
+
+```bash
+pip install rootbrowse
+```
+
+## 快速开始
+
+```python
+from DrissionPage import ChromiumPage
+from rootbrowse import Browser
+
+# 创建浏览器实例
+page = ChromiumPage()
+browser = Browser(page)
+
+# 打开网页
+browser.get('https://example.com')
+
+# 获取页面区块
+regions = browser.view.get_regions()
+print(regions)  # [Region(id='region_1', label='容器', node_count=87), ...]
+
+# 获取区块统计摘要
+summary = browser.view.get_region_summary('region_1')
+print(f"元素数量: {summary.count}")
+
+# 按条件筛选元素
+elements = browser.view.match_element(tag='a', text_contains='Python', limit=20)
+print(elements)  # [ElementPreview(ref='r5', text='Python 入门', ...), ...]
+
+# 获取完整元素信息
+ele = browser.view.get_element('r5')
+print(f"点击: {ele.text} -> {ele.attrs['href']}")
+
+# 执行操作
+result = browser.act.click('r5')
+print(f"点击结果: {result.success}")
+
+# 关闭浏览器
+browser.close()
+```
+
+## AI 工作流
+
+```
+用户指令
+    ↓
+get_regions()              → 查看页面有哪些区块
+get_region_summary(id)     → 查看区块统计（标签分布、role 分布）
+match_element(id, ...)     → 按条件筛选元素（摘要列表）
+get_element(ref)          → 获取元素完整信息
+ElementOperator 操作      → 点击、输入、悬停等
+```
+
+## 核心概念
+
+### ref（内部引用 ID）
+
+HTML 元素大多数没有 `id` 属性。RootBrowse 为每个可交互元素生成 `ref`（r1, r2, r3...），作为内部引用。
+
+```python
+# 原始 HTML: <a href="/python">Python 入门</a>
+# 生成 ref 后
+Element(ref="r1", tag="a", text="Python 入门", xpath="...", attrs={...})
+```
+
+AI 用 `ref` 操作元素，不依赖原始 HTML 的 id 或文字匹配。
+
+### 区域化拆分
+
+页面 DOM 有几千个节点，直接给 AI 无法处理。RootBrowse 按语义区块拆分：
+
+```
+页面 DOM
+    ↓ 按语义区域分组（header, main, sidebar 等）
+    ↓ 过滤噪音（script, style, meta）
+    ↓ 统计每个区域的节点数
+返回：Region 列表，AI 选择进入哪个区域
+```
+
+### 渐进式获取
+
+```
+get_regions()           → 看有哪些区块
+get_region_summary()     → 看区块统计（tag 分布）
+match_element()           → 按条件筛选元素（摘要）
+get_element()             → 最后才看完整信息
+```
+
+每一步都返回精简数据，AI 按需逐步深入。
+
+## API 概览
+
+### Browse — 主入口
+
+```python
+browser.get(url)                  # 打开 URL
+browser.screenshot(path)          # 截图
+browser.save_state(path)          # 保存会话状态
+browser.load_state(path)          # 恢复会话状态
+browser.close()                   # 关闭浏览器
+```
+
+### TabManager — 标签页管理
+
+```python
+browser.tabs.new_tab(url)         # 新建标签页
+browser.tabs.close_tab(index)     # 关闭标签页
+browser.tabs.switch_to_tab(index) # 切换标签页
+browser.tabs.tabs_count()         # 获取标签页数量
+browser.tabs.current_index()     # 获取当前索引
+```
+
+### PageScanner — 页面扫描
+
+```python
+browser.view.get_regions()                    # 获取区块列表
+browser.view.get_region_summary(region_id)    # 获取区块统计
+browser.view.match_element(**filters)         # 筛选元素
+browser.view.get_element(ref)                # 获取完整元素
+browser.view.find_element(by, value)         # 精确定位
+```
+
+### ElementOperator — 元素操作
+
+```python
+browser.act.click(ref)              # 点击
+browser.act.input_by_ref(ref, text) # 输入
+browser.act.hover(ref)             # 悬停
+browser.act.double_click(ref)      # 双击
+browser.act.right_click(ref)       # 右键
+browser.act.submit(ref)            # 提交表单
+browser.act.clear(ref)             # 清空输入框
+browser.act.send_enter()            # 发送回车
+```
+
+## 数据类型
+
+| 类型 | 说明 |
+|------|------|
+| `Region` | 页面语义区块 `{id, label, node_count}` |
+| `Element` | 可交互元素 `{ref, tag, role, text, xpath, attrs}` |
+| `RegionSummary` | 区域统计 `{count, tag_counts, role_counts, text_preview}` |
+| `ElementPreview` | 元素摘要 `{ref, text, attrs_preview}` |
+| `OperationResult` | 操作结果 `{success, error?, new_url?}` |
+
+## 异常
+
+| 异常 | 说明 |
+|------|------|
+| `BrowserError` | 浏览器相关错误 |
+| `ElementNotFoundError` | 元素未找到 |
+| `RegionNotFoundError` | 区域未找到 |
+| `TabNotFoundError` | 标签页未找到 |
+| `OperationError` | 操作失败 |
+| `StateFileError` | 状态文件错误 |
+| `PageLoadError` | 页面加载失败 |
+
+## 技术栈
+
+- **底层引擎**: [DrissionPage](https://github.com/g18792951860/DrissionPage) — Python CDP 连接，无需驱动
+- **MCP 框架**: FastMCP（官方 Python MCP SDK）
+- **Python 版本**: >= 3.10
+
+## License
+
+MIT

rootbrowse-0.2.0/PROJECT.md

@@ -0,0 +1,313 @@
+# RootBrowse
+
+## 项目定位
+
+Python 浏览器自动化 MCP 框架，为 AI Agent 提供结构化的浏览器交互能力。基于 DrissionPage 构建。
+
+## 解决什么问题
+
+| 问题 | 现状 | RootBrowse |
+|------|------|------------|
+| DOM 超限 | 复杂页面直接报错 | 区域化拆分 + 截图兜底 |
+| 点击不精确 | 文字匹配模糊，点击错位置 | ref 引用精确点击 |
+| 信息噪音大 | 原始 DOM 转储，AI 无法处理 | 可交互元素树（无噪音） |
+| 搜索场景弱 | 返回单节点 | 结构化搜索结果列表 |
+| 状态管理 | 每次重新登录 | save/load state |
+
+**本质：让 AI Agent 能稳定、准确地操作浏览器。**
+
+---
+
+## 核心概念
+
+### ref（内部引用 ID）
+
+HTML 元素大多数没有 `id` 属性。RootBrowse 为每个可交互元素生成 `ref`（r1, r2, r3...），作为内部引用。
+
+```python
+# 原始 HTML: <a href="/python">Python 入门</a>
+# 生成 ref 后
+Element(ref="r1", tag="a", text="Python 入门", xpath="...", attrs={...})
+```
+
+AI 用 `ref` 操作元素，不依赖原始 HTML 的 id 或文字匹配。
+
+### 区域化拆分
+
+页面 DOM 有几千个节点，直接给 AI 无法处理。RootBrowse 按语义区块拆分：
+
+```
+页面 DOM
+    ↓ 按语义区域分组（header, main, sidebar 等）
+    ↓ 过滤噪音（script, style, meta）
+    ↓ 统计每个区域的节点数
+返回：Region 列表，AI 选择进入哪个区域
+```
+
+### 渐进式获取
+
+```
+get_regions()           → 看有哪些区块
+get_region_summary()     → 看区块统计（tag 分布）
+match_element()           → 按条件筛选元素（摘要）
+get_element()             → 最后才看完整信息
+```
+
+每一步都返回精简数据，AI 按需逐步深入。
+
+### TabManager 状态自管理
+
+TabManager **不依赖 DrissionPage API 查询标签页列表**，自身维护状态：
+
+- `_tabs` — 所有标签页信息 `[{url, title}, ...]`
+- `_current_index` — 当前标签页索引
+
+每次调用 DrissionPage 方法后，同步更新内部状态。
+
+---
+
+## AI 工作流
+
+### 核心流程
+
+```
+用户指令 → get_regions() → get_region_summary() → match_element() → get_element() → ElementOperator 操作
+```
+
+### 具体例子
+
+**场景：在新闻网站搜索"Python"文章**
+
+```
+1. get_regions()
+   → [Region(id="header", node_count=15), Region(id="main", node_count=347), ...]
+
+2. get_region_summary("main")
+   → {count: 347, tag_counts: {a: 280, button: 23, input: 12}, role_counts: {link: 280, button: 23}}
+
+3. match_element("main", tag="a", text_contains="Python", limit=20)
+   → [{ref: "r5", text: "Python 入门", attrs_preview: {href: "/python"}}, ...]
+
+4. get_element("r5")
+   → Element(ref="r5", tag="a", role="link", text="Python 入门", xpath="...", attrs={...})
+
+5. ElementOperator.click("r5")
+   → {success: true, new_url: "...", error: null}
+```
+
+**场景：截图兜底**
+
+```
+操作后页面崩溃 / DOM 超限
+    ↓
+screenshot(annotate=[[x1,y1,x2,y2]])
+    ↓
+返回 base64 图片，高亮标注指定区域
+AI 从截图看页面状态，不依赖 DOM
+```
+
+---
+
+## 类结构
+
+### TabManager — 标签页管理器
+
+**职责**：管理浏览器标签页（新增、切换、关闭）
+
+**内部状态**：
+
+```python
+_page         # DrissionPage 底层实例
+_tabs         # [{url, title}, ...] 所有标签页信息
+_current_index  # 当前标签页索引
+```
+
+**方法**：
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `new_tab` | `url: str` | `int` | 打开新标签页，返回索引 |
+| `close_tab` | — | `None` | 关闭当前标签页 |
+| `switch_to_tab` | `index: int` | `None` | 切换到指定标签页 |
+| `tabs_count` | — | `int` | 返回标签页数量 |
+| `current_index` | — | `int` | 返回当前标签页索引 |
+
+---
+
+### ElementOperator — 元素操作器
+
+**职责**：对元素执行点击、输入、悬停等操作
+
+**内部状态**：
+
+```python
+_element_map  # ref -> Element 映射表
+```
+
+**方法**：
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `click` | `ref: str` | `dict` | 通过 ref 精确点击 |
+| `input_by_ref` | `ref: str, text: str, clear: bool = False` | `dict` | 向输入框写入文字 |
+| `hover` | `ref: str` | `dict` | 悬停 |
+| `double_click` | `ref: str` | `dict` | 双击 |
+| `right_click` | `ref: str` | `dict` | 右键 |
+| `submit` | `ref: str` | `dict` | 提交表单 |
+| `clear` | `ref: str` | `dict` | 清空输入框 |
+| `send_enter` | — | `None` | 发送回车键 |
+
+**返回值格式**：`{success, new_url?, error?}`
+
+---
+
+### PageScanner — 页面扫描器
+
+**职责**：获取页面结构化信息（区块、元素摘要、完整元素）
+
+**内部状态**：
+
+```python
+_page         # DrissionPage 底层实例
+_element_map  # ref -> Element 映射表
+```
+
+**方法**：
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `get_regions` | — | `list[Region]` | 返回页面语义区块列表 |
+| `get_region_summary` | `region_id: str` | `dict` | 返回区域统计摘要 |
+| `match_element` | 见下表 | `list[dict]` | 按条件筛选元素摘要 |
+| `get_element` | `ref: str` | `Element` | 返回完整元素信息 |
+| `find_element` | `by, value, filter` | `Element \| None` | 多维度精确定位 |
+
+**match_element 参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `region_id` | `str \| list[str] \| None` | 搜索区域，可单选/多选/全选 |
+| `query` | `str \| None` | 关键词搜索 |
+| `tag` | `str \| None` | HTML 标签筛选 |
+| `role` | `str \| None` | ARIA role 筛选 |
+| `text_contains` | `str \| None` | 文字包含筛选 |
+| `limit` | `int = 20` | 最多返回数量 |
+| `offset` | `int = 0` | 分页偏移 |
+
+**返回值"元素摘要"结构**：
+```python
+{"ref": "r1", "text": "文章标题", "attrs_preview": {"href": "/article/1"}}
+```
+
+**get_region_summary 返回值结构**：
+```python
+{
+    "count": 347,
+    "tag_counts": {"a": 280, "button": 23, "input": 12},
+    "role_counts": {"link": 280, "button": 23},
+    "text_preview": [{"tag": "a", "text": "标题1", "ref": "r1"}, ...]
+}
+```
+
+---
+
+### Browse — 主入口
+
+**职责**：组合 TabManager、ElementOperator、PageScanner，提供统一入口
+
+**方法**：
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `get` | `url: str` | `dict` | 打开 URL，返回 {url, title} |
+| `screenshot` | `path, annotate` | `str` | 截图，可高亮标注区域 |
+| `save_state` | `path: str` | `None` | 保存 cookies + localStorage |
+| `load_state` | `path: str` | `None` | 恢复会话状态 |
+
+**AI 调用方式**：
+
+```python
+browser.tabs.new_tab('https://example.com')  # TabManager
+browser.page.get_regions()                    # PageScanner
+browser.act.click('r1')                       # ElementOperator
+```
+
+---
+
+## 数据类型
+
+### Region（页面区块）
+
+```python
+Region(
+    id="main",           # 区块 ID
+    label="主内容",       # 人类可读名称
+    node_count=347        # 可交互元素数量
+)
+```
+
+### Element（可交互元素）
+
+```python
+Element(
+    ref="r1",            # 内部引用 ID
+    tag="a",             # HTML 标签
+    role="link",         # ARIA role
+    text="文章标题",     # 显示文字
+    xpath="/html/body/div[2]/a",  # 元素路径
+    attrs={"href": "/article/1", "target": "_blank"}
+)
+```
+
+### 返回值 dict
+
+| 方法 | 返回结构 |
+|------|---------|
+| `get` | `{url, title}` |
+| `screenshot` | 文件路径或 base64 字符串 |
+| `click` | `{success, new_url, error}` |
+| `input_by_ref` | `{success, error}` |
+| `get_region_summary` | `{count, tag_counts, role_counts, text_preview}` |
+| `match_element` | `[{ref, text, attrs_preview}, ...]` |
+
+---
+
+## 目录结构
+
+```
+src/RootBrowse/src/rootbrowse/
+├── __init__.py          # 包导出
+├── _version.py          # 版本信息
+├── browser.py           # Browse 主类
+├── tab_manager.py       # TabManager 类
+├── element_operator.py  # ElementOperator 类
+├── page_scanner.py      # PageScanner 类
+├── types.py             # Region, Element 数据类
+├── constants.py         # 可交互标签列表等常量
+└── exceptions.py        # 自定义异常
+```
+
+---
+
+## 技术选型
+
+- **底层引擎**: DrissionPage（Python CDP 连接，无需驱动）
+- **MCP 框架**: FastMCP（官方 Python MCP SDK）
+- **Python 版本**: >= 3.10
+
+---
+
+## 开发状态
+
+**当前阶段：实现完成**
+
+- [x] project_tree.json — 类结构定义（JSON Schema）
+- [x] types.py — Region, Element 数据类
+- [x] constants.py — 可交互标签列表
+- [x] exceptions.py — 自定义异常
+- [x] tab_manager.py — TabManager 实现
+- [x] element_operator.py — ElementOperator 实现
+- [x] page_scanner.py — PageScanner 实现
+- [x] browser.py — Browse 主类实现
+- [x] _version.py — 版本信息
+- [x] __init__.py — 包导出