Package Exports

bb-browser
bb-browser/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (bb-browser) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

bb-browser

让 AI Agent 用你的真实浏览器

你已经登录的 Gmail、Twitter、内部系统——Agent 直接能用。通过 chrome.debugger API 操作，绕过自动化指纹检测。

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

为什么不用 Playwright / Selenium

	Playwright / Selenium	bb-browser
浏览器环境	独立的无头浏览器	用户的真实浏览器
登录态	没有，需要手动登录	复用已有的 Cookies 和会话
自动化检测	容易被识别和拦截	`chrome.debugger` API，无指纹
内部系统	需要额外配置 VPN/代理	用户能访问的，它都能访问

两种使用方式

独立使用

作为 CLI 工具，任何 AI Agent 都可以直接调用：

bb-browser open https://example.com
bb-browser snapshot -i
bb-browser click @0
bb-browser fill @2 "search query"

接入 Epiral Agent

通过 Epiral CLI 的 Browser Bridge 接入 Epiral Agent，让 Agent 远程控制浏览器：

Epiral Agent → gRPC → Epiral CLI (Browser Bridge) → SSE → Chrome 扩展 → 浏览器

只需在 Chrome 扩展设置中将上游 URL 指向 Epiral CLI 的 SSE 端口即可。Agent 可以同时接入多个浏览器。

安装

npm 安装（推荐）

npm install -g bb-browser

从源码构建

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

加载 Chrome 扩展（必须）

打开 Chrome → chrome://extensions/
开启「开发者模式」
点击「加载已解压的扩展程序」
选择扩展目录：
- npm 安装：node_modules/bb-browser/extension/
- 源码构建：packages/extension/dist/

使用

启动 Daemon

bb-browser daemon    # 前台启动
bb-browser start     # 别名

基本操作

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

# 获取页面快照（可交互元素）
bb-browser snapshot -i
# 输出:
# - link "Learn more" [ref=0]
# - button "Submit" [ref=1]
# - textbox "Search" [ref=2]

# 通过 ref 操作元素
bb-browser click @0
bb-browser fill @2 "hello world"
bb-browser press Enter

命令速查

类别	命令	说明
导航	`open <url>`	打开 URL
	`back` / `forward` / `refresh`	导航操作
	`close`	关闭标签页
快照	`snapshot`	完整 DOM 树
	`snapshot -i`	只看可交互元素
交互	`click <ref>`	点击
	`fill <ref> <text>`	清空后填入
	`type <ref> <text>`	逐字符追加
	`hover <ref>`	悬停
	`press <key>`	按键
	`scroll <dir> [px]`	滚动
	`check` / `uncheck <ref>`	复选框
	`select <ref> <val>`	下拉框
信息	`get text <ref>`	元素文本
	`get url` / `get title`	页面信息
	`screenshot [path]`	截图
	`eval "<js>"`	执行 JavaScript
Tab	`tab`	列出标签页
	`tab new <url>`	新标签页
	`tab <n>`	切换标签页
	`tab close`	关闭标签页
Frame	`frame "<selector>"`	进入 iframe
	`frame main`	回到主 frame
对话框	`dialog accept [text]`	接受
	`dialog dismiss`	拒绝
网络	`network requests [filter]`	查看请求
	`network route "<pattern>" --abort`	拦截
	`network unroute`	取消拦截
调试	`console` / `errors`	控制台/错误
Daemon	`daemon` / `start` / `stop` / `status`	管理

JSON 输出

所有命令支持 --json 参数：

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

多 Tab 并发

每次 open 返回独立的 tabId，通过 --tab 参数隔离操作：

bb-browser open https://site-a.com    # → tabId: 123
bb-browser open https://site-b.com    # → tabId: 456
bb-browser snapshot -i --tab 123      # 操作 site-a
bb-browser click @0 --tab 456         # 操作 site-b

项目结构

bb-browser/
├── packages/
│   ├── cli/          # CLI 工具（参数解析、HTTP 客户端、Daemon 管理）
│   ├── daemon/       # HTTP Daemon（SSE 推送、请求-响应匹配）
│   ├── extension/    # Chrome 扩展（Manifest V3、chrome.debugger）
│   └── shared/       # 共享类型和协议定义
├── skills/           # AI Agent Skill 文档
├── dist/             # 构建产物（npm 发布）
└── extension/        # 构建好的扩展（npm 发布）

技术栈

层	技术
CLI	TypeScript，手写参数解析
Daemon	Node.js HTTP Server + SSE
Extension	Chrome Manifest V3 + `chrome.debugger` API
构建	pnpm monorepo + Turborepo + tsup + Vite

许可证

MIT