browserpilot-executor

用途

BrowserPilot Executor 通过 HTTP API 提供浏览器自动化控制能力，可用于让程序或智能体驱动浏览器完成导航、交互、数据提取与页面结构分析等任务。

主要能力

• 页面导航：跳转到 URL、后退、前进、刷新。
• 元素交互：点击、输入文本、选择下拉选项、悬停、等待元素状态、按键。
• 数据提取：从元素中提取文本、属性、值，支持多元素与自定义字段。
• 语义分析：获取语义树以理解页面结构，获取可点击元素与输入元素列表。
• 高级操作：截图（base64 编码）、执行 JavaScript、滚动到底部、调整浏览器窗口大小。
• 批量处理：按顺序执行多个操作，可设置出错即停。

使用方式

API 基础地址：http://127.0.0.1:8080/api/v1/executor

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

建议工作流：

1. 发现命令：GET /help，可查询具体命令 GET /help?command=extract。
2. 导航：POST /navigate，请求体如 {"url": "https://example.com"}。
3. 分析页面：GET /semantic-tree，获取元素索引与页面结构。
4. 交互：使用 POST /click、POST /type、POST /select、POST /wait 等。
5. 提取数据：POST /extract，可指定 selector、fields、multiple。
6. 展示结果：将提取的数据格式化后呈现。

元素识别方式包括：语义索引（如 [1]、Input Element [1]，推荐）、CSS 选择器、文本内容、XPath、ARIA 标签。

批量操作示例：

curl -X POST 'http://127.0.0.1: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": "[1]"}, "stop_on_error": true},
      {"type": "type", "params": {"identifier": "[1]", "text": "query"}, "stop_on_error": true}
    ]
  }'

适用场景

• 表单填写：导航到表单页，获取语义树，逐字段输入，选择下拉项，点击提交。
• 数据抓取：导航到目标页，等待内容加载，使用 /extract 配合 CSS 选择器与 multiple: true 提取数据。
• 搜索操作：定位搜索输入框，输入查询词，按回车或点击搜索按钮，等待结果并提取。
• 登录自动化：输入用户名与密码，点击登录按钮，等待成功标识。

限制与注意事项

• 浏览器必须处于运行状态；若未启动，首次操作时会自动启动。
• 操作在当前活动浏览器标签页上执行。
• 语义树会在每次导航和点击操作后更新。
• 所有超时时间单位为秒。
• 默认使用 wait_visible: true 以保证元素交互可靠。
• 需将 127.0.0.1:8080 替换为实际 API 主机地址。
• 需要认证，使用 X-BrowserWing-Key 请求头或 JWT token。
• 常见问题：元素未找到时可重新获取语义树或更换标识格式；超时错误可增大超时值；提取为空时检查选择器与内容加载状态。

响应格式

成功响应：

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

错误响应：

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