Skip to main content

browser_action

browser_action 工具通过 Puppeteer 控制的浏览器实现网页自动化和交互。它允许 Roo 启动浏览器、导航到网站、点击元素、输入文本，并通过截图提供视觉反馈。

参数​

该工具接受以下参数：

  • action（必需）：要执行的操作：
    • launch：在指定 URL 启动新的浏览器会话
    • click：在特定 x,y 坐标处点击
    • type：通过键盘输入文本
    • scroll_down：向下滚动一个页面高度
    • scroll_up：向上滚动一个页面高度
    • close：结束浏览器会话
  • url（可选）：使用 launch 操作时要导航到的 URL
  • coordinate（可选）：click 操作的 x,y 坐标（例如："450,300"）
  • text（可选）：使用 type 操作时要输入的文本

功能说明​

该工具创建一个 Roo 可以控制的自动化浏览器会话，用于导航网站、与元素交互以及执行需要浏览器自动化的任务。每个操作都会提供当前状态的截图，从而实现流程的视觉验证。

使用场景​

  • 当 Roo 需要与 Web 应用程序或网站交互时
  • 当测试用户界面或 Web 功能时
  • 当捕获网页截图时
  • 当可视化演示 Web 工作流程时

主要特性​

  • 每次操作后提供带有截图的视觉反馈，并捕获控制台日志
  • 支持从启动到页面交互再到关闭的完整工作流程
  • 通过坐标、键盘输入和滚动实现精确交互
  • 通过智能页面加载检测保持一致的浏览器会话
  • 以两种模式运行：本地（隔离的 Puppeteer 实例）或远程（连接到现有 Chrome）
  • 通过自动会话清理和详细消息优雅地处理错误
  • 通过支持各种格式和质量设置优化视觉输出
  • 通过位置指示器和操作历史跟踪交互状态

浏览器模式​

该工具以两种不同的模式运行：

本地浏览器模式（默认）​

  • 通过 Puppeteer 下载和管理本地 Chromium 实例
  • 每次启动时创建全新的浏览器环境
  • 无法访问现有用户配置文件、Cookie 或扩展
  • 在沙盒环境中保持一致、可预测的行为
  • 会话结束时完全关闭浏览器

远程浏览器模式​

  • 连接到已启用远程调试的现有 Chrome/Chromium 实例
  • 可以访问现有浏览器状态、Cookie 和潜在的扩展
  • 重用现有浏览器进程，启动速度更快
  • 支持连接到 Docker 容器或远程机器中的浏览器
  • 会话结束时仅断开连接（不关闭）浏览器
  • 需要 Chrome 以远程调试端口打开运行（通常为端口 9222）

限制​

  • 浏览器处于活动状态时，只能使用 browser_action 工具
  • 浏览器坐标是相对于视口的，而不是相对于页面的
  • 点击操作必须针对视口内的可见元素
  • 使用其他工具之前必须显式关闭浏览器会话
  • 浏览器窗口具有可配置的维度（默认 900x600）
  • 无法直接与浏览器开发者工具交互
  • 浏览器会话是临时的，在 Roo 重启后不会持久化
  • 仅适用于 Chrome/Chromium 浏览器，不适用于 Firefox 或 Safari
  • 本地模式无法访问现有 Cookie；远程模式需要启用调试的 Chrome

工作原理​

当调用 browser_action 工具时，它遵循以下流程：

  1. 操作验证和浏览器管理：

    • 验证请求操作所需的参数
    • 对于 launch：初始化浏览器会话（本地 Puppeteer 实例或远程 Chrome）
    • 对于交互操作：使用现有的浏览器会话
    • 对于 close：适当地终止或断开与浏览器的连接

  2. 页面交互和稳定性：

    • 使用 waitTillHTMLStable 算法通过 DOM 稳定性检测确保页面完全加载
    • 以适当的时间执行请求的操作（导航、点击、输入、滚动）
    • 点击后监控网络活动，必要时等待导航

  3. 视觉反馈：

    • 使用 WebP 格式（PNG 回退）捕获优化截图
    • 记录浏览器控制台日志用于调试目的
    • 跟踪鼠标位置并维护分页的操作历史

  4. 会话管理：

    • 在多个操作之间维护浏览器状态
    • 处理错误并自动清理资源
    • 强制执行正确的工作流程顺序（启动 → 交互 → 关闭）

工作流程顺序​

浏览器交互必须遵循此特定顺序：

  1. 会话初始化：所有浏览器工作流程必须以 launch 操作开始
  2. 交互阶段：可以执行多个 click、type 和滚动操作
  3. 会话终止：所有浏览器工作流程必须以 close 操作结束
  4. 工具切换：关闭浏览器后，可以使用其他工具

使用示例场景​

  • 当创建 Web 表单提交流程时，Roo 启动浏览器，导航到表单，使用 type 操作填写字段，然后点击提交。
  • 当测试响应式网站时，Roo 导航到网站并使用滚动操作检查不同部分。
  • 当捕获 Web 应用程序的截图时，Roo 浏览不同页面并在每个步骤拍摄截图。
  • 当演示电子商务结账流程时，Roo 模拟从产品选择到付款确认的整个过程。

使用示例​

启动浏览器并导航到网站：

<browser_action>
<action>launch</action>
<url>https://example.com</url>
</browser_action>

在特定坐标处点击（例如按钮）：

<browser_action>
<action>click</action>
<coordinate>450,300</coordinate>
</browser_action>

在焦点输入字段中输入文本：

<browser_action>
<action>type</action>
<text>Hello, World!</text>
</browser_action>

向下滚动查看更多内容：

<browser_action>
<action>scroll_down</action>
</browser_action>

关闭浏览器会话：

<browser_action>
<action>close</action>
</browser_action>