# browser-use CLI 工具能力测试报告

## 测试概述

**测试日期**: 2026-01-29
**测试目标**: 验证 browser-use CLI 工具对基本任务的支持程度
**对比对象**: browserUseTools.py 底层工具
**业务场景**: 电商产品搜索与比价流程 (CLI 实现)

## CLI 工具发现

通过 `browser-use --help` 命令，发现 browser-use 提供了完整的命令行工具，包含以下命令：

```bash
browser-use [-h] [--session SESSION] [--browser {chromium,real,remote}]
            [--headed] [--profile PROFILE] [--json] [--api-key API_KEY]
            {open,click,type,input,scroll,back,screenshot,state,switch,
             close-tab,keys,select,eval,extract,python,run,sessions,close,server}
```

## CLI 工具命令清单

### 1. 基础浏览器操作

| 命令 | 功能 | 说明 |
|------|------|------|
| `open` | 导航到 URL | 在当前会话中打开网页 |
| `back` | 返回上一页 | 浏览器后退操作 |
| `state` | 获取浏览器状态 | 返回 URL、标题、可交互元素列表 |
| `screenshot` | 截图 | 保存当前页面截图 |
| `close` | 关闭会话 | 关闭浏览器会话 |

### 2. 元素交互操作

| 命令 | 功能 | 说明 |
|------|------|------|
| `click` | 点击元素 | 通过索引点击元素 |
| `type` | 输入文本 | 在当前焦点元素输入文本 |
| `input` | 指定元素输入 | 在指定索引的元素输入文本 |
| `keys` | 发送按键 | 发送键盘按键（Enter, Tab, Escape 等） |
| `scroll` | 滚动页面 | 向上/向下滚动页面 |

### 3. 高级功能

| 命令 | 功能 | 说明 |
|------|------|------|
| `select` | 选择下拉选项 | 在下拉菜单中选择选项 |
| `eval` | 执行 JavaScript | 在页面上下文中执行 JS 代码 |
| `python` | 执行 Python | 执行 Python 代码访问浏览器对象 |
| `extract` | 提取数据 | 使用 LLM 提取页面数据（需要 API key） |
| `run` | 运行 Agent 任务 | 运行完整的 Agent 任务（需要 API key） |

### 4. 标签页管理

| 命令 | 功能 | 说明 |
|------|------|------|
| `switch` | 切换标签页 | 切换到指定索引的标签页 |
| `close-tab` | 关闭标签页 | 关闭指定标签页 |

### 5. 会话管理

| 命令 | 功能 | 说明 |
|------|------|------|
| `sessions` | 列出会话 | 显示所有活动的浏览器会话 |
| `server` | 服务器控制 | 启动/停止 browser-use 服务器 |

## CLI 工具 vs browserUseTools 对比分析

### 功能对比表

| 功能 | CLI 工具 | browserUseTools | 说明 |
|------|----------|-----------------|------|
| **导航 (navigate)** | ✓ open | ✓ navigate_to_url | CLI 不支持 new_tab 参数 |
| **点击 (click)** | ✓ click | ✓ click_element | CLI 只支持索引，Tools 支持坐标 |
| **输入 (input)** | ✓ type/input | ✓ input_text | 功能相同 |
| **滚动 (scroll)** | ✓ scroll | ✓ scroll_page | 功能相同 |
| **返回 (back)** | ✓ back | ✓ go_back | 功能相同 |
| **截图 (screenshot)** | ✓ screenshot | ✗ | CLI 独有 |
| **状态获取 (state)** | ✓ state | ✗ | CLI 独有，返回 DOM 状态 |
| **标签页切换 (switch)** | ✓ switch | ✓ switch_tab | CLI 完整实现，Tools 简化版 |
| **标签页关闭 (close-tab)** | ✓ close-tab | ✓ close_tab | CLI 完整实现，Tools 简化版 |
| **发送按键 (keys)** | ✓ keys | ✓ send_keys | 功能相同 |
| **下拉选择 (select)** | ✓ select | ✓ select_dropdown_option | CLI 只能选择，Tools 可获取选项 |
| **JavaScript 执行 (eval)** | ✓ eval | ✗ | CLI 独有 |
| **Python 执行 (python)** | ✓ python | ✗ | CLI 独有 |
| **数据提取 (extract)** | ✓ extract (需要 API) | ✓ extract_content | 实现方式不同 |
| **会话管理 (sessions)** | ✓ sessions | ✗ | CLI 独有 |
| **坐标点击** | ✗ | ✓ click_element | Tools 独有 |
| **文件上传** | ✗ | ✓ upload_file | Tools 独有 |
| **获取下拉选项** | ✗ | ✓ get_dropdown_options | Tools 独有 |
| **任务完成标记** | ✗ | ✓ done | Tools 独有（框架特有） |
| **网页搜索** | ✗ | ✓ search_web | Tools 独有 |

