bb-browser

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 "zhangsan@example.com"
bb-browser click @3
bb-browser wait 2000
bb-browser close

資訊提取

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

批次操作

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

深入文件

文件	說明
references/site-system.md	Site 系統完整指南：35 平台列表、命令用法、自動 tab 管理
references/adapter-development.md	Adapter 開發指南：API 逆向、三層複雜度、元資料格式
references/fetch-and-network.md	Fetch 與 Network 進階功能：帶登入態請求、請求攔截與 mock
references/snapshot-refs.md	Ref 生命週期、最佳實踐、常見問題