介绍
# BrowserWing Executor API
## 概述
BrowserWing 执行器通过 HTTP API 提供全面的浏览器自动化功能。您可以控制浏览器导航、与页面元素交互、提取数据并分析页面结构。
## 配置
**API 基础 URL：** BrowserWing 执行器 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-key>` 请求头，如果需要，也可使用 `Authorization: Bearer <token>`。
**重要提示：** 始终通过首先读取环境变量来构建 API URL。在 shell 命令中，请使用：`${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}`
## 核心功能
- **页面导航：** 导航至 URL、前进/后退、刷新 - **元素交互：** 点击、输入、选择、悬停于页面元素 - **数据提取：** 从元素中提取文本、属性、值 - **可访问性分析：** 获取可访问性快照以了解页面结构 - **高级操作：** 截图、JavaScript 执行、键盘输入 - **批量处理：** 按顺序执行多个操作
## API 端点
### 1. 发现可用命令
**重要：** 始终首先调用此端点以查看所有可用命令及其参数。
```bash EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}" curl -X GET "${EXECUTOR_URL}/api/v1/executor/help" ```
**响应：** 返回所有命令的完整列表，包含参数、示例和用法指南。
**查询特定命令：** ```bash EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}" curl -X GET "${EXECUTOR_URL}/api/v1/executor/help?command=extract" ```
### 2. 获取可访问性快照
**关键：** 导航后始终调用此方法以了解页面结构并获取元素 RefID。
```bash EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}" curl -X GET "${EXECUTOR_URL}/api/v1/executor/snapshot" ```
**响应示例：** ```json { "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 更整洁，更适合 LLM - RefID 是稳定的引用，在页面更改时能可靠工作
### 3. 常用操作
**注意：** 以下所有示例均使用 `EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"` 从环境变量读取 API 地址，并以 `http://127.0.0.1:8080` 作为默认回退值。
#### 导航至 URL ```bash 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"}' ```
#### 点击元素 ```bash 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']` - **文本：** `Login`（文本内容）
#### 输入文本 ```bash 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": "[email protected]"}' ```
#### 提取数据 ```bash 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 }' ```
#### 等待元素 ```bash 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}' ```
#### 批量操作 ```bash 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} ] }' ```
## 指令
**分步工作流程：**
0. **获取 API URL：** 首先，从环境变量 `$BROWSERWING_EXECUTOR_URL` 读取 API 基础 URL。如果未设置，则使用默认值 `http://127.0.0.1:8080`。在 shell 命令中，请使用：`EXECUTOR_URL="${BROWSERWING_EXECUTOR_URL:-http://127.0.0.1:8080}"`
1. **发现命令：** 调用 `GET /help` 查看所有可用操作及其参数（如果不确定，请先执行此操作）。
2. **导航：** 使用 `POST /navigate` 打开目标网页。
3. **分析页面：** 调用 `GET /snapshot` 了解页面结构并获取元素 RefID。
4. **交互：** 使用元素 RefID（如 `@e1`, `@e2`）或 CSS 选择器来： - 点击元素：`POST /click` - 输入文本：`POST /type` - 选择选项：`POST /select` - 等待元素：`POST /wait`
5. **提取数据：** 使用 `POST /extract` 从页面获取信息。
6. **展示结果：** 格式化并向用户展示提取的数据。
## 完整示例
**用户请求：** "在 example.com 上搜索 'laptop' 并获取前 5 个结果"
**您的操作：**
1. 导航至搜索页面： ```bash curl -X POST 'http://127.0.0.1:18085/api/v1/executor/navigate' \ -H 'Content-Type: application/json' \ -d '{"url": "https://example.com/search"}' ```
2. 获取页面结构以查找搜索输入框： ```bash curl -X GET 'http://127.0.0.1:18085/api/v1/executor/snapshot' ``` 响应显示：`@e3 Search (role: textbox) [placeholder: Search...]`
3. 输入搜索查询： ```bash curl -X POST 'http://127.0.0.1:18085/api/v1/executor/type' \ -H 'Content-Type: application/json' \ -d '{"identifier": "@e3", "text": "laptop"}' ```
4. 按下 Enter 提交： ```bash curl -X POST 'http://127.0.0.1:18085/api/v1/executor/press-key' \ -H 'Content-Type: application/json' \ -d '{"key": "Enter"}' ```
5. 等待结果加载： ```bash 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}' ```
6. 提取搜索结果： ```bash 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 }' ```
7. 展示提取的数据： ``` Found 15 results for 'laptop': 1. Gaming Laptop - $1299 (https://...) 2. Business Laptop - $899 (https://...) ... ```
## 关键命令参考
### 导航 - `POST /navigate` - 导航至 URL - `POST /go-back` - 后退 - `POST /go-forward` - 前进 - `POST /reload` - 刷新当前页面
### 元素交互 - `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` - 关闭当前页面/标签页
## 元素标识
您可以使用以下方式标识元素：
1. **RefID（推荐）：** `@e1`, `@e2`, `@e3` - 最可靠的方法 - 在页面更改时保持稳定 - 从 `/snapshot` 端点获取 RefID - 快照后 5 分钟内有效 - 示例：`"identifier": "@e1"` - 支持多策略回退以提高稳健性
2. **CSS 选择器：** `#id`, `.class`, `button[type="submit"]` - 标准 CSS 选择器 - 示例：`"identifier": "#login-button"`
3. **XPath：** `//button[@id='login']`, `//a[contains(text(), 'Submit')]` - 用于复杂查询的 XPath 表达式 - 示例：`"identifier": "//button[@id='login']"`
4. **文本内容：** `Login`, `Sign Up`, `Submit` - 搜索包含匹配文本的按钮和链接 - 示例：`"identifier": "Login"`
5. **ARIA 标签：** 具有 `aria-label` 属性的元素 - 自动搜索
## 指南
**开始之前：** - **首先获取 API URL：** 从 `$BROWSERWING_EXECUTOR_URL` 环境变量读取，或使用默认值 `http://127.0.0.1:8080` - 如果不确定可用命令或其参数，请调用 `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：** 导航至登录页面 ```bash 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：** 获取页面结构 ```bash 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) ```
**步骤 3：** 输入用户名 ```bash POST http://127.0.0.1:18085/api/v1/executor/type {"identifier": "@e2", "text": "john"} ```
**步骤 4：** 输入密码 ```bash POST http://127.0.0.1:18085/api/v1/executor/type {"identifier": "@e3", "text": "secret123"} ```
**步骤 5：** 点击登录按钮 ```bash POST http://127.0.0.1:18085/api/v1/executor/click {"identifier": "@e1"} ```
**步骤 6：** 等待登录成功（可选） ```bash POST http://127.0.0.1:18085/api/v1/executor/wait {"identifier": ".welcome-message", "state": "visible", "timeout": 10} ```
**步骤 7：** 通知用户 ``` "Successfully logged in to example.com!" ```
## 批量操作示例
**场景：** 填写包含多个字段的表单
不要进行 5 次单独的 API 调用，而是使用一次批量操作：
```bash 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": "[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 } ] }' ```
## 最佳实践
1. **首先发现：** 如果不确定，请调用 `/help` 或 `/help?command=<name>` 以了解命令 2. **结构优先：** 导航后始终调用 `/snapshot` 以了解页面 3. **使用可访问性索引：** 它们比 CSS 选择器更可靠（元素可能有动态类） 4. **等待动态内容：** 在与异步加载的元素交互之前使用 `/wait` 5. **尽可能批量：** 对多个连续操作使用 `/batch` 6. **优雅处理错误：** 提供清晰的说明
以及操作失败时的建议 7. **验证结果：** 操作完成后，检查是否达到了预期结果
## 常见场景
### 表单填写 1. 导航至表单页面 2. 获取无障碍快照以查找输入元素及其 RefID 3. 对每个字段使用 `/type`：`@e1`、`@e2` 等 4. 对下拉菜单使用 `/select` 5. 使用其 RefID 点击提交按钮
### 数据抓取 1. 导航至目标页面 2. 使用 `/wait` 等待内容加载 3. 使用带有 CSS 选择器和 `multiple: true` 的 `/extract` 4. 指定要提取的字段：`["text", "href", "src"]`
### 搜索操作 1. 导航至搜索页面 2. 获取无障碍快照以定位搜索输入框 3. 在输入框中输入搜索查询 4. 按回车键或点击搜索按钮 5. 等待结果 6. 提取结果数据
### 登录自动化 1. 导航至登录页面 2. 获取无障碍快照以查找 RefID 3. 输入用户名：`@e2` 4. 输入密码：`@e3` 5. 点击登录按钮：`@e1` 6. 等待成功指示器
## 重要说明
- 浏览器必须正在运行（如果需要，它会在首次操作时自动启动） - 操作在**当前活动的浏览器标签页**上执行 - 无障碍快照在每次导航和点击操作后更新 - 所有超时时间均以秒为单位 - 使用 `wait_visible: true`（默认）以确保可靠的元素交互 - **API 地址：** 始终从 `$BROWSERWING_EXECUTOR_URL` 环境变量中读取，如果未设置则回退到 `http://127.0.0.1:8080` - 需要身份验证：如果已配置，请使用 `X-BrowserWing-Key` 标头或 JWT 令牌
## 故障排除
**找不到元素：** - 调用 `/snapshot` 查看可用元素 - 尝试不同的标识符格式（无障碍索引、CSS 选择器、文本） - 检查页面是否已完成加载
**超时错误：** - 增加请求中的超时值 - 检查元素是否实际出现在页面上 - 在交互之前使用带有适当状态的 `/wait`
**提取结果为空：** - 验证 CSS 选择器是否匹配目标元素 - 检查内容是否已加载（先使用 `/wait`） - 尝试不同的提取字段或类型
## 快速参考
```bash 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}' ```
## 响应格式
所有操作返回： ```json { "success": true, "message": "Operation description", "timestamp": "2026-01-15T10:30:00Z", "data": { // Operation-specific data } } ```
**错误响应：** ```json { "error": "error.operationFailed", "detail": "Detailed error message" } ```