### 优势对比

#### CLI 工具的优势

1. **会话管理** ✓
   - 支持命名会话，可以在多个命令之间保持浏览器状态
   - 支持列出和管理多个会话
   - 不需要每次都启动新浏览器

2. **DOM 状态维护** ✓
   - `state` 命令可以获取当前页面的所有可交互元素
   - 自动维护元素索引映射
   - 支持通过索引操作元素

3. **代码执行能力** ✓
   - 支持执行 JavaScript 代码（`eval` 命令）
   - 支持执行 Python 代码（`python` 命令）
   - 可以直接访问浏览器对象

4. **截图功能** ✓
   - 内置截图命令
   - 支持保存到指定路径

5. **完整的标签页管理** ✓
   - 真实的标签页切换和关闭
   - 支持多标签页操作

#### browserUseTools 的优势

1. **坐标点击** ✓
   - 支持通过坐标点击元素
   - 不依赖 DOM 状态，更灵活

2. **文件上传** ✓
   - 支持文件上传功能
   - CLI 未暴露此功能

3. **获取下拉选项** ✓
   - 可以获取下拉菜单的所有选项
   - CLI 只能选择，不能获取

4. **框架集成** ✓
   - 与 Agent 框架深度集成
   - 支持 ToolResult 标准返回格式
   - 支持任务完成标记（done）

5. **网页搜索** ✓
   - 内置搜索引擎支持（Google, Bing, DuckDuckGo）
   - CLI 需要手动导航到搜索引擎

## CLI 工具能力分析

### 完全支持的功能（17 个命令）

✓ **open** - 导航到 URL
✓ **click** - 通过索引点击元素
✓ **type** - 输入文本
✓ **input** - 在指定元素输入文本
✓ **scroll** - 滚动页面
✓ **back** - 返回上一页
✓ **screenshot** - 截图
✓ **state** - 获取浏览器状态
✓ **switch** - 切换标签页
✓ **close-tab** - 关闭标签页
✓ **keys** - 发送键盘按键
✓ **select** - 选择下拉选项
✓ **eval** - 执行 JavaScript
✓ **python** - 执行 Python 代码
✓ **sessions** - 会话管理
✓ **close** - 关闭会话
✓ **server** - 服务器控制

### 需要 API key 的功能

⚠ **extract** - 使用 LLM 提取数据（需要 Browser-Use API key）
⚠ **run** - 运行 Agent 任务（需要 LLM API key）

### CLI 不支持但 browserUseTools 支持的功能

✗ 通过坐标点击（CLI 只支持索引点击）
✗ 文件上传（CLI 未暴露此功能）
✗ 获取下拉选项列表（CLI 只能选择，不能获取选项）
✗ 新标签页打开 URL（CLI open 命令不支持 new_tab 参数）
✗ 任务完成标记（done 工具是框架特有的）
✗ 网页搜索（CLI 需要手动导航）

## browserUseTools 需要改进的地方

基于 CLI 工具的设计，browserUseTools 需要在以下方面改进：

### 1. 浏览器会话管理 ⚠

**现状**: 每次调用都创建新的浏览器实例
**问题**: 无法在多个操作之间保持状态，资源浪费
**改进方案**:
```python
# 参考 CLI 的会话管理机制
class BrowserSession:
    _sessions = {}  # 全局会话池

    @classmethod
    def get_or_create(cls, session_id):
        if session_id not in cls._sessions:
            cls._sessions[session_id] = cls(session_id)
        return cls._sessions[session_id]
```

### 2. DOM 状态维护 ⚠

**现状**: 未实现 DOM 状态提取和维护
**问题**: 索引点击、输入等功能无法正常工作
**改进方案**:
```python
# 参考 CLI 的 state 命令
async def get_browser_state():
    """获取浏览器状态，包括 URL、标题、可交互元素"""
    elements = await page.query_selector_all("a, button, input, select, textarea")
    return {
        "url": page.url,
        "title": await page.title(),
        "elements": [{"index": i, "tag": elem.tag_name, ...} for i, elem in enumerate(elements)]
    }
```

