mini-browser

mini-browser (mb) — 面向 Agent 的浏览器命令行工具

mb 是一款浏览器命令行工具，其中每条命令都是一个小型 Unix 工具。它通过 puppeteer-core 使用 CDP（端口 9222）与 Chrome 通信。

设置（仅在尚不可用时）

仅当尚未安装 mb 或无法连接 Chrome 时才需要设置。 先运行这些检查——如果两项都通过，请直接跳到命令参考。

检查是否就绪

# 1. Is mb installed?
which mb && echo "mb: ok" || echo "mb: MISSING"

# 2. Is Chrome listening on CDP?
curl -sf http://127.0.0.1:9222/json/version > /dev/null && echo "chrome: ok" || echo "chrome: NOT RUNNING"

如果两项都显示“ok”，则表示一切就绪——可直接使用 mb 命令。

安装（仅在缺少 mb 时）

npm install -g @runablehq/mini-browser

启动 Chrome（仅在未运行时）

mb-start-chrome

此命令会使用 --remote-debugging-port=9222、全新的配置文件和一个 1024×768 的窗口启动 Chrome。如果 Chrome 已在运行，则不执行任何操作。

要终止并重新启动：

mb-restart-chrome

验证

mb go "https://example.com" && mb text

环境变量

变量	默认值	描述
CHROME_PORT	9222	CDP 端口
CHROME_BIN	自动检测	Chrome/Chromium 二进制文件的路径
CHROME_PID_FILE	<scripts>/.chrome-pid	PID 文件位置
CHROME_USER_DATA_DIR	<scripts>/.chrome-profile	Chrome 配置文件目录

命令参考

导航

命令	描述
mb go <url>	导航到 URL（等待 networkidle）
mb url	输出当前 URL
mb back	后退
mb forward	前进

观察

命令	描述
mb text [selector]	可见文本内容（默认：body）
mb shot [file]	截取 PNG 屏幕截图（默认：./shot.png）
mb snap	列出可交互元素及其坐标

交互

命令	描述
mb click <x> <y>	点击指定坐标
mb type [x y] <text>	输入文本（带坐标时：选中第一个）
mb fill <k=v...>	按标签/名称/占位符填写表单字段
mb key <key...>	按下按键（Enter、Tab、Meta+a）
mb move <x> <y>	将鼠标悬停在指定坐标
mb drag <x1> <y1> <x2> <y2>	在两点之间拖动
mb scroll [dir] [px]	滚动（默认：向下 500）

录制

命令	描述
mb record start <file>	开始录制（.webm、.mp4、.gif）
mb record stop	停止录制并保存
mb record status	检查录制是否正在进行

标签页

命令	描述
mb tab list	列出已打开的标签页
mb tab new [url]	打开新标签页并输出索引
mb tab close [n]	关闭标签页（默认：最后一个）

其他

命令	描述
mb js <code>	在页面上下文中运行 JavaScript
mb wait <target>	等待毫秒数 / 选择器 / networkidle / url:pattern
mb audit	设计审查（配色、字体、对比度、无障碍、SEO）
mb logs	持续输出控制台日志（按 Ctrl+C 停止）

标志

标志	默认值	描述
--timeout <ms>	30000	命令超时时间
--tab <n>	0	目标标签页索引
--json	false	结构化 JSON 输出
--right	false	右键单击
--double	false	双击
--fps <n>	30	录制帧率
--scale <n>	1	录制缩放比例

使用模式

观察 → 操作循环

标准的 Agent 循环：截取页面快照、选择元素并对其执行操作。

mb snap                          # list interactive elements with (x, y)
mb click 512 380                 # click the button at those coordinates
mb wait networkidle              # wait for the page to settle
mb snap                          # observe again

填写并提交表单

mb go "https://example.com/login"
mb fill "[email protected]" "Password=hunter2"
mb key Enter
mb wait url:/dashboard

截取屏幕截图

mb shot page.png
mb shot page.png --width 1440 --height 900

提取文本

mb text "main"                   # text from <main>
mb text "#content"               # text from #content
mb text                          # full body text

运行 JavaScript

mb js 'document.title'
echo 'document.querySelectorAll("a").length' | mb js -

录制屏幕录像

mb record start demo.mp4 --fps 30 --scale 1
# ... interact with the page ...
mb record stop

设计审查

mb audit                         # human-readable report
mb audit --json                  # structured JSON output

关闭覆盖层

Cookie 横幅和模态框会阻挡点击。使用 JS 将其移除：

mb js 'document.querySelector("[class*=cookie]")?.remove()'

等待策略

mb wait 2000                     # sleep 2 seconds
mb wait ".modal"                 # wait for selector to appear
mb wait networkidle              # wait for no network activity
mb wait url:/dashboard           # wait for URL to contain string

重要说明

• 视口为 1024×768。 snap 只会返回当前视口中的元素 — 滚动后再次执行 snap，以查找更多元素。
• text 使用 querySelector — 只返回第一个匹配项。使用 text "main" 比使用 text "p" 更容易获得理想结果。
• go 会等待 networkidle。 对于大型 SPA，后续执行 wait ".selector"。
• 使用坐标执行 type 时，会先三击选中现有文本，再输入替换内容。
• fill 字段匹配顺序： aria-label → placeholder → name 属性 → id → 标签文本 → CSS 选择器（使用 #/./[ 前缀）。
• --json 输出： snap → [{role, name, x, y, state}]，tab list → [{index, url, title}]，logs → JSON 行，audit → 完整审计对象。
• 录制状态存储在 ~/.mb-recorder.json 中。一次只能进行一项录制。
• tab close 无法关闭最后一个剩余标签页。

故障排查

问题	解决方法
"Chrome not found"	设置 CHROME_BIN=/path/to/chrome
连接被拒绝	先运行 mb-start-chrome
录制状态过期	删除 ~/.mb-recorder.json
Chrome 窗口大小不正确	执行 mb-restart-chrome（会创建新的配置文件）
snap 输出中没有该元素	执行 mb scroll down 500，然后再次执行 mb snap