browserwing-executor

Name: browserwing-executor
Author: memtensor

github.com/memtensorAgent 工作流12.2k133 次安装5 天前更新

代码仓库

关于 browserwing-executor

browserwing-executor 是面向 Agent 的浏览器自动化技能，通过 BrowserWing HTTP API 操作网页，涵盖页面交互、无障碍快照、数据提取和批量执行。

主要功能

01导航并控制页面
02查看无障碍快照
03点击、输入和选择元素
04提取页面数据
05按序执行批量操作

适用场景

01自动执行网站搜索
02填写并提交网页表单
03收集结构化页面内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/memtensor/memos --skill browserwing-executor

安装后在 Claude Code 中输入/browserwing-executor确认已加载。

详细介绍

BrowserWing Executor API

概述

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

API 基础 URL： http://localhost:8080/api/v1/executor

身份验证： 使用 X-BrowserWing-Key: <api-key> 请求头或 Authorization: Bearer <token>

核心功能

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

API 端点

1. 发现可用命令

重要： 始终先调用此端点，查看所有可用命令及其参数。

curl -X GET 'http://localhost:8080/api/v1/executor/help'

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

查询特定命令：

curl -X GET 'http://localhost:8080/api/v1/executor/help?command=extract'

2. 获取无障碍快照

关键： 每次导航后都要调用此端点，以了解页面结构并获取元素 RefID。

curl -X GET 'http://localhost:8080/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: [email protected]]\n  @e4 Password (role: textbox)"
}

使用场景：

了解页面上有哪些交互元素
获取元素 RefID（@e1、@e2 等），以便准确识别
查看元素标签、角色和属性
无障碍树比原始 DOM 更简洁，也更适合大模型处理
RefID 是稳定的引用，即使页面发生变化也能可靠使用

3. 常见操作

导航到 URL

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

点击元素

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

标识符格式：

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

输入文本

curl -X POST 'http://localhost:8080/api/v1/executor/type' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "[email protected]"}'

提取数据

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

等待元素

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

批量操作

curl -X POST 'http://localhost:8080/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}
    ]
  }'

使用说明

分步工作流：

发现命令： 调用 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://localhost:8080/api/v1/executor/navigate' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/search"}'

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

curl -X GET 'http://localhost:8080/api/v1/executor/snapshot'

响应显示：@e3 Search (role: textbox) [placeholder: Search...]

输入搜索内容：

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

按 Enter 提交：

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

等待结果加载：

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

提取搜索结果：

curl -X POST 'http://localhost:8080/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 端点获取 RefID
- 快照生成后 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']"
文本内容： Login、Sign Up、Submit
- 搜索文本匹配的按钮和链接
- 示例："identifier": "Login"
ARIA 标签： 带有 aria-label 属性的元素
- 自动搜索

指南

开始之前：

如果不确定有哪些可用命令或其参数，请调用 GET /help
确保浏览器已启动（如果尚未启动，首次操作时会自动启动）

自动化过程中：

导航后始终调用 /snapshot，以获取页面结构和 RefID
为确保可靠性和稳定性，优先使用 RefID（如 @e1），而非 CSS 选择器
页面更改后重新获取快照，以获取更新后的 RefID
对于异步加载的动态内容，请使用 /wait
交互前检查元素状态（是否可见、是否启用）
使用 /batch 执行多个连续操作，以提高效率

错误处理：

如果操作失败，请检查元素标识符并尝试其他格式
对于超时错误，请增加超时值
如果找不到元素，请再次调用 /snapshot 以刷新页面结构
向用户清楚说明错误并提供建议的解决方案

数据提取：

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

完整工作流示例

场景： 用户想要登录网站

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

你的操作：

步骤 1： 导航到登录页面

POST http://localhost:8080/api/v1/executor/navigate
{"url": "https://example.com/login"}

步骤 2： 获取页面结构

GET http://localhost:8080/api/v1/executor/snapshot

响应：

Clickable Elements:
  @e1 Login (role: button)

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

步骤 3： 输入用户名

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

步骤 4： 输入密码

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

步骤 5： 点击登录按钮

POST http://localhost:8080/api/v1/executor/click
{"identifier": "@e1"}

步骤 6： 等待登录成功（可选）

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

步骤 7： 告知用户

"Successfully logged in to example.com!"

批量操作示例

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

无需分别进行 5 次 API 调用，只需使用一次批量操作：

curl -X POST 'http://localhost:8080/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": "[email protected]"},
        "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=<name> 了解命令
先了解结构： 导航后务必调用 /snapshot 了解页面
使用无障碍索引： 它们比 CSS 选择器更可靠（元素可能使用动态类名）
等待动态内容： 与异步加载的元素交互前，使用 /wait
尽可能批量处理： 对多个连续操作使用 /batch
妥善处理错误： 操作失败时提供清晰的解释和建议
验证结果： 操作完成后，检查是否达成预期结果

常见场景

填写表单

导航到表单页面
获取无障碍快照，查找输入元素及其 RefID
对每个字段使用 /type：@e1、@e2 等
对下拉列表使用 /select
使用对应的 RefID 点击提交按钮

抓取数据

导航到目标页面
使用 /wait 等待内容加载
使用 CSS 选择器和 multiple: true 调用 /extract
指定要提取的字段：["text", "href", "src"]

搜索操作

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

登录自动化

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

重要说明

浏览器必须处于运行状态（如果需要，首次操作时会自动启动）
操作会在当前活动的浏览器标签页中执行
每次导航和点击操作后，无障碍快照都会更新
所有超时值均以秒为单位
使用 wait_visible: true（默认值）以确保可靠地与元素交互
将 localhost:8080 替换为实际的 API 主机地址
需要进行身份验证：使用 X-BrowserWing-Key 标头或 JWT 令牌

故障排除

找不到元素：

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

超时错误：

增大请求中的超时值
检查元素是否确实出现在页面上
交互前使用 /wait 等待适当的状态

提取结果为空：

确认 CSS 选择器与目标元素匹配
检查内容是否已加载（先使用 /wait）
尝试其他提取字段或类型

快速参考

# Discover commands
GET localhost:8080/api/v1/executor/help

# Navigate
POST localhost:8080/api/v1/executor/navigate {"url": "..."}

# Get page structure
GET localhost:8080/api/v1/executor/snapshot

# Click element
POST localhost:8080/api/v1/executor/click {"identifier": "@e1"}

# Type text
POST localhost:8080/api/v1/executor/type {"identifier": "@e3", "text": "..."}

# Extract data
POST localhost:8080/api/v1/executor/extract {"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"
}

支持 Markdown

登录后评论

基本信息

作者: memtensor
仓库: memtensor/memos
分类: Agent 工作流
安装次数: 133
GitHub Stars: 12,157

报告问题