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 需要与网页应用或网站交互时
  • 当测试用户界面或网页功能时
  • 当捕获网页截图时
  • 当需要可视化演示网页工作流程时

主要特性​

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

浏览器模式​

该工具支持两种不同的模式：

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

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

远程浏览器模式​

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

局限性​

  • 浏览器活动期间，只能使用 browser_action 工具
  • launch 操作必须提供 URL 参数
  • 浏览器坐标是视口相关的，不是页面相关的
  • 点击操作必须针对视口内可见的元素
  • 浏览器会话必须明确关闭后才能使用其他工具
  • 浏览器窗口具有可配置的尺寸（默认 900x600）
  • 无法直接与浏览器 DevTools 交互
  • 浏览器会话是临时的，Roo 重启后不会保留
  • 仅支持 Chrome/Chromium 浏览器，不支持 Firefox 或 Safari
  • 本地模式无法访问现有 Cookie；远程模式需要启用调试的 Chrome

工作原理​

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

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

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

  2. 页面交互和稳定性：

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

  3. 视觉反馈：

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

  4. 会话管理：

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

工作流程顺序​

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

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

使用示例​

创建网页表单提交流程时，Roo 启动浏览器，导航到表单，使用 type 操作填写字段，然后点击提交按钮。 测试响应式网站时，Roo 导航到网站并使用滚动操作查看不同部分。 捕获网页应用截图时，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>