browser-js

一款轻量级命令行工具，通过 CDP（Chrome DevTools Protocol）与 Chrome 浏览器通信。返回精简、已索引的输出，使智能体可立即执行操作 —— 无需解析可访问性树（accessibility tree），也无需查找 DOM 引用（ref hunting）。

安装配置

# 安装依赖（仅需一次，在 skill 的 scripts/ 目录下执行）
cd scripts && npm install

# 确保浏览器已启动并启用 CDP。
# 使用 OpenClaw：
#   browser start profile=openclaw
# 或手动启动：
#   google-chrome --remote-debugging-port=18800 --user-data-dir=~/.browser-data

该工具默认连接 http://127.0.0.1:18800。可通过环境变量 CDP_URL 覆盖此地址。

别名配置（可选）

mkdir -p ~/.local/bin
cat > ~/.local/bin/bjs << 'WRAPPER'
#!/bin/bash
exec node /path/to/scripts/browser.js "$@"
WRAPPER
chmod +x ~/.local/bin/bjs

命令列表

bjs tabs                    列出当前打开的标签页
bjs open               导航至指定 URL
bjs tab              切换到指定索引的标签页
bjs newtab [url]            新建标签页（可选自动导航至 URL）
bjs close [index]           关闭指定索引的标签页
bjs elements [selector]     列出所有可交互元素（已编号索引）
bjs click            按索引点击对应元素
bjs type       向指定索引的元素中输入文本
bjs upload  [selector] 将文件上传至 input 元素（绕过操作系统文件选择对话框）
bjs text [selector]         提取页面可见文本内容
bjs html          获取匹配元素的 HTML 内容
bjs eval                在页面上下文中执行 JavaScript 代码
bjs screenshot [path]       保存当前页面截图
bjs scroll  [px]
bjs url                     获取当前页面 URL
bjs back / forward / refresh  后退 / 前进 / 刷新
bjs wait 

坐标类命令（适用于跨域 iframe、验证码、浮层等场景）：
bjs click-xy         通过 CDP Input 在页面坐标处触发点击
bjs click-xy   --double   在指定坐标处双击
bjs click-xy   --right    在指定坐标处右键点击
bjs hover-xy         在页面坐标处触发鼠标悬停
bjs drag-xy       在两组坐标间执行拖拽操作
bjs iframe-rect  获取 iframe 的边界框（用于 click-xy 定位）

工作原理

elements 命令会扫描整个页面，查找所有可交互元素（链接、按钮、输入框、下拉框等）——包括位于 Shadow DOM 内的元素（即 Web Components）。这意味着 Reddit、GitHub 等大量采用 Shadow DOM 的现代单页应用（SPA）均可完整支持。elements 会递归穿透所有 Shadow Root。

返回格式为紧凑的编号列表：

[0] (link) Hacker News → https://news.ycombinator.com/news
[1] (link) new → https://news.ycombinator.com/newest
[2] (input:text) q
[3] (button) Submit

随后即可直接执行 click 3 或 type 2 search query —— 即刻生效，无需额外解释或映射。

自动索引：click 和 type 命令会在目标元素尚未被索引时自动触发索引。你无需先调用 elements，可在 open 后直接使用 click/type。仅当你需要查看页面当前有哪些可交互元素时，才显式调用 elements。

导航或 AJAX 更新后：若页面状态发生变更（如跳转或异步加载），当检测到缓存的索引已过期时，下一次 click/type 将自动重新索引。如需手动刷新索引，可再次运行 elements。

真实鼠标事件：click 使用 CDP 的 Input.dispatchMouseEvent（mousePressed + mouseReleased），而非 JavaScript 原生的 .click() 方法。因此可正确触发 React/Vue/Angular 等框架中忽略原生 .click() 的合成事件处理器。在 Instagram、GitHub、LinkedIn 等 SPA 上表现稳定可靠。

文件上传

upload 使用 CDP 的 DOM.setFileInputFiles 接口，将文件直接注入隐藏的 元素 —— 完全绕过操作系统级文件选择对话框。适用于 Instagram、Twitter 等所有支持文件上传的网站。

bjs upload ~/photos/image.jpg                    # 自动查找 input[type=file]
bjs upload ~/docs/resume.pdf "input.file-drop"   # 指定 CSS 选择器

Token 效率对比

执行一个包含 10 步操作的流程：使用 bjs 仅需约 1,500 tokens，而 browser tool 需约 30,000–80,000 tokens。

典型操作流程

bjs open https://example.com       # 导航至目标页面
bjs elements                        # 查看当前可交互元素
bjs click 5                         # 点击第 [5] 个元素
bjs type 12 "hello world"          # 向第 [12] 个元素输入文本
bjs text                            # 提取页面可见文本内容
bjs screenshot /tmp/result.png      # 截图验证结果

Shadow DOM 支持

bjs 自动穿透 Shadow DOM 边界。基于 Web Components 构建的网站（如 Reddit、GitHub 等）开箱即用 —— elements、click、type 和 text 均会递归进入 Shadow Root，无需任何特殊标志或配置。

坐标类命令（适用于 iframe、验证码、浮层等场景）

当无法通过索引使用 click（例如目标元素位于跨域 iframe 中，如 hCaptcha 复选框、支付表单、OAuth 小部件）时，请改用基于坐标的命令。这些命令通过 CDP Input 在操作系统层面派发真实输入事件，从而完全绕过 DOM 边界限制。

在 iframe 内点击的操作流程：

bjs iframe-rect 'iframe[title*="hCaptcha"]'    # 获取 iframe 在页面中的位置
# 输出示例：x=95 y=440 w=302 h=76 center=(246, 478)

bjs click-xy 125 458                            # 在复选框位置点击

iframe-rect 返回 iframe 在视口中的绝对位置。你可在此基础上叠加偏移量，精确定位其内部特定元素（例如复选框通常靠近左侧区域）。

其他常见用途：

• hover-xy — 触发依赖鼠标坐标的悬停菜单、工具提示（tooltip）
• drag-xy — 控制滑块、实现拖放、与 Canvas 交互
• click-xy --double — 双击以选中文本、展开折叠项
• click-xy --right — 打开上下文菜单（右键菜单）

何时选用坐标命令 vs click：

• click —— 若目标元素已出现在 elements 列表中，则始终优先使用该方式
• click-xy —— 仅当目标位于跨域 iframe 中，或因其他原因无法通过 DOM 索引访问时使用

使用技巧

• elements 支持传入 CSS 选择器以缩小扫描范围：bjs elements ".modal"
• eval 可执行任意 JavaScript 并返回结果，适用于定制化数据提取
• text 输出上限为 8KB —— 足以覆盖绝大多数页面内容，避免上下文爆炸
• html 输出上限为 10KB —— 适合检查特定元素结构
• 可配合 grep 过滤输出：bjs elements | grep -i "submit|login"