SuperAPI AI 工具集

browse

通用与其它

查看项目

更新于 11-06 16:20

技能介绍

用途

browse 是一个浏览器自动化命令行工具,配合 Claude 使用,用于自动化浏览器交互。它可以通过 CLI 命令导航网页、提取数据、截图、填写表单,并与 Web 应用进行交互。

环境选择(本地与远程)

CLI 会根据可用配置自动在本地和远程浏览器环境之间选择:

  • 本地模式(默认):使用本地 Chrome,无需 API 密钥。适合开发、简单页面、无机器人防护的可信站点。
  • 远程模式(Browserbase):当设置了 BROWSERBASE_API_KEY 和 BROWSERBASE_PROJECT_ID 时激活。提供反机器人隐身、自动验证码识别、住宅代理、会话持久化。适用于目标站点有机器人检测、验证码、IP 限流、Cloudflare 防护,或需要特定地区访问的场景。凭据可在 https://browserbase.com/settings 获取。

选择建议:简单浏览(文档、维基、公共 API)使用本地模式即可;受保护站点(登录墙、验证码、反爬)使用远程模式;如果本地模式因机器人检测或访问被拒而失败,切换到远程模式。

主要能力

所有命令在两种模式下行为一致,守护进程在首次命令时自动启动。

导航

  • browse open <url>:跳转到 URL(别名:goto)
  • browse reload:重新加载当前页面
  • browse back:在历史中后退
  • browse forward:在历史中前进

页面状态(优先使用 snapshot 而非 screenshot)

  • browse snapshot:获取带元素引用的可访问性树(快速、结构化)
  • browse screenshot [path]:截取可视化屏幕截图(较慢,消耗视觉 token)
  • browse get url:获取当前 URL
  • browse get title:获取页面标题
  • browse get text <selector>:获取文本内容(使用 "body" 获取全部文本)
  • browse get html <selector>:获取元素的 HTML 内容
  • browse get value <selector>:获取表单字段值

建议默认使用 browse snapshot 来理解页面状态,它返回带元素引用的可访问性树,可用于交互。仅在需要视觉上下文(布局、图片、调试)时使用 browse screenshot。

交互

  • browse click <ref>:按 snapshot 中的引用点击元素(例如 @0-5)
  • browse type <text>:向聚焦元素输入文本
  • browse fill <selector> <value>:填写输入框并回车
  • browse select <selector> <values...>:选择下拉选项
  • browse press <key>:按键(Enter、Tab、Escape、Cmd+A 等)
  • browse drag <fromX> <fromY> <toX> <toY>:从一点拖拽到另一点
  • browse scroll <x> <y> <deltaX> <deltaY>:在坐标处滚动
  • browse highlight <selector>:在页面上高亮元素
  • browse is visible <selector>:检查元素是否可见
  • browse is checked <selector>:检查元素是否被勾选
  • browse wait <type> [arg]:等待 load、selector 或 timeout

会话管理

  • browse stop:停止浏览器守护进程
  • browse status:检查守护进程状态(包含环境)
  • browse env:显示当前环境(本地或远程)
  • browse env local:切换到本地 Chrome
  • browse env remote:切换到 Browserbase(需要 API 密钥)
  • browse pages:列出所有打开的标签页
  • browse tab_switch <index>:按索引切换标签页
  • browse tab_close [index]:关闭标签页

使用方式

安装检查

在运行任何浏览器命令之前,先验证 CLI 是否可用:

which browse || npm install -g @browserbasehq/browse-cli

典型工作流

  1. browse open <url>:导航到页面
  2. browse snapshot:读取可访问性树,理解页面结构并获取元素引用
  3. browse click <ref> / browse type <text> / browse fill <selector> <value>:使用 snapshot 中的引用进行交互
  4. browse snapshot:确认操作生效
  5. 按需重复第 3-4 步
  6. browse stop:完成后关闭浏览器

快速示例

browse open https://example.com browse snapshot # 查看页面结构 + 元素引用 browse click @0-5 # 点击引用为 0-5 的元素 browse get title browse stop

模式对比

特性 本地 Browserbase
速度 更快 稍慢
设置 需要 Chrome 需要 API 密钥
隐身模式 否 是(定制 Chromium、反机器人指纹)
验证码识别 否 是(自动 reCAPTCHA/hCaptcha)
住宅代理 否 是(201 个国家、地理定位)
会话持久化 否 是(cookie/认证跨会话保持)
最适合 开发/简单页面 受保护站点、机器人检测、生产级抓取

适用场景

  • 简单浏览:文档、维基、公共 API,使用本地模式。
  • 受保护站点:登录墙、验证码、反爬,使用远程模式。
  • 生产级抓取:需要隐身、代理、会话持久化时使用远程模式。

最佳实践

  • 交互前始终先执行 browse open。
  • 使用 browse snapshot 检查页面状态,它快速且提供元素引用。
  • 仅在需要视觉上下文(布局检查、图片、调试)时使用 screenshot。
  • 使用 snapshot 中的引用进行点击/交互,例如 browse click @0-5。
  • 完成后执行 browse stop 清理浏览器会话。

限制与故障排查

  • "No active page":运行 browse stop,然后检查 browse status。如果仍显示运行中,用 pkill -f "browse.*daemon" 杀掉僵尸守护进程,再重试 browse open。
  • 找不到 Chrome:安装 Chrome 或使用 browse env remote。
  • 操作失败:运行 browse snapshot 查看可用元素及其引用。
  • Browserbase 失败:确认 API 密钥和项目 ID 已设置。

切换到远程模式

当检测到以下情况时切换到远程:验证码(reCAPTCHA、hCaptcha、Turnstile)、机器人检测页面("Checking your browser...")、HTTP 403/429、本应有内容的站点出现空白页,或用户要求时。

简单站点(文档、维基、公共 API、localhost)不要切换。

browse env remote # 切换到 Browserbase browse env local # 切回本地 Chrome

切换在运行 browse stop 或再次切换之前保持有效。

更多详细示例见 EXAMPLES.md,API 参考见 REFERENCE.md。