bb-browser

面向 AI Agent 的浏览器自动化 CLI 工具。

核心特性

• 复用用户登录态 - 运行在用户的浏览器中，自动复用已登录的网站（Gmail, Twitter, 内部系统等）
• AI Agent 友好 - 简洁的 CLI 接口，支持 JSON 输出，Ref 系统方便元素引用
• 反爬绕过 - 使用 chrome.debugger API，避免 Playwright 等工具的自动化指纹检测

架构

AI Agent (Claude, GPT, etc.)
       │ CLI 命令
       ▼
bb-browser CLI ──HTTP──▶ Daemon ──SSE──▶ Chrome Extension
                                              │
                                              ▼ chrome.debugger (CDP)
                                         用户浏览器
                                    (已登录的网站、Cookies)

安装

方式 1：npm 安装（推荐）

npm install -g bb-browser

方式 2：从源码构建

git clone https://github.com/yan5xu/bb-browser.git
cd bb-browser
pnpm install
pnpm build

加载 Chrome 扩展

必须步骤：CLI 需要配合 Chrome 扩展使用。

1. 打开 Chrome，访问 chrome://extensions/
2. 开启「开发者模式」（右上角开关）
3. 点击「加载已解压的扩展程序」
4. 选择扩展目录：
   • npm 安装：node_modules/bb-browser/extension/
   • 源码构建：packages/extension/dist/
5. 确认扩展已启用

使用

1. 启动 Daemon

# 前台启动（查看日志）
bb-browser daemon

# 或使用别名
bb-browser start

2. 基本操作

# 打开网页
bb-browser open https://example.com

# 获取页面快照（可交互元素）
bb-browser snapshot -i

# 输出示例：
# - link "Learn more" [ref=0]
# - button "Submit" [ref=1]
# - textbox "Search" [ref=2]

# 点击元素
bb-browser click @0

# 填充输入框
bb-browser fill @2 "search query"

# 按键
bb-browser press Enter

3. 完整命令列表

| 命令 | 说明 | 示例 | |------|------|------| | open <url> | 打开 URL | bb-browser open https://x.com | | snapshot | 获取页面快照 | bb-browser snapshot -i | | click <ref> | 点击元素 | bb-browser click @5 | | hover <ref> | 悬停元素 | bb-browser hover @3 | | fill <ref> <text> | 填充输入框（清空后填入） | bb-browser fill @2 "hello" | | type <ref> <text> | 逐字符输入（追加） | bb-browser type @2 " world" | | check <ref> | 勾选复选框 | bb-browser check @7 | | uncheck <ref> | 取消勾选 | bb-browser uncheck @7 | | select <ref> <val> | 下拉框选择 | bb-browser select @4 "option1" | | eval "<js>" | 执行 JavaScript | bb-browser eval "document.title" | | get text <ref> | 获取元素文本 | bb-browser get text @5 | | get url | 获取当前 URL | bb-browser get url | | get title | 获取页面标题 | bb-browser get title | | screenshot [path] | 截图 | bb-browser screenshot ./shot.png | | wait <ms\|@ref> | 等待时间或元素 | bb-browser wait 2000 | | press <key> | 按键 | bb-browser press Enter | | scroll <dir> [px] | 滚动 | bb-browser scroll down 500 | | back | 后退 | bb-browser back | | forward | 前进 | bb-browser forward | | refresh | 刷新 | bb-browser refresh | | close | 关闭标签页 | bb-browser close |

4. 标签页管理

# 列出所有标签页
bb-browser tab

# 新建标签页
bb-browser tab new https://google.com

# 切换到第 2 个标签页
bb-browser tab 2

# 关闭当前标签页
bb-browser tab close

5. iframe 支持

# 切换到 iframe（通过选择器）
bb-browser frame "#iframe-id"
bb-browser frame "[name='content']"

# 返回主 frame
bb-browser frame main

6. 对话框处理

# 接受 alert/confirm
bb-browser dialog accept

# 接受 prompt 并输入文本
bb-browser dialog accept "input text"

# 拒绝对话框
bb-browser dialog dismiss

7. 网络监控

# 查看网络请求
bb-browser network requests

# 按关键词过滤
bb-browser network requests api

# 拦截并阻止请求
bb-browser network route "*ads*" --abort

# Mock 响应
bb-browser network route "/api/user" --body '{"name":"test"}'

# 移除拦截规则
bb-browser network unroute

# 清空请求记录
bb-browser network clear

8. 调试

# 查看控制台消息
bb-browser console

# 清空控制台
bb-browser console --clear

# 查看 JS 错误
bb-browser errors

# 清空错误记录
bb-browser errors --clear

9. JSON 输出

所有命令支持 --json 参数，方便程序解析：

bb-browser snapshot -i --json
# {"success":true,"data":{"snapshot":"...","refs":{...}}}

bb-browser get url --json
# {"success":true,"data":"https://example.com"}

CDP 开发模式

以 CDP 调试模式启动 Chrome，支持 reload 命令热重载扩展：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile

# 然后加载扩展，之后可以热重载
bb-browser reload

项目结构

bb-browser/
├── packages/
│   ├── cli/          # CLI 工具
│   ├── daemon/       # HTTP Daemon（CLI 与扩展的桥梁）
│   ├── extension/    # Chrome 扩展
│   └── shared/       # 共享类型
└── README.md

技术栈

• CLI: TypeScript, Commander.js
• Daemon: Node.js HTTP Server, SSE
• Extension: Chrome Manifest V3, chrome.debugger API
• 构建: pnpm, Turbo, Vite, tsup

License

MIT