bb-browser - 信息获取与浏览器自动化

核心价值

通过浏览器 + 用户登录态，可以获取：

• 公域信息：任意公开网页、搜索结果、新闻资讯
• 私域信息：内部系统、企业应用、登录后页面、个人账户数据

还可以代替用户执行浏览器操作：表单填写、按钮点击、数据提取、截图保存、批量操作。

运行在用户真实浏览器中，复用已登录的账号，不触发反爬检测。

快速开始

bb-browser open <url>        # 打开页面（新 tab）
bb-browser snapshot -i       # 获取可交互元素
bb-browser click @5          # 点击元素
bb-browser fill @3 "text"    # 填写输入框
bb-browser close             # 完成后关闭 tab

Site 系统 — 把任何网站变成命令行 API

site 系统是 bb-browser 的核心特性，通过 adapter 将网站功能 CLI 化，覆盖 36+ 平台。

# 常用命令
bb-browser site list                          # 列出所有 adapter
bb-browser site search <query>                # 搜索 adapter
bb-browser site <name> [args...]              # 运行 adapter
bb-browser site update                        # 更新社区 adapter 库

# 使用示例
bb-browser site twitter/search "Claude Code"  # 搜索推文
bb-browser site zhihu/hot                     # 知乎热榜
bb-browser site github/repo owner/repo        # 仓库信息
bb-browser site youtube/transcript <video_id> # 获取字幕
bb-browser site reddit/thread <url>           # 帖子详情
bb-browser site eastmoney/stock "茅台"         # 股票查询
bb-browser site weibo/hot                     # 微博热搜
bb-browser site arxiv/search "transformer"    # 论文搜索

adapter 自动处理 tab 管理（查找匹配域名的 tab 或新建），自动检测登录错误并提示。

详细用法和 36 平台完整列表：参见 references/site-system.md 创建自定义 adapter：参见 references/adapter-development.md

fetch — 带登录态的 curl

在浏览器上下文中执行 fetch，自动携带 Cookie 和登录态。

bb-browser fetch <url>                                    # GET 请求
bb-browser fetch <url> --method POST --body '{"k":"v"}'   # POST 请求
bb-browser fetch <url> --headers '{"Auth":"Bearer xxx"}'  # 自定义请求头
bb-browser fetch <url> --output data.json                 # 保存到文件
bb-browser fetch /api/me.json                             # 相对路径（用当前 tab 的 origin）

自动域名路由：绝对路径自动查找匹配 tab 或新建；相对路径使用当前 tab。

详细用法：参见 references/fetch-and-network.md

Tab 管理规范

操作完成后必须关闭自己打开的 tab。

# 单 tab 场景
bb-browser open https://example.com    # 打开新 tab
bb-browser snapshot -i
bb-browser click @5
bb-browser close                        # 完成后关闭

# 多 tab 场景
bb-browser open https://site-a.com     # tabId: 123
bb-browser open https://site-b.com     # tabId: 456
# ... 操作 ...
bb-browser tab close                    # 关闭当前 tab
bb-browser tab close                    # 关闭剩余 tab

# 指定 tab 操作
bb-browser open https://example.com --tab current  # 在当前 tab 打开（不新建）
bb-browser open https://example.com --tab 123      # 在指定 tabId 打开

核心工作流

1. open 打开页面
2. snapshot -i 查看可操作元素（返回 @ref）
3. 用 @ref 执行操作（click, fill, etc.）
4. 页面变化后重新 snapshot -i
5. 任务完成后 close 关闭 tab

命令速查

导航

bb-browser open <url>                # 打开 URL（新 tab）
bb-browser open <url> --tab current  # 在当前 tab 打开
bb-browser back                      # 后退
bb-browser forward                   # 前进
bb-browser refresh                   # 刷新
bb-browser close                     # 关闭当前 tab

快照

bb-browser snapshot             # 完整页面结构
bb-browser snapshot -i          # 只显示可交互元素（推荐）
bb-browser snapshot -c          # 移除空结构节点
bb-browser snapshot -d 3        # 限制树深度为 3 层
bb-browser snapshot -s ".main"  # 限定 CSS 选择器范围
bb-browser snapshot --json      # JSON 格式输出
# 选项可组合：bb-browser snapshot -i -c -d 5

元素交互

bb-browser click @5             # 点击
bb-browser hover @5             # 悬停
bb-browser fill @3 "text"       # 清空并填写
bb-browser type @3 "text"       # 追加输入（不清空）
bb-browser check @7             # 勾选复选框
bb-browser uncheck @7           # 取消勾选
bb-browser select @4 "option"   # 下拉选择
bb-browser press Enter          # 按键
bb-browser press Control+a      # 组合键
bb-browser scroll down          # 向下滚动（默认 300px）
bb-browser scroll up 500        # 向上滚动 500px

获取信息

bb-browser get text @5          # 获取元素文本
bb-browser get url              # 获取当前 URL
bb-browser get title            # 获取页面标题

