browserwing

2026-03-28 新闻来源：网淘吧围观:10

电脑广告

手机广告

BrowserWing Executor API

概述

BrowserWing Executor 通过 HTTP API 提供全面的浏览器自动化能力。您可以控制浏览器导航、与页面元素交互、提取数据以及分析页面结构。

配置

API 基础 URL：BrowserWing Executor API 地址可通过环境变量配置。

环境变量： BROWSERWING_EXECUTOR_URL
默认值： http://127.0.0.1:8080
如何获取 URL：从环境变量读取$BROWSERWING_EXECUTOR_URL，如果未设置，则使用默认值http://127.0.0.1:8080

基础 URL 格式： ${BROWSERWING_EXECUTOR_URL}/api/v1/executor或http://127.0.0.1:8080/api/v1/executor（如果未设置环境变量）

身份验证：使用X-BrowserWing-Key: <api密钥>请求头，或在需要时使用Authorization: Bearer <令牌>认证方式。

重要提示：始终优先读取环境变量来构建API URL。在Shell命令中，请使用：${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}

核心功能

页面导航：导航至URL、前进/后退、重新加载
元素交互：点击、输入、选择、悬停在页面元素上
数据提取：从元素中提取文本、属性和值
无障碍分析：获取无障碍快照以理解页面结构
高级操作：截图、执行JavaScript、键盘输入
批量处理：按顺序执行多个操作

API端点

1. 发现可用命令

重要提示：请务必首先调用此端点以查看所有可用命令及其参数。

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help"

响应：返回包含参数、示例和用法指南的所有命令的完整列表。

查询特定命令：

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help?command=extract"

2. 获取可访问性快照

关键：导航后务必调用此端点，以了解页面结构并获取元素引用ID（RefIDs）。

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

响应示例：

{
  "success": true,
  "snapshot_text": "Clickable Elements:\n  @e1 Login (role: button)\n  @e2 Sign Up (role: link)\n\nInput Elements:\n  @e3 Email (role: textbox) [placeholder: your@email.com]\n  @e4 Password (role: textbox)"
}

使用场景：

了解页面上有哪些交互元素
获取元素引用ID（@e1, @e2 等）以进行精确识别
查看元素标签、角色和属性
可访问性树比原始DOM更清晰，更适合LLM处理
引用ID是稳定的参考标识，在页面变更时也能可靠工作

3. 常用操作

注意：以下所有示例均使用EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"从环境变量读取API地址，默认回退值为http://127.0.0.1:8080。

导航到URL

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

点击元素

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/click" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

标识符格式：

RefID（推荐）： @e1、@e2（来自快照）
CSS选择器： #button-id、.class-name
XPath： //button[@type='submit']
文本： 登录（文本内容）

输入文本

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/type" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "user@example.com"}'

提取数据

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/extract" \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".product-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

等待元素

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/wait" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".loading", "state": "hidden", "timeout": 10}'

批量操作

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/batch" \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {"type": "navigate", "params": {"url": "https://example.com"}, "stop_on_error": true},
      {"type": "click", "params": {"identifier": "@e1"}, "stop_on_error": true},
      {"type": "type", "params": {"identifier": "@e3", "text": "query"}, "stop_on_error": true}
    ]
  }'

指令

分步工作流程：

获取 API URL：首先，从环境变量读取 API 基础 URL$BROWSERWING_EXECUTOR_URL。如果未设置，则使用默认值http://127.0.0.1:8080。在 shell 命令中，使用：EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
发现命令：调用GET /help以查看所有可用的操作及其参数（如果不确定，请首先执行此操作）。
导航：使用POST /navigate来打开目标网页。
分析页面：调用GET /snapshot以了解页面结构并获取元素 RefID。
交互：使用元素 RefID（例如@e1,@e2) 或 CSS 选择器来：
- 点击元素：POST /click
- 输入文本：POST /type
- 选择选项：POST /select
- 等待元素：POST /wait
提取数据：使用POST /extract从页面获取信息。
呈现结果：格式化并向用户显示提取的数据。

完整示例

用户请求："在 example.com 上搜索 'laptop' 并获取前 5 个结果"

您的操作：

导航到搜索页面：

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/navigate' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/search"}'

获取页面结构以找到搜索输入框：

curl -X GET 'http://127.0.0.1:18085/api/v1/executor/snapshot'

响应显示：@e3 搜索（角色：文本框）[占位符：搜索...]

输入搜索查询：

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/type' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "laptop"}'

按回车键提交：

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/press-key' \
  -H 'Content-Type: application/json' \
  -d '{"key": "Enter"}'

