Back to Details

bb-browser

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

bb-browser - Information Retrieval and Browser Automation

核心价值

Core Value

bb-browser 是一个强大的信息获取工具。
通过浏览器 + 用户登录态，可以获取：
  • 公域信息：任意公开网页、搜索结果、新闻资讯
  • 私域信息：内部系统、企业应用、登录后页面、个人账户数据
在此基础上，还可以代替用户执行浏览器操作：
  • 表单填写、按钮点击
  • 数据提取、截图保存
  • 批量操作、重复任务
为什么能做到？
  • 运行在用户真实浏览器中，复用已登录的账号
  • 不触发反爬检测，访问受保护的页面
  • 无需提供密码或 Cookie，直接使用现有登录态
bb-browser is a powerful information retrieval tool.
With browsers + user login states, you can obtain:
  • Public domain information: Any public web pages, search results, news and information
  • Private domain information: Internal systems, enterprise applications, post-login pages, personal account data
On this basis, it can also perform browser operations on behalf of users:
  • Form filling, button clicking
  • Data extraction, screenshot saving
  • Batch operations, repetitive tasks
Why can it do this?
  • Runs in the user's real browser, reusing logged-in accounts
  • Does not trigger anti-crawling detection, accessing protected pages
  • No need to provide passwords or Cookies, directly using existing login states

快速开始

Quick Start

bash
bb-browser open <url>        # 打开页面（新 tab）
bb-browser snapshot -i       # 获取可交互元素
bb-browser click @5          # 点击元素
bb-browser fill @3 "text"    # 填写输入框
bb-browser close             # 完成后关闭 tab
bash
bb-browser open <url>        # Open page (new tab)
bb-browser snapshot -i       # Get interactive elements
bb-browser click @5          # Click element
bb-browser fill @3 "text"    # Fill input box
bb-browser close             # Close tab after completion

Tab 管理规范

Tab Management Specifications

重要：操作完成后必须关闭自己打开的 tab
bash
undefined
Important: You must close the tabs you opened after completing operations
bash
undefined

单 tab 场景

Single tab scenario

bb-browser open https://example.com # 打开新 tab bb-browser snapshot -i bb-browser click @5 bb-browser close # 完成后关闭
bb-browser open https://example.com # Open new tab bb-browser snapshot -i bb-browser click @5 bb-browser close # Close after completion

多 tab 场景

Multiple tabs scenario

bb-browser open https://site-a.com # tabId: 123 bb-browser open https://site-b.com # tabId: 456
bb-browser open https://site-a.com # tabId: 123 bb-browser open https://site-b.com # tabId: 456

... 操作 ...

... operations ...

bb-browser tab close # 关闭当前 tab bb-browser tab close # 关闭剩余 tab
bb-browser tab close # Close current tab bb-browser tab close # Close remaining tab

指定 tab 操作

Specified tab operations

bb-browser open https://example.com --tab current # 在当前 tab 打开（不新建） bb-browser open https://example.com --tab 123 # 在指定 tabId 打开
undefined
bb-browser open https://example.com --tab current # Open in current tab (no new tab) bb-browser open https://example.com --tab 123 # Open in specified tabId
undefined

核心工作流

Core Workflow

  1. open
    打开页面
  2. snapshot -i
    查看可操作元素（返回 @ref）
  3. 用 
    @ref
    执行操作（click, fill, etc.）
  4. 页面变化后重新 
    snapshot -i
  5. 任务完成后 
    close
    关闭 tab
  1. open
    Open the page
  2. snapshot -i
    View operable elements (returns @ref)
  3. Use 
    @ref
    to perform operations (click, fill, etc.)
  4. Re-run 
    snapshot -i
    after page changes
  5. close
    the tab after task completion

命令速查

Command Quick Reference

导航

Navigation

bash
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
bash
bb-browser open <url>           # Open URL (new tab)
bb-browser open <url> --tab current  # Open in current tab
bb-browser back                 # Go back
bb-browser forward              # Go forward
bb-browser refresh              # Refresh
bb-browser close                # Close current tab

快照

Snapshot

bash
bb-browser snapshot             # 完整页面结构
bb-browser snapshot -i          # 只显示可交互元素（推荐）
bb-browser snapshot --json      # JSON 格式输出
bash
bb-browser snapshot             # Complete page structure
bb-browser snapshot -i          # Only display interactive elements (recommended)
bb-browser snapshot --json      # Output in JSON format

