Lzh on GitHub

browser_action

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

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 操作：适当地终止或断开与浏览器的连接。

页面交互与稳定性

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

视觉反馈

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

会话管理

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

工作流序列

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

  • 会话初始化：所有浏览器工作流必须以 launch 操作开始。
  • 交互阶段：可以执行多个 click、type 和 scroll 操作。
  • 会话终止：所有浏览器工作流必须以 close 操作结束。
  • 工具切换：关闭浏览器后，才能使用其他工具。

使用示例

  • 创建 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>