### 3. 标签页管理 ⚠

**现状**: switch_tab 和 close_tab 是简化实现
**问题**: 未真正操作浏览器标签页
**改进方案**:
```python
# 维护标签页映射
class BrowserSession:
    def __init__(self):
        self.pages = []  # 所有标签页
        self.current_page_index = 0

    async def switch_tab(self, index):
        self.current_page_index = index
        return self.pages[index]
```

### 4. JavaScript/Python 执行能力 ⚠

**现状**: 未实现
**问题**: 无法执行自定义代码
**改进方案**:
```python
@tool()
async def eval_javascript(code: str, uid: str = "") -> ToolResult:
    """执行 JavaScript 代码"""
    result = await page.evaluate(code)
    return ToolResult(title="JavaScript executed", output=str(result))
```

### 5. 截图功能 ⚠

**现状**: 未实现
**问题**: 无法保存页面截图
**改进方案**:
```python
@tool()
async def take_screenshot(path: str, uid: str = "") -> ToolResult:
    """截取页面截图"""
    await page.screenshot(path=path)
    return ToolResult(title="Screenshot saved", output=f"Saved to {path}")
```

## 实施建议

### 方案 1: 混合使用（推荐 - 短期）

**适用场景**: 快速验证业务流程，时间紧迫

**实施方式**:
- 使用 CLI 工具处理常规操作（导航、点击、输入、滚动等）
- 使用 browserUseTools 处理特殊需求（坐标点击、文件上传、获取下拉选项）
- 通过 subprocess 调用 CLI 命令

**优点**:
- 快速实现，无需大量开发
- 充分利用两者优势
- 可以立即投入使用

**缺点**:
- 需要维护两套工具的集成
- 调试困难（CLI 命令输出解析）
- 性能可能不是最优

**示例代码**:
```python
import subprocess

def cli_navigate(url, session="default"):
    """使用 CLI 导航"""
    result = subprocess.run(
        f"browser-use --session {session} open {url}",
        shell=True, capture_output=True, text=True
    )
    return result.returncode == 0

def cli_click(index, session="default"):
    """使用 CLI 点击"""
    result = subprocess.run(
        f"browser-use --session {session} click {index}",
        shell=True, capture_output=True, text=True
    )
    return result.returncode == 0
```

### 方案 2: 改进 browserUseTools（推荐 - 中长期）

**适用场景**: 长期维护，需要统一接口

**实施方式**:
1. 参考 CLI 工具实现会话管理
2. 实现 DOM 状态维护机制
3. 添加 JavaScript/Python 执行能力
4. 添加截图功能
5. 完善标签页管理

**优点**:
- 统一工具接口，易于维护
- 性能更好（直接使用 Playwright API）
- 调试方便
- 可以添加更多自定义功能

**缺点**:
- 开发工作量大
- 需要时间投入

**实施步骤**:

**第 1 周**: 会话管理
```python
# 实现全局会话管理器
class BrowserSessionManager:
    _sessions = {}

    @classmethod
    async def get_session(cls, session_id="default"):
        if session_id not in cls._sessions:
            cls._sessions[session_id] = await cls._create_session()
        return cls._sessions[session_id]

    @classmethod
    async def _create_session(cls):
        p = await async_playwright().start()
        browser = await p.chromium.launch(headless=False)
        context = await browser.new_context()
        page = await context.new_page()
        return {"playwright": p, "browser": browser, "context": context, "page": page}
```

**第 2 周**: DOM 状态维护
```python
@tool()
async def get_browser_state(session_id: str = "default", uid: str = "") -> ToolResult:
    """获取浏览器状态"""
    session = await BrowserSessionManager.get_session(session_id)
    page = session["page"]

    # 提取可交互元素
    elements = await page.query_selector_all("a, button, input, select, textarea")
    element_list = []
    for i, elem in enumerate(elements):
        element_list.append({
            "index": i,
            "tag": await elem.evaluate("el => el.tagName"),
            "text": await elem.inner_text(),
            "selector": await elem.evaluate("el => el.id || el.className")
        })

    return ToolResult(
        title="Browser state",
        output=f"URL: {page.url}\nTitle: {await page.title()}",
        metadata={"elements": element_list}
    )
```