元素交互

Element Interaction

bash
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          # 向下滚动
bb-browser scroll up 500        # 向上滚动 500px
bash
bb-browser click @5             # Click
bb-browser hover @5             # Hover
bb-browser fill @3 "text"       # Clear and fill
bb-browser type @3 "text"       # Append input (no clear)
bb-browser check @7             # Check checkbox
bb-browser uncheck @7           # Uncheck checkbox
bb-browser select @4 "option"   # Dropdown selection
bb-browser press Enter          # Press key
bb-browser press Control+a      # Press key combination
bb-browser scroll down          # Scroll down
bb-browser scroll up 500        # Scroll up 500px

获取信息

Information Retrieval

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

Tab 管理

Tab Management

bash
bb-browser tab                  # 列出所有 tab
bb-browser tab new [url]        # 新建 tab
bb-browser tab 2                # 切换到第 2 个 tab
bb-browser tab close            # 关闭当前 tab
bb-browser tab close 3          # 关闭第 3 个 tab
bash
bb-browser tab                  # List all tabs
bb-browser tab new [url]        # Create new tab
bb-browser tab 2                # Switch to 2nd tab
bb-browser tab close            # Close current tab
bb-browser tab close 3          # Close 3rd tab

截图

Screenshot

bash
bb-browser screenshot           # 截图（自动保存）
bb-browser screenshot path.png  # 截图到指定路径
bash
bb-browser screenshot           # Screenshot (auto-save)
bb-browser screenshot path.png  # Screenshot to specified path

等待

Wait

bash
bb-browser wait 2000            # 等待 2 秒
bb-browser wait @5              # 等待元素出现
bash
bb-browser wait 2000            # Wait 2 seconds
bb-browser wait @5              # Wait for element to appear

JavaScript

JavaScript

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

Frame 切换

Frame Switching

bash
bb-browser frame "#iframe-id"   # 切换到 iframe
bb-browser frame main           # 返回主 frame
bash
bb-browser frame "#iframe-id"   # Switch to iframe
bb-browser frame main           # Return to main frame

对话框处理

Dialog Handling

bash
bb-browser dialog accept        # 确认对话框
bb-browser dialog dismiss       # 取消对话框
bb-browser dialog accept "text" # 确认并输入（prompt）
bash
bb-browser dialog accept        # Confirm dialog
bb-browser dialog dismiss       # Cancel dialog
bb-browser dialog accept "text" # Confirm and input (prompt)

调试

Debugging

bash
bb-browser network requests     # 查看网络请求
bb-browser console              # 查看控制台消息
bb-browser errors               # 查看 JS 错误
bb-browser trace start          # 开始录制用户操作
bb-browser trace stop           # 停止录制
bash
bb-browser network requests     # View network requests
bb-browser console              # View console messages
bb-browser errors               # View JS errors
bb-browser trace start          # Start recording user operations
bb-browser trace stop           # Stop recording

Ref 使用说明

Ref Usage Instructions

snapshot 返回的 
@ref
是元素的临时标识：
@1 [button] "提交"
@2 [input type="text"] placeholder="请输入姓名"
@3 [a] "查看详情"
注意：
  • 页面导航后 ref 失效，需重新 snapshot
  • 动态内容加载后需重新 snapshot
  • ref 格式：
    @1
    , 
    @2
    , 
    @3
    ...
The 
@ref
returned by snapshot is a temporary identifier for elements:
@1 [button] "Submit"
@2 [input type="text"] placeholder="Please enter name"
@3 [a] "View details"
Notes:
  • Ref becomes invalid after page navigation, need to re-run snapshot
  • Need to re-run snapshot after dynamic content loads
  • Ref format: 
    @1
    , 
    @2
    , 
    @3
    ...

并发操作

Concurrent Operations

bash
undefined
bash
undefined

并发打开多个页面（各自独立 tab）

Open multiple pages concurrently (each in independent tab)

bb-browser open https://site-a.com & bb-browser open https://site-b.com & bb-browser open https://site-c.com & wait
bb-browser open https://site-a.com & bb-browser open https://site-b.com & bb-browser open https://site-c.com & wait

