简体中文

English
日本語

简体中文

English
日本語

browser_action ​

browser_action 工具基于 Puppeteer 管控的浏览器实现网页自动化与交互能力，支持 VJSP 启动浏览器、导航至目标网站、点击页面元素、输入文本、滚动页面，并通过截图提供可视化反馈。

参数说明 ​

本工具接收以下参数，参数约束与取值规则如下：

  • action（必选）：待执行的操作类型，取值范围为：
    • launch：启动新的浏览器会话并导航至指定URL
    • click：在页面指定的X、Y坐标位置执行点击操作
    • type：通过键盘执行文本输入操作
    • scroll_down：向下滚动一个页面高度
    • scroll_up：向上滚动一个页面高度
    • close：终止当前浏览器会话
  • url（可选）：使用launch操作时，指定浏览器导航的目标 URL
  • coordinate（可选）：使用click操作时，指定点击的 X、Y 坐标（示例格式："450,300"）
  • text（可选）：使用type操作时，指定待输入的文本内容

功能定位 ​

该工具创建由 VJSP 管控的自动化浏览器会话，实现网站导航、页面元素交互，以及所有需浏览器自动化支撑的任务执行。每一步操作均会生成当前页面状态截图，支持流程的可视化校验。

适用场景 ​

  • VJSP 需与 Web 应用或网站进行交互时
  • 开展用户界面（UI）或 Web 功能自动化测试时
  • 捕获网页截图进行留存或分析时
  • 以可视化方式演示 Web 业务流程时

核心特性 ​

  • 每步操作后生成截图并捕获控制台日志，提供可视化反馈与调试依据
  • 支持从浏览器启动、页面交互到会话关闭的全流程自动化
  • 支持基于坐标的精准交互、键盘输入及页面滚动操作
  • 内置智能页面加载检测机制，保障浏览器会话的一致性
  • 支持两种运行模式：本地模式（独立 Puppeteer 实例）、远程模式（连接已启动的 Chrome 浏览器）
  • 具备优雅的错误处理能力，实现会话自动清理并输出详细错误信息
  • 支持多种截图格式与画质配置，优化可视化输出效果
  • 通过位置标识与操作历史记录，实现交互状态的全链路追踪

浏览器运行模式 ​

本工具提供两种独立的运行模式，适配不同自动化场景需求：

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

  • 通过 Puppeteer 自动下载并管理本地 Chromium 实例
  • 每次启动操作均创建全新的浏览器运行环境
  • 无法访问本地现有用户配置、Cookie 及浏览器扩展程序
  • 沙箱化环境下实现行为的一致性与可预测性
  • 会话终止时自动完全关闭浏览器进程

远程浏览器模式 ​

  • 连接已开启远程调试功能的 Chrome/Chromium 浏览器实例
  • 可访问浏览器现有运行状态、Cookie 及已安装的扩展程序
  • 复用现有浏览器进程，实现启动速度的优化
  • 支持连接 Docker 容器内或远程服务器上的浏览器实例
  • 会话终止时仅断开连接，不关闭目标浏览器
  • 依赖已开启远程调试端口的 Chrome 浏览器（默认端口：9222）

功能限制 ​

  • 浏览器会话激活期间，仅可调用browser_action工具执行操作
  • 浏览器坐标为视口相对坐标，非页面绝对坐标
  • 点击操作仅支持定位到视口内的可见元素
  • 切换至其他工具前，需显式关闭当前浏览器会话
  • 浏览器窗口尺寸支持自定义配置（默认尺寸：900x600）
  • 不支持直接与浏览器开发者工具（DevTools）进行交互
  • 浏览器会话为临时状态，VJSP 重启后无法持久化
  • 仅兼容 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. 工具切换：浏览器会话关闭后，方可调用其他工具执行操作

典型应用示例 ​

  • 网页表单提交流程：VJSP 启动浏览器并导航至表单页面，通过type操作填充各字段，执行点击操作提交表单
  • 响应式网站测试：VJSP 导航至目标站点，通过滚动操作检查页面不同区域的适配效果
  • Web应用截图捕获：VJSP 导航至应用不同页面，在各节点执行截图操作完成留存
  • 电商结账流程演示：VJSP 模拟从商品选品到支付确认的全流程操作

调用示例 ​

启动浏览器并导航至指定网站：

<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>