**第 3-4 周**: 添加高级功能
- JavaScript 执行
- Python 执行
- 截图功能
- 完善标签页管理

### 方案 3: 封装 CLI 工具

**适用场景**: 快速原型，不需要深度定制

**实施方式**:
- 将 CLI 命令封装为 Python 函数
- 保持与 browserUseTools 相同的接口
- 使用 subprocess 调用 CLI

**优点**:
- 快速实现，功能完整
- 利用 CLI 的所有功能

**缺点**:
- 依赖外部 CLI 工具
- 调试困难
- 性能可能不是最优

## 测试结论

### 核心发现

1. **CLI 工具功能完整性**
   - browser-use CLI 工具提供了 17+ 个命令
   - 覆盖了大部分浏览器自动化需求
   - 支持会话管理，可以在多个命令之间保持浏览器状态
   - 支持 JavaScript 和 Python 代码执行，扩展性强

2. **browserUseTools 的优势**
   - 提供了坐标点击功能（CLI 只支持索引点击）
   - 支持文件上传（CLI 未暴露）
   - 可以获取下拉选项列表（CLI 只能选择）
   - 集成了任务完成标记（框架特有）
   - 内置网页搜索功能

3. **browserUseTools 需要改进的地方**
   - 缺少会话管理机制（每次调用都创建新浏览器实例）
   - 缺少 DOM 状态维护（CLI 已实现）
   - 标签页管理是简化版（CLI 已完整实现）
   - 缺少 JavaScript/Python 执行能力（CLI 支持）
   - 缺少截图功能（CLI 支持）

### 最终建议

**短期（1-2 周）**:
- 采用方案 1（混合使用）
- 使用 CLI 工具处理常规操作
- 使用 browserUseTools 处理特殊需求
- 编写集成测试，确保两套工具协同工作

**中期（1-2 月）**:
- 采用方案 2（改进 browserUseTools）
- 重点实现会话管理和 DOM 状态维护
- 添加 JavaScript 执行能力
- 完善标签页管理

**长期（3-6 月）**:
- 优化性能，实现连接池和会话复用
- 添加更多高级功能（截图、PDF 生成、Cookie 管理等）
- 完善文档和示例
- 建立完整的测试套件

### 结论

browser-use CLI 工具功能强大且完整，已经实现了大部分浏览器自动化需求。browserUseTools 在某些特定功能上有优势，但需要学习 CLI 工具的设计，特别是会话管理和 DOM 状态维护机制。

**建议采用混合使用的方案**，在改进 browserUseTools 的同时，充分利用 CLI 工具的现有能力，快速实现业务需求。

## 附录：CLI 命令示例

### 基础操作示例

```bash
# 1. 打开网页
browser-use --session my-session --headed open https://www.example.com

# 2. 获取页面状态
browser-use --session my-session state

# 3. 点击元素（索引 5）
browser-use --session my-session click 5

# 4. 输入文本
browser-use --session my-session type "Hello World"

# 5. 发送回车键
browser-use --session my-session keys Enter

# 6. 滚动页面
browser-use --session my-session scroll down

# 7. 截图
browser-use --session my-session screenshot /tmp/screenshot.png

# 8. 执行 JavaScript
browser-use --session my-session eval "document.title"

# 9. 执行 Python
browser-use --session my-session python "print(browser.url)"

# 10. 列出所有会话
browser-use sessions

# 11. 关闭会话
browser-use --session my-session close
```

### 电商搜索流程示例

```bash
# 1. 打开淘宝
browser-use --session taobao --headed open https://www.taobao.com

# 2. 获取页面状态，找到搜索框索引
browser-use --session taobao state

# 3. 点击搜索框（假设索引为 3）
browser-use --session taobao click 3

# 4. 输入搜索关键词
browser-use --session taobao type "iPhone 15 Pro"

# 5. 发送回车键搜索
browser-use --session taobao keys Enter

# 6. 等待加载，获取搜索结果
browser-use --session taobao state

# 7. 点击第一个商品（假设索引为 10）
browser-use --session taobao click 10

# 8. 滚动查看详情
browser-use --session taobao scroll down

# 9. 截图保存
browser-use --session taobao screenshot /tmp/product.png

# 10. 关闭会话
browser-use --session taobao close
```

---

**报告生成时间**: 2026-01-29
**测试执行者**: Claude Code
**报告版本**: 1.0