使用 agent-browser 進行瀏覽器自動化
此CLI透過CDP直接使用Chrome/Chromium。透過 npm i -g agent-browser、brew install agent-browser 或 cargo install agent-browser 安裝。執行 agent-browser install 以下載Chrome。系統會自動偵測現有的Chrome、Brave、Playwright和Puppeteer安裝。執行 agent-browser upgrade 以更新至最新版本。
核心工作流程
每次瀏覽器自動化均遵循此模式:
- 導航:
agent-browser open <url> - 快照:
agent-browser snapshot -i(取得元素參考,如@e1、@e2) - 互動:使用參考ID來點擊、填寫、選擇
- 重新快照:在導航或DOM變更後,取得新的參考ID
agent-browser open https://example.com/form
agent-browser snapshot -i
# 輸出:@e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait 2000
agent-browser snapshot -i # 檢查結果
命令串連
可以使用 && 在同一個shell呼叫中串連多個命令。瀏覽器會透過背景守護行程在命令之間持續存在,因此串連比單獨呼叫更安全且更有效率。
# 在一個呼叫中串連開啟 + 快照(開啟已經等待頁面載入)
agent-browser open https://example.com && agent-browser snapshot -i
# 串連多個互動
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# 導航並擷取
agent-browser open https://example.com && agent-browser screenshot
何時串連: 當您不需要在繼續之前讀取中間命令的輸出時使用 &&(例如,開啟 + 等待 + 截圖)。當您需要先解析輸出時(例如,透過快照發現參考,然後使用這些參考進行互動),請單獨執行命令。
處理認證
在自動化需要登入的網站時,選擇最適合的方法:
選項 1:從使用者的瀏覽器匯入認證(一次性任務最快)
# 連接到使用者正在執行的Chrome(他們已經登入)
agent-browser --auto-connect state save ./auth.json
# 使用該認證狀態
agent-browser --state ./auth.json open https://app.example.com/dashboard
狀態檔案包含明文的工作階段令牌——請加入 .gitignore 並在不再需要時刪除。設定 AGENT_BROWSER_ENCRYPTION_KEY 以進行靜態加密。
選項 2:Chrome設定檔重複使用(零設定)
# 列出可用的Chrome設定檔
agent-browser profiles
# 重複使用使用者現有的Chrome登入狀態
agent-browser --profile Default open https://gmail.com
選項 3:持久化設定檔(適用於重複性任務)
# 第一次執行:手動或透過自動化登入
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 填寫憑證,提交 ...
# 所有後續執行:已認證
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
選項 4:工作階段名稱(自動儲存/還原Cookie + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... 登入流程 ...
agent-browser close # 狀態自動儲存
# 下次執行:狀態自動還原
agent-browser --session-name myapp open https://app.example.com/dashboard
選項 5:認證保管庫(憑證加密儲存,依名稱登入)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login 會使用 load 導航,然後等待登入表單選擇器出現後再填寫/點擊,這對於延遲的SPA登入畫面更可靠。
選項 6:狀態檔案(手動儲存/載入)
# 登入後:
agent-browser state save ./auth.json
# 在未來的工作階段中:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
請參閱 references/authentication.md 了解OAuth、2FA、基於Cookie的認證和令牌重新整理模式。
基本命令
# 批次:對於2個或更多連續命令,請務必使用批次。命令依序執行。
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 導航
agent-browser open <url> # 導航(別名:goto, navigate)
agent-browser close # 關閉瀏覽器
agent-browser close --all # 關閉所有活躍工作階段
# 快照
agent-browser snapshot -i # 帶有參考的互動元素(建議使用)
agent-browser snapshot -i --urls # 包含連結的href URL
agent-browser snapshot -s "#selector" # 限定CSS選擇器範圍
# 互動(使用來自快照的@refs)
agent-browser click @e1 # 點擊元素
agent-browser click @e1 --new-tab # 點擊並在新分頁中開啟
agent-browser fill @e2 "text" # 清除並輸入文字
agent-browser type @e2 "text" # 不清除直接輸入文字
agent-browser select @e1 "option" # 選擇下拉選項
agent-browser check @e1 # 勾選核取方塊
agent-browser press Enter # 按下按鍵
agent-browser keyboard type "text" # 在當前焦點輸入文字(無選擇器)
agent-browser keyboard inserttext "text" # 插入文字但不觸發鍵盤事件
agent-browser scroll down 500 # 滾動頁面
agent-browser scroll down 500 --selector "div.content" # 在特定容器內滾動
# 取得資訊
agent-browser get text @e1 # 取得元素文字
agent-browser get url # 取得當前URL
agent-browser get title # 取得頁面標題
agent-browser get cdp-url # 取得CDP WebSocket URL
# 等待
agent-browser wait @e1 # 等待元素出現
agent-browser wait 2000 # 等待毫秒數
agent-browser wait --url "**/page" # 等待URL模式匹配
agent-browser wait --text "Welcome" # 等待文字出現(子字串比對)
agent-browser wait --load networkidle # 等待網路閒置(注意:請參閱陷阱)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # 等待文字消失
agent-browser wait "#spinner" --state hidden # 等待元素消失
# 下載
agent-browser download @e1 ./file.pdf # 點擊元素觸發下載
agent-browser wait --download ./output.zip # 等待任何下載完成
agent-browser --download-path ./downloads open <url> # 設定預設下載目錄
# 分頁管理
agent-browser tab list # 列出所有開啟的分頁
agent-browser tab new # 開啟空白新分頁
agent-browser tab new https://example.com # 在新分頁中開啟URL
agent-browser tab 2 # 按索引切換分頁(從0開始)
agent-browser tab close # 關閉當前分頁
agent-browser tab close 2 # 按索引關閉分頁
# 網路
agent-browser network requests # 檢視追蹤的請求
agent-browser network requests --type xhr,fetch # 按資源類型篩選
agent-browser network requests --method POST # 按HTTP方法篩選
agent-browser network requests --status 2xx # 按狀態碼篩選(200, 2xx, 400-499)
agent-browser network request <requestId> # 檢視完整請求/回應細節
agent-browser network route "**/api/*" --abort # 封鎖符合的請求
agent-browser network har start # 開始HAR錄製
agent-browser network har stop ./capture.har # 停止並儲存HAR檔案
# 視窗大小與裝置模擬
agent-browser set viewport 1920 1080 # 設定視窗大小(預設:1280x720)
agent-browser set viewport 1920 1080 2 # 2倍視網膜(相同CSS大小,更高解析度截圖)
agent-browser set device "iPhone 14" # 模擬裝置(視窗大小 + 使用者代理)
# 擷取
agent-browser screenshot # 截圖至暫存目錄
agent-browser screenshot --full # 全頁截圖
agent-browser screenshot --annotate # 帶有編號元素標籤的註解截圖
agent-browser screenshot --screenshot-dir ./shots # 儲存至自訂目錄
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # 儲存為PDF
# 即時預覽 / 串流
agent-browser stream enable # 在自動選擇的連接埠上啟動執行階段WebSocket串流
agent-browser stream enable --port 9223 # 繫結特定的localhost連接埠
agent-browser stream status # 檢查啟用狀態、連接埠、連線和螢幕投射
agent-browser stream disable # 停止執行階段串流並移除.stream元資料檔案
# 剪貼簿
agent-browser clipboard read # 從剪貼簿讀取文字
agent-browser clipboard write "Hello, World!" # 寫入文字至剪貼簿
agent-browser clipboard copy # 複製當前選取內容
agent-browser clipboard paste # 從剪貼簿貼上
# 對話框(alert, confirm, prompt, beforeunload)
# 預設情況下,alert和beforeunload對話框會自動接受,因此它們不會封鎖代理程式。
# confirm和prompt對話框仍需明確處理。
# 使用 --no-auto-dialog(或 AGENT_BROWSER_NO_AUTO_DIALOG=1)來停用自動處理。
agent-browser dialog accept # 接受對話框
agent-browser dialog accept "my input" # 接受提示對話框並附帶文字
agent-browser dialog dismiss # 關閉/取消對話框
agent-browser dialog status # 檢查對話框目前是否開啟
# 差異比較(比較頁面狀態)
agent-browser diff snapshot # 比較當前與上一次快照
agent-browser diff snapshot --baseline before.txt # 比較當前與已儲存檔案
agent-browser diff screenshot --baseline before.png # 視覺化像素差異
agent-browser diff url <url1> <url2> # 比較兩個頁面
agent-browser diff url <url1> <url2> --wait-until networkidle # 自訂等待策略
agent-browser diff url <url1> <url2> --selector "#main" # 限定元素範圍
# 聊天(AI自然語言控制)
agent-browser chat "open google.com and search for cats" # 單次指令
agent-browser chat # 互動式REPL模式
agent-browser -q chat "summarize this page" # 靜音模式(僅文字,無工具呼叫)
agent-browser -v chat "fill in the login form" # 詳細模式(顯示命令輸出)
agent-browser --model openai/gpt-4o chat "take a screenshot" # 覆寫模型
串流
每個工作階段都會在作業系統指定的連接埠上自動啟動一個WebSocket串流伺服器。使用 agent-browser stream status 查看綁定的連接埠和連線狀態。使用 stream disable 來關閉它,使用 stream enable --port <port> 在特定連接埠上重新啟用。
批次執行
在依序執行2個以上命令時,請務必使用 batch。Batch會依序執行命令,因此依賴性命令(例如先導航後截圖)可以正常運作。每個引號內的參數都是一個獨立的命令。
# 導航並取得快照
agent-browser batch "open https://example.com" "snapshot -i"
# 在一個呼叫中導航、快照和截圖
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# 點擊、等待,然後截圖
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 使用 --bail 在首次錯誤時停止
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
僅在需要讀取輸出才能決定下一個命令時,才使用單一命令(而非批次)。例如,您必須將 snapshot -i 作為單一命令執行,因為您需要讀取參考ID來決定點擊哪個元素。讀取快照後,再批次處理其餘步驟。
也支援使用標準輸入的模式以進行程式化使用:
echo '[['open','https://example.com'],['screenshot']]' | agent-browser batch --json
agent-browser batch --bail < commands.json
效率策略
這些模式可最小化工具呼叫次數和令牌用量。
使用 --urls 避免重新導航。 當您需要存取頁面上的連結時,請使用 snapshot -i --urls 預先取得所有href URL。然後直接 open 每個URL,而無需點擊參考ID並導航回來。
快照一次,多次操作。 從不對同一個頁面重新快照。從單次快照中提取所有需要的資訊(參考ID、URL、文字),然後批次處理剩餘的操作。
多頁面工作流程(例如「造訪N個網站並對每個網站截圖」):
# 1. 在一次呼叫中取得所有URL
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 讀取輸出以提取URL,然後直接造訪每個URL:
# 2. 每個目標網站使用一個批次
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"
這種方法使用4次工具呼叫,而非14次以上。切勿在每次造訪之間返回列表頁面。
常見模式
表單提交
# 導航並取得表單結構
agent-browser batch "open https://example.com/signup" "snapshot -i"
# 讀取快照輸出以識別表單參考ID,然後填寫並提交
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
使用認證保管庫進行認證(建議)
# 儲存憑證一次(使用 AGENT_BROWSER_ENCRYPTION_KEY 加密)
# 建議:透過stdin傳遞密碼以避免暴露於shell歷史記錄
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# 使用儲存的設定檔登入(LLM永遠看不到密碼)
agent-browser auth login github
# 列出/顯示/刪除設定檔
agent-browser auth list