SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbb-browser

bb-browser

General & other

View repository

Updated 10-16 01:33

About this skill

bb-browser - Information Retrieval and Browser Automation

Core Value

Through the browser + the user's logged-in session, you can retrieve:

  • Public-domain information: any public web page, search results, news and information
  • Private-domain information: internal systems, enterprise applications, post-login pages, personal account data

It can also perform browser operations on behalf of the user: form filling, button clicking, data extraction, screenshot saving, and batch operations.

It runs in the user's real browser, reuses already logged-in accounts, and does not trigger anti-scraping detection.

Quick Start

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

Site System — Turn Any Website into a Command-Line API

The site system is a core feature of bb-browser. Through adapters, it turns website functionality into a CLI, covering 36+ platforms.

# 常用命令
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"    # 论文搜索

The adapter automatically handles tab management (finding a tab matching the domain or creating a new one), and automatically detects login errors and prompts.

For detailed usage and the complete list of 36 platforms: see references/site-system.md To create a custom adapter: see references/adapter-development.md

fetch — curl with logged-in session

Execute fetch in the browser context, automatically carrying cookies and the logged-in session.

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）

Automatic domain routing: absolute paths automatically find a matching tab or create a new one; relative paths use the current tab.

For detailed usage: see references/fetch-and-network.md

Tab Management Guidelines

After operations are complete, you must close the tabs you opened yourself.

# 单 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 打开

Core Workflow

  1. open Open the page
  2. snapshot -i View operable elements (returns @ref)
  3. Use @ref to perform operations (click, fill, etc.)
  4. After the page changes, run snapshot -i
  5. After the task is complete, close close the tab

Command Quick Reference

Navigation

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

Snapshot

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

Element Interaction

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

Retrieve Information

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

Tab Management

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

Screenshot

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

Wait

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

JavaScript

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

Frame Switching

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

Dialog Handling

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

Network and Debugging

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                             # 查看录制状态

For detailed advanced usage of network: see references/fetch-and-network.md

Global Options

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

Ref Usage Instructions

The @ref returned by snapshot is a temporary identifier for an element:

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

Note:

  • After page navigation, refs become invalid, and you need to run snapshot again
  • After dynamic content loads, you need to run snapshot again
  • Ref format:@1, @2, @3...

For detailed instructions: see references/snapshot-refs.md

Concurrent Operations

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

Information Extraction vs Page Operations

Choose different methods according to the purpose:

Extracting page content (use eval)

When you need to extract long text such as articles or body text, use eval to retrieve it directly:

# 微信公众号文章
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')"

Some websites have deeply nested DOM, making snapshot output verbose;eval directly extracting text is more efficient.

Operating page elements (use snapshot -i)

When you need to click, fill, or select, use snapshot -i to retrieve interactive elements:

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 Only show interactive elements, filtering out a large amount of irrelevant content.

MCP Integration

bb-browser provides an MCP server that can be integrated with AI tools such as Claude Code / Cursor:

# 启动 MCP server
bb-browser --mcp

Configuration example (Claude Code / Cursor):

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

Common Task Examples

Form Filling

bb-browser open https://example.com/form
bb-browser snapshot -i
bb-browser fill @1 "张三"
bb-browser fill @2 "zhangsan@example.com"
bb-browser click @3
bb-browser wait 2000
bb-browser close

Information Extraction

bb-browser open https://example.com/dashboard
bb-browser snapshot -i
bb-browser get text @5
bb-browser screenshot report.png
bb-browser close

Batch Operations

for url in "url1" "url2" "url3"; do
  bb-browser open "$url"
  bb-browser snapshot -i --json
  bb-browser close
done

In-Depth Documentation

Documentation Description
references/site-system.md Complete guide to the Site system: 35 platform list, command usage, automatic tab management
references/adapter-development.md Adapter development guide: API reverse engineering, three-tier complexity, metadata format
references/fetch-and-network.md Advanced Fetch and Network features: requests with login state, request interception and mock
references/snapshot-refs.md Ref lifecycle, best practices, common issues