每个返回独立的 tabId，互不干扰

Each returns independent tabId, no interference

undefined
undefined

JSON 输出

JSON Output

添加 
--json
获取结构化输出：
bash
bb-browser snapshot -i --json
bb-browser get text @5 --json
bb-browser open https://example.com --json
Add 
--json
to get structured output:
bash
bb-browser snapshot -i --json
bb-browser get text @5 --json
bb-browser open https://example.com --json

信息提取 vs 页面操作

Information Retrieval vs Page Operations

根据目的选择不同的方法：
Choose different methods based on your purpose:

提取页面内容（用 eval）

Extract Page Content (use eval)

当需要提取文章、正文等长文本时，用 
eval
直接获取：
bash
undefined
When you need to extract long text such as articles or main content, use 
eval
to get it directly:
bash
undefined

微信公众号文章

WeChat Official Account article

bb-browser eval "document.querySelector('#js_content').innerText"
bb-browser eval "document.querySelector('#js_content').innerText"

知乎回答

Zhihu answer

bb-browser eval "document.querySelector('.RichContent-inner').innerText"
bb-browser eval "document.querySelector('.RichContent-inner').innerText"

通用：获取页面主体文本

General: Get page main text

bb-browser eval "document.body.innerText.substring(0, 5000)"
bb-browser eval "document.body.innerText.substring(0, 5000)"

获取所有链接

Get all links

bb-browser eval "[...document.querySelectorAll('a')].map(a => a.href).join('\n')"

**为什么不用 snapshot？** 
有些网站（如微信公众号）DOM 结构嵌套很深，snapshot 输出会非常冗长。`eval` 直接提取文本更高效。
bb-browser eval "[...document.querySelectorAll('a')].map(a => a.href).join('\n')"

**Why not use snapshot?** 
Some websites (such as WeChat Official Accounts) have deeply nested DOM structures, so snapshot output will be very lengthy. `eval` directly extracts text more efficiently.

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

Operate Page Elements (use snapshot -i)

当需要点击、填写、选择时，用 
snapshot -i
获取可交互元素：
bash
bb-browser snapshot -i
When you need to click, fill, or select, use 
snapshot -i
to get interactive elements:
bash
bb-browser snapshot -i

@1 [button] "登录"

@1 [button] "Login"

@2 [input] placeholder="用户名"

@2 [input] placeholder="Username"

@3 [input type="password"]

@3 [input type="password"]

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

**`-i` 很重要**：只显示可交互元素，过滤掉大量无关内容。
bb-browser fill @2 "username" bb-browser fill @3 "password"
bb-browser click @1

**`-i` is important**: Only displays interactive elements, filtering out a large amount of irrelevant content.

常见任务示例

Common Task Examples

表单填写

Form Filling

bash
bb-browser open https://example.com/form
bb-browser snapshot -i
bash
bb-browser open https://example.com/form
bb-browser snapshot -i

@1 [input] placeholder="姓名"

@1 [input] placeholder="Name"

@2 [input] placeholder="邮箱"

@2 [input] placeholder="Email"

@3 [button] "提交"

@3 [button] "Submit"

bb-browser fill @1 "张三" bb-browser fill @2 "zhangsan@example.com" bb-browser click @3 bb-browser wait 2000 bb-browser close
undefined
bb-browser fill @1 "Zhang San" bb-browser fill @2 "zhangsan@example.com" bb-browser click @3 bb-browser wait 2000 bb-browser close
undefined

信息提取

Information Retrieval

bash
bb-browser open https://example.com/dashboard
bb-browser snapshot -i
bb-browser get text @5              # 获取特定元素文本
bb-browser screenshot report.png    # 截图保存
bb-browser close
bash
bb-browser open https://example.com/dashboard
bb-browser snapshot -i
bb-browser get text @5              # Get specific element text
bb-browser screenshot report.png    # Save screenshot
bb-browser close

批量操作

Batch Operations

bash
undefined
bash
undefined

打开多个页面提取信息

Open multiple pages to extract information

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

深入文档

In-Depth Documentation

文档说明
references/snapshot-refs.mdRef 生命周期、最佳实践、常见问题
DocumentDescription
references/snapshot-refs.mdRef lifecycle, best practices, common issues