等待结果加载：

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/wait' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".search-results", "state": "visible", "timeout": 10}'

提取搜索结果：

curl -X POST 'http://127.0.0.1:18085/api/v1/executor/extract' \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".result-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

呈现提取的数据：

Found 15 results for 'laptop':
1. Gaming Laptop - $1299 (https://...)
2. Business Laptop - $899 (https://...)
...

关键命令参考

元素交互

POST /click- 点击元素（支持：RefID@e1、CSS选择器、XPath、文本内容）
POST /type- 在输入框中输入文本（支持：RefID@e3、CSS选择器、XPath）
POST /select- 选择下拉选项
POST /hover- 悬停在元素上
POST /wait- 等待元素状态（可见、隐藏、启用）
POST /press-key- 按下键盘按键（Enter、Tab、Ctrl+S等）

数据提取

POST /extract- 从元素中提取数据（支持多元素、自定义字段）
POST /get-text- 获取元素文本内容
POST /get-value- 获取输入元素的值
GET /page-info- 获取页面URL和标题
GET /page-text- 获取所有页面文本
GET /page-content- 获取完整HTML

页面分析

GET /snapshot- 获取无障碍访问快照（⭐导航后务必调用）
GET /clickable-elements- 获取所有可点击元素
GET /input-elements- 获取所有输入元素

高级功能

POST /screenshot- 截取页面截图（base64编码）
POST /evaluate- 执行JavaScript代码
POST /batch- 按顺序执行多个操作
POST /scroll-to-bottom- 滚动到页面底部
POST /resize- 调整浏览器窗口大小
POST /tabs- 管理浏览器标签页（列表、新建、切换、关闭）
POST /fill-form- 智能填写多个表单字段

调试与监控

GET /console-messages- 获取浏览器控制台消息（日志、警告、错误）
GET /network-requests- 获取页面发起的网络请求
POST /handle-dialog- 配置JavaScript对话框（alert、confirm、prompt）处理方式
POST /file-upload- 向输入元素上传文件
POST /drag- 拖放元素
POST /close-page- 关闭当前页面/标签页

元素识别

您可以通过以下方式识别元素：

RefID（推荐）： @e1、@e2、@e3
- 最可靠的方法 - 在页面变更中保持稳定
- 从/snapshot端点获取RefIDs
- 快照后5分钟内有效
- 示例："identifier": "@e1"
- 采用多策略回退机制以确保鲁棒性
CSS选择器： #id、.class、button[type="submit"]
- 标准CSS选择器
- 示例："identifier": "#login-button"
XPath： //button[@id='login']、//a[contains(text(), 'Submit')]
- 用于复杂查询的XPath表达式
- 示例："identifier": "//button[@id='login']"
文本内容： 登录,注册,提交
- 搜索具有匹配文本的按钮和链接
- 示例："标识符": "登录"
ARIA 标签：带有aria-label属性的
- 元素

自动搜索

指南

开始前：首先获取 API URL：从$BROWSERWING_EXECUTOR_URL环境变量中读取，或默认使用http://127.0.0.1:8080
如果不确定可用的命令或其参数，请调用GET /help （注意：根据上下文和中文表达习惯，最后两个段落“Call”和“if you're unsure about available commands or their parameters”被合并翻译为一个完整的句子，并相应调整了分隔符的放置位置以保持段落数量一致。）
确保浏览器已启动（如果未启动，将在首次操作时自动启动）

自动化过程中：

始终在导航后调用/snapshot以获取页面结构和引用ID优先使用引用ID
（例如@e1）而非CSS选择器，以确保可靠性和稳定性页面变更后重新快照
以获取更新的引用ID使用
/wait处理异步加载的动态内容交互前检查元素状态
（可见性、可用性）使用
/batch处理多个连续操作以提高效率错误处理：

若操作失败，请检查元素标识符并尝试不同格式

If operation fails, check element identifier and try different format
对于超时错误，增加超时值
如果未找到元素，调用/snapshot以刷新页面结构
向用户清晰解释错误并提供建议的解决方案

数据提取：

使用fields参数指定要提取的内容：["text", "href", "src"]
设置multiple: true以从多个元素中提取数据
将提取的数据以用户可读的方式格式化

完整工作流程示例

场景：用户希望登录一个网站

User: "Please log in to example.com with username 'john' and password 'secret123'"

您的操作：

步骤1：导航到登录页面

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/login"}'

步骤2：获取页面结构

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

响应：

Clickable Elements:
  @e1 Login (role: button)

Input Elements:
  @e2 Username (role: textbox)
  @e3 Password (role: textbox)

第三步：输入用户名

POST http://127.0.0.1:18085/api/v1/executor/type
{"identifier": "@e2", "text": "john"}

第四步：输入密码

POST http://127.0.0.1:18085/api/v1/executor/type
{"identifier": "@e3", "text": "secret123"}

第五步：点击登录按钮

POST http://127.0.0.1:18085/api/v1/executor/click
{"identifier": "@e1"}

第六步：等待登录成功（可选）

POST http://127.0.0.1:18085/api/v1/executor/wait
{"identifier": ".welcome-message", "state": "visible", "timeout": 10}

第七步：通知用户

"Successfully logged in to example.com!"

批量操作示例

场景：填写包含多个字段的表单

不要进行5次单独的API调用，而是使用一次批量操作：

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"
curl -X POST "${EXECUTOR_URL}/api/v1/executor/batch" \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {
        "type": "navigate",
        "params": {"url": "https://example.com/form"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#name", "text": "John Doe"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#email", "text": "john@example.com"},
        "stop_on_error": true
      },
      {
        "type": "select",
        "params": {"identifier": "#country", "value": "United States"},
        "stop_on_error": true
      },
      {
        "type": "click",
        "params": {"identifier": "#submit"},
        "stop_on_error": true
      }
    ]
  }'

最佳实践

先探索：如果不确定，请调用/help或/help?command=<名称>来了解命令
先获取结构：始终先调用/snapshot导航后理解页面内容
使用无障碍索引：它们比CSS选择器更可靠（元素可能具有动态类名）
等待动态内容加载：使用/wait在与异步加载的元素交互前
尽可能批量操作：使用/batch处理多个顺序操作
优雅地处理错误：当操作失败时，提供清晰的解释和建议
验证结果：操作后，检查是否达到了预期结果

常见场景

表单填写

导航到表单页面
获取无障碍快照以查找输入元素及其RefID
使用/type为每个字段输入内容@e1,@e2, 等等。
使用/select处理下拉菜单
使用其 RefID 点击提交按钮

数据抓取

导航到目标页面
使用/wait
等待内容加载使用/extract配合 CSS 选择器和
multiple: true指定要提取的字段：

["text", "href", "src"]

搜索操作
导航到搜索页面
获取无障碍快照以定位搜索输入框
在输入框中键入搜索查询
按 Enter 键或点击搜索按钮
提取结果数据

登录自动化

导航到登录页面
获取无障碍快照以查找RefID
输入用户名：@e2
输入密码：@e3
点击登录按钮：@e1
等待成功指示器

重要说明

浏览器必须正在运行（首次操作时如需将自动启动）
操作将在当前活动的浏览器标签页上执行
每次导航和点击操作后都会更新无障碍快照
所有超时时间均以秒为单位
使用wait_visible: true（默认）以确保元素交互可靠
API地址：始终从$BROWSERWING_EXECUTOR_URL 读取环境变量，若未设置则回退到http://127.0.0.1:8080如果未设置
需要身份验证：使用X-BrowserWing-Key请求头或配置的 JWT 令牌

故障排除

未找到元素：

调用/snapshot以查看可用元素
尝试不同的标识符格式（无障碍索引、CSS 选择器、文本）
检查页面是否已完成加载

超时错误：

增加请求中的超时值
检查元素是否实际出现在页面上
在交互前使用/wait并设置适当的状态

提取返回为空：

验证 CSS 选择器是否匹配目标元素
检查内容是否已加载（使用/等待第一）
尝试不同的提取字段或输入

快速参考

EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"

# Discover commands
curl -X GET "${EXECUTOR_URL}/api/v1/executor/help"

# Navigate
curl -X POST "${EXECUTOR_URL}/api/v1/executor/navigate" \
  -H 'Content-Type: application/json' \
  -d '{"url": "..."}'

# Get page structure
curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot"

# Click element
curl -X POST "${EXECUTOR_URL}/api/v1/executor/click" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

# Type text
curl -X POST "${EXECUTOR_URL}/api/v1/executor/type" \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "..."}'

# Extract data
curl -X POST "${EXECUTOR_URL}/api/v1/executor/extract" \
  -H 'Content-Type: application/json' \
  -d '{"selector": "...", "fields": [...], "multiple": true}'

响应格式

所有操作返回：

{
  "success": true,
  "message": "Operation description",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    // Operation-specific data
  }
}

错误响应：

{
  "error": "error.operationFailed",
  "detail": "Detailed error message"
}

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Context Recovery 下一篇：Openclaw Godmode Skill Repo