browser

瀏覽器自動化

使用 browse CLI 搭配 Claude 自動化瀏覽器操作。

安裝檢查

在執行任何瀏覽器指令前，確認 CLI 已可用：

which browse || npm install -g browse

環境選擇（本機 vs 遠端）

CLI 支援每個指令明確指定環境旗標。若未指定，當 BROWSERBASE_API_KEY 已設定時，下一個工作階段預設使用 Browserbase，否則使用本機。

本機模式

• browse open <url> --local 啟動一個乾淨隔離的本機瀏覽器
• browse open <url> --auto-connect 附加到已執行中的可除錯 Chrome；若無可除錯 Chrome 則使用 --local
• browse open <url> --cdp <port|url> 附加到特定 CDP 目標
• 最適合：開發、localhost、信任的網站及可重複執行的測試

遠端模式（Browserbase）

• browse open <url> --remote 啟動 Browserbase 工作階段
• 若未指定本機旗標，當 BROWSERBASE_API_KEY 已設定時，Browserbase 也是預設值
• 提供：Browserbase Identity、驗證瀏覽器、自動 CAPTCHA 解決、住宅代理、工作階段持久化
• 使用遠端模式時機： 目標網站有機器人偵測、CAPTCHA、IP 速率限制、Cloudflare 保護，或需要特定地理區域存取
• 在 https://browserbase.com/settings 取得憑證

何時選擇哪種模式

• 可重複的本機測試 / 乾淨狀態：browse open <url> --local
• 重複使用本機登入/cookie：browse open <url> --auto-connect
• 簡單瀏覽（文件、維基、公開 API）：本機模式即可
• 受保護網站（登入牆、CAPTCHA、反爬蟲）：使用遠端模式
• 若本機模式因機器人偵測或存取被拒而失敗：切換至遠端模式

指令

大多數驅動程式指令在 daemon 啟動後，可於本機、遠端及 CDP 工作階段中運作。

導航

browse open <url>                        # 前往 URL
browse open <url> --local                # 在乾淨的本機瀏覽器中前往 URL
browse open <url> --remote               # 在 Browserbase 工作階段中前往 URL
browse reload                            # 重新載入目前頁面
browse back                              # 返回上一頁
browse forward                           # 前進下一頁

頁面狀態（優先使用 snapshot 而非 screenshot）

browse snapshot                          # 取得無障礙樹與元素參考（快速、結構化）
browse screenshot --path <path>          # 擷取視覺截圖（較慢，使用 vision tokens）
browse get url                           # 取得目前 URL
browse get title                         # 取得頁面標題
browse get text <selector>               # 取得文字內容（使用 "body" 取得所有文字）
browse get html <selector>               # 取得元素的 HTML 內容
browse get markdown [selector]           # 將頁面內容轉為 markdown（預設為 body）
browse get value <selector>              # 取得表單欄位值

預設使用 browse snapshot 了解頁面狀態 — 它會回傳無障礙樹及元素參考，可用於互動。僅在需要視覺上下文（版面、圖片、除錯）時才使用 browse screenshot。

互動

browse click <ref>                       # 點擊 snapshot 中的元素參考（例如 @0-5）
browse type <text>                       # 在焦點元素中輸入文字
browse fill <selector> <value>           # 填寫輸入欄位；若需按 Enter 則加上 --press-enter
browse select <selector> <values...>     # 選擇下拉選項
browse upload <selector> <files...>      # 上傳檔案至 <input type="file">
browse press <key>                       # 按下按鍵（Enter、Tab、Escape、Cmd+A 等）
browse mouse drag <fromX> <fromY> <toX> <toY>  # 從一點拖曳至另一點
browse mouse scroll <x> <y> <deltaX> <deltaY>  # 在指定座標滾動
browse highlight <selector>              # 在頁面上高亮元素
browse is visible <selector>             # 檢查元素是否可見
browse is checked <selector>             # 檢查元素是否已勾選
browse wait <type> [arg]                 # 等待：load、selector、timeout

CDP 事件串流