Tab 管理

bb-browser tab                  # 列出所有 tab
bb-browser tab new [url]        # 新建 tab
bb-browser tab 2                # 切换到第 2 个 tab（按 index）
bb-browser tab select --id 123  # 切换到指定 tabId 的 tab
bb-browser tab close            # 关闭当前 tab
bb-browser tab close 3          # 关闭第 3 个 tab（按 index）
bb-browser tab close --id 123   # 关闭指定 tabId 的 tab

截图

bb-browser screenshot           # 截图（自动保存）
bb-browser screenshot path.png  # 截图到指定路径

等待

bb-browser wait 2000            # 等待 2 秒
bb-browser wait @5              # 等待元素出现

JavaScript

bb-browser eval "document.title"              # 执行 JS
bb-browser eval "window.scrollTo(0, 1000)"    # 滚动到指定位置

Frame 切换

bb-browser frame "#iframe-id"   # 切换到 iframe
bb-browser frame main           # 返回主 frame

对话框处理

bb-browser dialog accept        # 确认对话框
bb-browser dialog dismiss       # 取消对话框
bb-browser dialog accept "text" # 确认并输入（prompt）

网络与调试

bb-browser network requests                        # 查看网络请求
bb-browser network requests "api" --with-body       # 过滤 + 完整请求/响应体
bb-browser network route "*analytics*" --abort      # 拦截并阻止请求
bb-browser network route "*/api/user" --body '{}'   # 拦截并 mock 响应
bb-browser network unroute                          # 移除所有拦截规则
bb-browser network clear                            # 清空请求记录
bb-browser console                                  # 查看控制台消息
bb-browser console --clear                          # 清空控制台
bb-browser errors                                   # 查看 JS 错误
bb-browser errors --clear                           # 清空错误记录
bb-browser trace start                              # 开始录制用户操作
bb-browser trace stop                               # 停止录制，输出事件列表
bb-browser trace status                             # 查看录制状态

详细的 network 高级用法：参见 references/fetch-and-network.md

全局选项

--json               # 以 JSON 格式输出（所有命令通用）
--tab <tabId>        # 指定操作的标签页 ID（几乎所有命令通用）
--mcp                # 启动 MCP server（用于 Claude Code / Cursor 等 AI 工具）

Ref 使用说明

snapshot 返回的 @ref 是元素的临时标识：

@1 [button] "提交"
@2 [input type="text"] placeholder="请输入姓名"
@3 [a] "查看详情"

注意：

• 页面导航后 ref 失效，需重新 snapshot
• 动态内容加载后需重新 snapshot
• ref 格式：@1, @2, @3...

详细说明：参见 references/snapshot-refs.md

并发操作

# 并发打开多个页面（各自独立 tab）
bb-browser open https://site-a.com &
bb-browser open https://site-b.com &
bb-browser open https://site-c.com &
wait
# 每个返回独立的 tabId，互不干扰

信息提取 vs 页面操作

根据目的选择不同的方法：

提取页面内容（用 eval）

当需要提取文章、正文等长文本时，用 eval 直接获取：

# 微信公众号文章
bb-browser eval "document.querySelector('#js_content').innerText"

# 知乎回答
bb-browser eval "document.querySelector('.RichContent-inner').innerText"

# 通用：获取页面主体文本
bb-browser eval "document.body.innerText.substring(0, 5000)"

# 获取所有链接
bb-browser eval "[...document.querySelectorAll('a')].map(a => a.href).join('\n')"

有些网站 DOM 嵌套很深，snapshot 输出冗长，eval 直接提取文本更高效。

操作页面元素（用 snapshot -i）

当需要点击、填写、选择时，用 snapshot -i 获取可交互元素：

bb-browser snapshot -i
# @1 [button] "登录"
# @2 [input] placeholder="用户名"
# @3 [input type="password"]

bb-browser fill @2 "username"
bb-browser fill @3 "password"
bb-browser click @1

-i 只显示可交互元素，过滤掉大量无关内容。

MCP 集成

bb-browser 提供 MCP server，可与 Claude Code / Cursor 等 AI 工具集成：

# 启动 MCP server
bb-browser --mcp

配置示例（Claude Code / Cursor）：

{
  "mcpServers": {
    "bb-browser": {
      "command": "npx",
      "args": ["-y", "bb-browser", "--mcp"]
    }
  }
}

常见任务示例

表单填写

bb-browser open https://example.com/form
bb-browser snapshot -i
bb-browser fill @1 "张三"
bb-browser fill @2 
how to use bb-browser
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use bb-browser on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add bb-browser
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/epiral/bb-browser --skill bb-browsercopy
The skills CLI fetches bb-browser from GitHub repository epiral/bb-browser and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/bb-browser
Reload or restart Cursor to activate bb-browser. Access the skill through slash commands (e.g., /bb-browser) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?