# Browser-Use 底层工具方法文档

本文档整理了 browser-use 项目的所有底层工具方法，方便你在自己的 Agent 中集成使用。

## 目录

1. [浏览器会话管理 (BrowserSession)](#1-浏览器会话管理-browsersession)
2. [页面操作工具 (Tools)](#2-页面操作工具-tools)
3. [DOM 服务 (DomService)](#3-dom-服务-domservice)
4. [页面交互 (Page)](#4-页面交互-page)
5. [鼠标操作 (Mouse)](#5-鼠标操作-mouse)
6. [元素操作 (Element)](#6-元素操作-element)

---

## 1. 浏览器会话管理 (BrowserSession)

**文件位置**: `browser_use/browser/session.py`

### 核心方法

#### `async start() -> None`
**功能**: 启动浏览器会话
- 自动检测是本地浏览器还是云浏览器
- 建立 CDP (Chrome DevTools Protocol) 连接
- 初始化所有 watchdog 服务
- **使用场景**: 在使用任何浏览器功能前必须调用

```python
browser_session = BrowserSession(headless=False)
await browser_session.start()
```

#### `async stop() -> None`
**功能**: 优雅停止浏览器会话
- 保存存储状态 (cookies, localStorage 等)
- 清理事件总线和缓存
- 保持浏览器进程运行
- **使用场景**: 临时暂停会话但不关闭浏览器

#### `async kill() -> None`
**功能**: 强制终止浏览器会话
- 保存存储状态
- 关闭浏览器进程
- 清理所有资源
- **使用场景**: 完全结束浏览器使用

#### `async reset() -> None`
**功能**: 重置会话状态
- 清除所有 CDP 会话缓存
- 清除 DOM 缓存和选择器映射
- 重置焦点目标
- **使用场景**: 需要清理状态但保持连接时

#### `async get_or_create_cdp_session(target_id: str, focus: bool = True) -> CDPSession`
**功能**: 获取或创建 CDP 会话
- **参数**:
  - `target_id`: 目标页面/标签的 ID
  - `focus`: 是否将焦点切换到该目标
- **返回**: CDP 会话对象，用于发送 CDP 命令
- **使用场景**: 需要直接使用 CDP 协议操作浏览器时

#### `async get_current_page_url() -> str`
**功能**: 获取当前页面 URL
- 返回当前焦点标签页的 URL
- **使用场景**: 需要知道当前浏览位置

#### `async get_selector_map() -> dict[int, EnhancedDOMTreeNode]`
**功能**: 获取页面元素索引映射
- 返回页面所有可交互元素的索引字典
- 键是元素索引，值是增强的 DOM 节点对象
- **使用场景**: 需要通过索引访问页面元素时

#### `async get_element_by_index(index: int) -> EnhancedDOMTreeNode | None`
**功能**: 通过索引获取页面元素
- **参数**: `index` - 元素索引号
- **返回**: 增强的 DOM 节点对象或 None
- **使用场景**: 根据 LLM 返回的索引定位元素

---

## 2. 页面操作工具 (Tools)

**文件位置**: `browser_use/tools/service.py`

这是最核心的工具类，包含了所有高级浏览器操作方法。

### 2.1 导航类方法

#### `async search(query: str, engine: str = 'google') -> ActionResult`
**功能**: 使用搜索引擎搜索
- **参数**:
  - `query`: 搜索关键词
  - `engine`: 搜索引擎 ('google', 'duckduckgo', 'bing')
- **返回**: 操作结果，包含搜索状态
- **实现位置**: `browser_use/tools/service.py:126`

```python
result = await tools.search(
    query="Python async programming",
    engine="google",
    browser_session=browser_session
)
```

#### `async navigate(url: str, new_tab: bool = False) -> ActionResult`
**功能**: 导航到指定 URL
- **参数**:
  - `url`: 目标 URL
  - `new_tab`: 是否在新标签页打开
- **返回**: 导航结果
- **实现位置**: `browser_use/tools/service.py:169`

```python
result = await tools.navigate(
    url="https://example.com",
    new_tab=True,
    browser_session=browser_session
)
```

#### `async go_back() -> ActionResult`
**功能**: 返回上一页
- 相当于浏览器的后退按钮
- **实现位置**: `browser_use/tools/service.py:213`

#### `async wait(seconds: int = 3) -> ActionResult`
**功能**: 等待指定秒数
- **参数**: `seconds` - 等待时间（最大 30 秒）
- **使用场景**: 等待页面加载或动画完成
- **实现位置**: `browser_use/tools/service.py:227`

### 2.2 元素交互方法

#### `async click(index: int, coordinate_x: int = None, coordinate_y: int = None) -> ActionResult`
**功能**: 点击页面元素
- **参数**:
  - `index`: 元素索引（优先使用）
  - `coordinate_x`, `coordinate_y`: 坐标点击（备选）
- **返回**: 点击结果，包含点击坐标元数据
- **实现位置**: `browser_use/tools/service.py:299` (索引), `browser_use/tools/service.py:258` (坐标)

```python
# 通过索引点击
result = await tools.click(
    index=5,
    browser_session=browser_session
)

# 通过坐标点击（需要启用坐标点击功能）
result = await tools.click(
    coordinate_x=100,
    coordinate_y=200,
    browser_session=browser_session
)
```

#### `async input(index: int, text: str, clear: bool = True) -> ActionResult`
**功能**: 在输入框中输入文本
- **参数**:
  - `index`: 输入框元素索引
  - `text`: 要输入的文本
  - `clear`: 是否先清空输入框
- **返回**: 输入结果
- **实现位置**: `browser_use/tools/service.py:369`
- **特性**: 支持敏感数据检测和脱敏

```python
result = await tools.input(
    index=3,
    text="user@example.com",
    clear=True,
    browser_session=browser_session
)
```

#### `async upload_file(index: int, path: str) -> ActionResult`
**功能**: 上传文件到文件输入框
- **参数**:
  - `index`: 文件输入框索引
  - `path`: 文件路径
- **返回**: 上传结果
- **实现位置**: `browser_use/tools/service.py:438`
- **特性**: 自动查找最近的文件输入元素

```python
result = await tools.upload_file(
    index=7,
    path="/path/to/file.pdf",
    browser_session=browser_session,
    available_file_paths=["/path/to/file.pdf"],
    file_system=file_system
)
```

### 2.3 滚动和视图方法

#### `async scroll(down: bool = True, pages: float = 1.0, index: int = None) -> ActionResult`
**功能**: 滚动页面或元素
- **参数**:
  - `down`: True 向下滚动，False 向上滚动
  - `pages`: 滚动页数（0.5-10.0）
  - `index`: 可选，滚动特定元素（如下拉框）
- **返回**: 滚动结果
- **实现位置**: `browser_use/tools/service.py:789`
- **特性**: 自动检测视口高度，支持多页连续滚动

```python
# 向下滚动 2 页
result = await tools.scroll(
    down=True,
    pages=2.0,
    browser_session=browser_session
)

# 滚动特定元素
result = await tools.scroll(
    down=True,
    pages=1.0,
    index=10,
    browser_session=browser_session
)
```

#### `async find_text(text: str) -> ActionResult`
**功能**: 查找并滚动到文本位置
- **参数**: `text` - 要查找的文本
- **返回**: 查找结果
- **实现位置**: `browser_use/tools/service.py:910`

#### `async screenshot() -> ActionResult`
**功能**: 请求在下次观察中包含截图
- **返回**: 包含截图请求标志的结果
- **实现位置**: `browser_use/tools/service.py:934`
- **使用场景**: 需要视觉检查页面状态时

### 2.4 标签页管理方法

#### `async switch(tab_id: str) -> ActionResult`
**功能**: 切换到指定标签页
- **参数**: `tab_id` - 标签页 ID（target_id 的最后 4 位）
- **返回**: 切换结果
- **实现位置**: `browser_use/tools/service.py:605`

```python
result = await tools.switch(
    tab_id="a3f2",
    browser_session=browser_session
)
```

#### `async close(tab_id: str) -> ActionResult`
**功能**: 关闭指定标签页
- **参数**: `tab_id` - 标签页 ID
- **返回**: 关闭结果
- **实现位置**: `browser_use/tools/service.py:630`

### 2.5 下拉框操作方法

#### `async dropdown_options(index: int) -> ActionResult`
**功能**: 获取下拉框的所有选项
- **参数**: `index` - 下拉框元素索引
- **返回**: 包含所有选项的结果
- **实现位置**: `browser_use/tools/service.py:952`

```python
result = await tools.dropdown_options(
    index=8,
    browser_session=browser_session
)
```

#### `async select_dropdown(index: int, text: str) -> ActionResult`
**功能**: 选择下拉框选项
- **参数**:
  - `index`: 下拉框索引
  - `text`: 要选择的选项文本
- **返回**: 选择结果
- **实现位置**: `browser_use/tools/service.py:980`

### 2.6 数据提取方法

#### `async extract(query: str, extract_links: bool = False, start_from_char: int = 0) -> ActionResult`
**功能**: 使用 LLM 从页面提取结构化数据
- **参数**:
  - `query`: 提取查询（告诉 LLM 要提取什么）
  - `extract_links`: 是否提取链接
  - `start_from_char`: 从哪个字符开始（用于分页提取）
- **返回**: 提取的内容
- **实现位置**: `browser_use/tools/service.py:659`
- **特性**:
  - 自动将 HTML 转换为 Markdown
  - 过滤噪音内容
  - 支持大内容分页提取（最大 100k 字符）

```python
result = await tools.extract(
    query="提取页面上所有产品的名称和价格",
    extract_links=True,
    browser_session=browser_session,
    page_extraction_llm=llm,
    file_system=file_system
)
```

### 2.7 JavaScript 执行方法

#### `async evaluate(code: str) -> ActionResult`
**功能**: 在页面中执行 JavaScript 代码
- **参数**: `code` - JavaScript 代码字符串
- **返回**: 执行结果
- **实现位置**: `browser_use/tools/service.py:1098`
- **特性**:
  - 自动修复常见 JavaScript 语法问题
  - 支持 Promise
  - 限制输出大小（20k 字符）
  - 自动提取图片数据

```python
result = await tools.evaluate(
    code="""
    (function(){
        try {
            const title = document.querySelector('h1');
            return title ? title.textContent : 'not found';
        } catch(e) {
            return 'Error: ' + e.message;
        }
    })()
    """,
    browser_session=browser_session
)
```

### 2.8 键盘操作方法

#### `async send_keys(keys: list[str]) -> ActionResult`
**功能**: 发送键盘按键序列
- **参数**: `keys` - 按键列表（如 ['Control', 'a']）
- **返回**: 操作结果
- **实现位置**: `browser_use/tools/service.py:894`

```python
result = await tools.send_keys(
    keys=['Control', 'a'],
    browser_session=browser_session
)
```

### 2.9 文件系统方法

#### `async write_file(file_name: str, content: str, append: bool = False) -> ActionResult`
**功能**: 写入文件到本地文件系统
- **参数**:
  - `file_name`: 文件名
  - `content`: 文件内容
  - `append`: 是否追加模式
- **返回**: 写入结果
- **实现位置**: `browser_use/tools/service.py:1026`
- **支持格式**: .txt, .md, .json, .jsonl, .csv, .pdf

```python
result = await tools.write_file(
    file_name="output.txt",
    content="Hello World",
    append=False,
    file_system=file_system
)
```

#### `async read_file(file_name: str) -> ActionResult`
**功能**: 读取文件内容
- **参数**: `file_name` - 文件名
- **返回**: 文件内容
- **实现位置**: `browser_use/tools/service.py:1060`
- **支持格式**: 文本文件、PDF、DOCX、图片

#### `async replace_file(file_name: str, old_str: str, new_str: str) -> ActionResult`
**功能**: 替换文件中的特定文本
- **参数**:
  - `file_name`: 文件名
  - `old_str`: 要替换的文本
  - `new_str`: 新文本
- **返回**: 替换结果
- **实现位置**: `browser_use/tools/service.py:1052`

### 2.10 任务完成方法

#### `async done(text: str, success: bool = True, files_to_display: list[str] = None) -> ActionResult`
**功能**: 标记任务完成
- **参数**:
  - `text`: 完成消息
  - `success`: 是否成功
  - `files_to_display`: 要显示的文件列表
- **返回**: 包含 `is_done=True` 的结果
- **实现位置**: `browser_use/tools/service.py:1295`

---

## 3. DOM 服务 (DomService)

**文件位置**: `browser_use/dom/service.py`

### 核心方法

#### `async get_all_trees(target_id: str) -> TargetAllTrees`
**功能**: 获取页面的所有 DOM 树
- **参数**: `target_id` - 目标页面 ID
- **返回**: 包含 DOM 树、可访问性树和快照的完整数据
- **实现位置**: `browser_use/dom/service.py:248`
- **特性**:
  - 合并主框架和所有 iframe 的 DOM
  - 包含元素位置、样式、可见性信息
  - 支持跨域 iframe（可配置）

#### `is_element_visible_according_to_all_parents(node: EnhancedDOMTreeNode, html_frames: list) -> bool`
**功能**: 检查元素在所有父框架中是否可见
- **参数**:
  - `node`: DOM 节点
  - `html_frames`: HTML 框架列表
- **返回**: 是否可见
- **实现位置**: `browser_use/dom/service.py:125`
- **检查项**:
  - CSS display/visibility/opacity
  - 元素边界框
  - iframe 视口交集
  - 滚动位置

---

## 4. 页面交互 (Page)

**文件位置**: `browser_use/actor/page.py`

Page 类提供了对单个页面/标签的直接操作接口。

### 核心方法

#### `async evaluate(page_function: str, *args) -> str`
**功能**: 在页面中执行 JavaScript 函数
- **参数**:
  - `page_function`: 必须是箭头函数格式 `(...args) => {...}`
  - `*args`: 传递给函数的参数
- **返回**: 执行结果的字符串表示
- **实现位置**: `browser_use/actor/page.py:103`

```python
page = Page(browser_session, target_id)
result = await page.evaluate(
    "() => document.title"
)
```

#### `async screenshot(format: str = 'png', quality: int = None) -> str`
**功能**: 截取页面截图
- **参数**:
  - `format`: 图片格式 ('png', 'jpeg', 'webp')
  - `quality`: JPEG 质量 (0-100)
- **返回**: Base64 编码的图片数据
- **实现位置**: `browser_use/actor/page.py:192`

#### `async press(key: str) -> None`
**功能**: 按下键盘按键
- **参数**: `key` - 按键名称或组合键（如 "Enter", "Control+A"）
- **实现位置**: `browser_use/actor/page.py:213`
- **支持**: 单键和组合键（用 + 连接）

```python
await page.press("Enter")
await page.press("Control+A")
```

#### `async reload() -> None`
**功能**: 重新加载页面
- **实现位置**: `browser_use/actor/page.py:90`

#### `async set_viewport_size(width: int, height: int) -> None`
**功能**: 设置视口大小
- **参数**:
  - `width`: 宽度（像素）
  - `height`: 高度（像素）
- **实现位置**: `browser_use/actor/page.py:279`

#### `async get_element(backend_node_id: int) -> Element`
**功能**: 通过后端节点 ID 获取元素对象
- **参数**: `backend_node_id` - 元素的后端节点 ID
- **返回**: Element 对象
- **实现位置**: `browser_use/actor/page.py:95`

#### `@property async mouse -> Mouse`
**功能**: 获取鼠标操作接口
- **返回**: Mouse 对象
- **实现位置**: `browser_use/actor/page.py:81`

---

## 5. 鼠标操作 (Mouse)

**文件位置**: `browser_use/actor/mouse.py`

### 核心方法

#### `async click(x: int, y: int, button: str = 'left', click_count: int = 1) -> None`
**功能**: 在指定坐标点击
- **参数**:
  - `x`, `y`: 坐标位置
  - `button`: 鼠标按钮 ('left', 'right', 'middle')
  - `click_count`: 点击次数（双击用 2）
- **实现位置**: `browser_use/actor/mouse.py:21`

```python
mouse = await page.mouse
await mouse.click(100, 200, button='left', click_count=1)
```

#### `async move(x: int, y: int, steps: int = 1) -> None`
**功能**: 移动鼠标到指定坐标
- **参数**:
  - `x`, `y`: 目标坐标
  - `steps`: 移动步数（预留参数）
- **实现位置**: `browser_use/actor/mouse.py:77`

#### `async down(button: str = 'left', click_count: int = 1) -> None`
**功能**: 按下鼠标按钮
- **参数**:
  - `button`: 鼠标按钮
  - `click_count`: 点击计数
- **实现位置**: `browser_use/actor/mouse.py:49`

#### `async up(button: str = 'left', click_count: int = 1) -> None`
**功能**: 释放鼠标按钮
- **参数**: 同 `down()`
- **实现位置**: `browser_use/actor/mouse.py:63`

#### `async scroll(x: int = 0, y: int = 0, delta_x: int = None, delta_y: int = None) -> None`
**功能**: 滚动页面
- **参数**:
  - `x`, `y`: 滚动起始坐标（默认视口中心）
  - `delta_x`, `delta_y`: 滚动距离（正数向下/右）
- **实现位置**: `browser_use/actor/mouse.py:85`
- **特性**: 三种滚动方法自动降级

```python
# 向下滚动 500 像素
await mouse.scroll(delta_y=500)
```

---

## 6. 元素操作 (Element)

**文件位置**: `browser_use/actor/element.py`

### 核心方法

#### `async click(button: str = 'left', click_count: int = 1, modifiers: list[str] = None) -> None`
**功能**: 点击元素
- **参数**:
  - `button`: 鼠标按钮
  - `click_count`: 点击次数
  - `modifiers`: 修饰键列表 (['Alt', 'Control', 'Meta', 'Shift'])
- **实现位置**: `browser_use/actor/element.py:93`
- **特性**:
  - 自动获取元素几何信息
  - 多种方法降级（getContentQuads → getBoxModel → getBoundingClientRect）
  - 自动滚动到可见区域
  - 检查元素可见性

```python
element = await page.get_element(backend_node_id)
await element.click(button='left', click_count=1)
```

---

## 使用示例

### 完整的浏览器自动化流程

```python
from browser_use import BrowserSession
from browser_use.tools.service import Tools
from browser_use.llm.base import BaseChatModel

# 1. 初始化浏览器会话
browser_session = BrowserSession(
    headless=False,
    user_data_dir="./profile"
)

# 2. 启动浏览器
await browser_session.start()

# 3. 初始化工具
tools = Tools()

# 4. 导航到网页
await tools.navigate(
    url="https://example.com",
    browser_session=browser_session
)

# 5. 等待页面加载
await tools.wait(seconds=2)

# 6. 获取页面元素
selector_map = await browser_session.get_selector_map()

# 7. 点击元素
await tools.click(
    index=5,
    browser_session=browser_session
)

# 8. 输入文本
await tools.input(
    index=3,
    text="search query",
    browser_session=browser_session
)

# 9. 滚动页面
await tools.scroll(
    down=True,
    pages=2.0,
    browser_session=browser_session
)

# 10. 提取数据
result = await tools.extract(
    query="提取所有产品信息",
    browser_session=browser_session,
    page_extraction_llm=your_llm
)

# 11. 清理
await browser_session.stop()
```

### 在你的 Agent 中集成

```python
class MyAgent:
    def __init__(self):
        self.browser_session = BrowserSession(headless=False)
        self.tools = Tools()

    async def start(self):
        await self.browser_session.start()

    async def navigate_and_extract(self, url: str, query: str):
        # 导航
        await self.tools.navigate(
            url=url,
            browser_session=self.browser_session
        )

        # 等待加载
        await self.tools.wait(seconds=2)

        # 提取数据
        result = await self.tools.extract(
            query=query,
            browser_session=self.browser_session,
            page_extraction_llm=self.llm
        )

        return result.extracted_content

    async def cleanup(self):
        await self.browser_session.stop()
```

---

## 关键概念

### ActionResult
所有工具方法返回的结果对象，包含：
- `extracted_content`: 提取的内容（短期记忆）
- `long_term_memory`: 长期记忆摘要
- `error`: 错误信息
- `is_done`: 是否完成任务
- `success`: 是否成功
- `metadata`: 元数据（如点击坐标）
- `attachments`: 附件文件路径列表

### EnhancedDOMTreeNode
增强的 DOM 节点对象，包含：
- `node_id`: 节点 ID
- `node_name`: 节点名称（如 'DIV', 'INPUT'）
- `node_type`: 节点类型
- `attributes`: 属性字典
- `absolute_position`: 绝对位置
- `snapshot_node`: 快照信息（样式、边界框等）
- `children_nodes`: 子节点列表
- `parent_node`: 父节点引用

### CDPSession
CDP 会话对象，用于发送 CDP 命令：
- `cdp_client`: CDP 客户端
- `target_id`: 目标 ID
- `session_id`: 会话 ID

---

## 注意事项

1. **异步操作**: 所有方法都是异步的，必须使用 `await`
2. **会话管理**: 使用前必须调用 `browser_session.start()`
3. **资源清理**: 使用完毕后调用 `stop()` 或 `kill()`
4. **错误处理**: 所有方法可能抛出异常，建议使用 try-except
5. **元素索引**: 元素索引可能因页面变化而失效，需要重新获取
6. **坐标点击**: 默认禁用，需要调用 `tools.set_coordinate_clicking(True)` 启用
7. **文件路径**: 上传文件时需要在 `available_file_paths` 中声明路径

---

## 扩展阅读

- CDP 协议文档: https://chromedevtools.github.io/devtools-protocol/
- Browser-Use 项目: https://github.com/browser-use/browser-use
- 事件驱动架构: 查看 `browser_use/browser/events.py`
- Watchdog 服务: 查看 `browser_use/browser/watchdog_base.py`

---

**文档版本**: 1.0
**最后更新**: 2026-01-28
**适用版本**: browser-use >= 0.1.0