browse cdp <url|port>                    # 從任何目標串流 CDP 事件為 NDJSON 格式
browse cdp 9222                          # 附加到連接埠 9222 的本機 Chrome
browse cdp ws://localhost:9222/devtools/browser/...  # 完整 WebSocket URL
browse cdp <url> --domain Network        # 僅 Network 事件
browse cdp <url> --domain Network --domain Console  # 多個領域
browse cdp <url> --pretty                # 人類可讀輸出
browse cdp <url> > events.jsonl          # 輸出至檔案
browse cdp <url> | jq '.method'          # 使用 jq 過濾

cdp 指令直接連接到任何 Chrome DevTools Protocol 目標並串流事件。它不使用 daemon — 是一個獨立的長時間執行程序。按 Ctrl+C 停止。預設領域：Network、Console、Runtime、Log、Page。

工作階段管理

browse stop                              # 停止瀏覽器 daemon
browse status                            # 檢查 daemon 狀態及解析模式
browse tab list                          # 列出所有開啟的分頁
browse tab switch <index-or-target-id>   # 切換至指定索引或目標 ID 的分頁
browse tab close [index-or-target-id]    # 關閉分頁

典型工作流程

若環境重要，請在第一個瀏覽器指令加上 --local、--remote、--auto-connect 或 --cdp <port|url>。

1. browse open <url> --local 或 browse open <url> --remote — 導航至頁面
2. browse snapshot — 讀取無障礙樹以了解頁面結構並取得元素參考
3. browse click <ref> / browse type <text> / browse fill <selector> <value> — 使用 snapshot 的參考進行互動
4. browse snapshot — 確認操作成功
5. 視需要重複步驟 3-4
6. browse stop — 完成後關閉瀏覽器

快速範例

browse open https://example.com
browse snapshot                          # 查看頁面結構 + 元素參考
browse click @0-5                        # 點擊參考為 0-5 的元素
browse get title
browse stop

模式比較

功能	本機	Browserbase
速度	較快	稍慢
設定	需要 Chrome	需要 API 金鑰
重複使用本機 cookie	使用 browse open <url> --auto-connect	不適用
驗證瀏覽器	否	是（Browserbase Verified browser via Identity）
CAPTCHA 解決	否	是（自動 reCAPTCHA/hCaptcha）
住宅代理	否	是（201 個國家，地理定位）
工作階段持久化	否	是（透過 context 持久化 cookie/驗證）
最適合	開發/簡單頁面	受保護網站、Browserbase Identity + Verified 存取、生產環境爬蟲

最佳實踐

1. 審慎選擇本機策略：使用 browse open <url> --local 取得乾淨狀態，browse open <url> --auto-connect 重複使用現有本機憑證，browse open <url> --remote 處理受保護網站
2. 互動前務必先執行 browse open
3. 使用 browse snapshot 檢查頁面狀態 — 快速且提供元素參考
4. 僅在需要視覺上下文時才截圖（版面檢查、圖片、除錯）
5. 使用 snapshot 的參考進行點擊/互動 — 例如 browse click @0-5
6. 完成後執行 browse stop 以清理瀏覽器工作階段並清除環境覆蓋

疑難排解

• "No active page"：執行 browse stop，然後檢查 browse status。若仍顯示執行中，使用 pkill -f "browse.*daemon" 終止殭屍 daemon，然後重試 browse open
• 找不到 Chrome：安裝 Chrome，若已有可除錯 Chrome 執行中則使用 browse open <url> --auto-connect，或切換至 browse open <url> --remote
• 操作失敗：執行 browse snapshot 查看可用元素及其參考
• Browserbase 失敗：確認 API 金鑰已設定

切換至遠端模式

當偵測到以下情況時切換至遠端：CAPTCHA（reCAPTCHA、hCaptcha、Turnstile）、機器人偵測頁面（"Checking your browser..."）、HTTP 403/429、應有內容的網站出現空白頁面，或使用者要求。

對於簡單網站（文件、維基、公開 API、localhost）則不需切換。

browse open <url> --local          # 乾淨隔離的本機瀏覽器
browse open <url> --auto-connect   # 附加至現有可除錯 Chrome
browse open <url> --remote         # Browserbase 工作階段

模式旗標在工作階段啟動時套用。執行 browse stop 後，下一次啟動將回歸基於環境變數的自動偵測。在 daemon 執行期間，可使用 browse status 檢查解析模式與目標。

詳細範例請參閱 EXAMPLES.md。
API 參考請參閱 REFERENCE.md。