agent-browser CLI 入門：快照、ref 與工作階段

使用 agent-browser 時，先打開頁面，讀取交互快照，按快照里的 ref 操作，再核對頁面結果。如果頁面已變化，下一次通過 ref 操作前應重新獲取快照。@e3 這樣的數字引用只在當前瀏覽器狀態中指向控制項，單看數字無法知道它對應哪個按鈕。

有用戶問，依靠 ref 的流程在頻繁更新 DOM 的單頁應用中是否可靠。另一位用戶建議驗證失敗是否可見、能否重現。下面的練習分別記錄這兩件事。 r/ClaudeAI · r/AI_Agents

CLI 與工作階段怎麼配合

CLI 把命令發給後台進程，因此多條命令可以接著使用運行中的瀏覽器。每條命令都指定同一個 --session，讓一個任務在同一工作階段內繼續。快照描述當前分頁；分頁決定操作哪張頁面，工作階段決定命令共享哪一份瀏覽器狀態。

工作階段文件 · Tabbit 與 agent-browser 對比 · 瀏覽器 Agent · 瀏覽器自動化

打開練習頁並讀快照

使用已安裝的 agent-browser 與已設定的瀏覽器，具體安裝方式看官方文件。可在本地保存練習頁並通過本機回送地址提供，也可使用站內練習頁。先讀快照中的標題和按鈕名稱。輸出里寫 ref=e2 時，點擊命令使用 @e2。

官方安裝 · 快照文件 · 打開練習頁

安全運行練習

練習是無賬號的普通 HTML。將它保存為 fixture.html，放到沒有其他文件的目錄里，在另一個終端運行 HTTP 命令。確認頁面標題後再用示例 URL。若打開站內練習頁，把命令中的本機回送 URL 換成該地址。

python3 -m http.server 4173 --bind 127.0.0.1

agent-browser --session refs-demo-a open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-a snapshot -i

只讀下一步需要的頁面信息

選擇控制項時從 snapshot -i 開始。如果下一步依賴說明文字或錯誤提示，就讀取完整快照或直接查狀態。過濾結果沒顯示的文字可能仍在頁面上。頁面有重復按鈕時，可先核對容器，再限制快照範圍。

重現舊 ref 失效

點擊替換操作區的按鈕。URL 沒變，但原來的按鈕已經移除。本次 0.41.2 使用舊 @e3 返回退出碼 1，並提示找不到原按鈕。重新讀取狀態仍是 Panel B ready，說明預期動作沒有發生。

agent-browser --session refs-demo-a click @e2
agent-browser --session refs-demo-a get text '#status'
agent-browser --session refs-demo-a click @e3

Panel B ready
✗ Could not locate element with role=button name=Use original action

重新獲取快照並核對結果

新快照給 Use revised action 分配了 @e5，點擊後讀到 Panel B selected。用 0.26.0 重跑時，新快照把同一個數字 @e3 分配給了替換後的按鈕。每次都先看角色和名稱。版本和頁面不同，ref 數字也可能不同。

agent-browser --session refs-demo-a snapshot -i
agent-browser --session refs-demo-a click @e5
agent-browser --session refs-demo-a get text '#status'

區分三類證據

第一條回傳結果說明點擊被接受並改變了面板。錯誤回傳結果說明舊名稱查找失敗。最後一次狀態讀取說明重新觀察後完成了另一個動作。這三種結果分別記錄，排查時把快照和狀態一起保留。

當前實現會保留哪些引用

當前快照文件指出，同一文件內仍存在的 DOM 元素可以保留 ref。節點被替換時，在文件規定的條件下，工具可以按相同角色和名稱找唯一匹配。本例完全移除了舊按鈕名稱，所以這條路徑找不到目標。如果頁面上有多個同名按鈕，先重新觀察並加上區域上下文。

給獨立任務分配不同工作階段

按任務命名，例如 refs-demo-a 和 refs-demo-b。實測在獨立臨時瀏覽器設定中用第二個工作階段打開同一 URL，它顯示 Panel A ready，第一工作階段仍顯示 Panel B selected。持久狀態還要看瀏覽器設定。兩個客戶端接入同一個外部瀏覽器時，單靠工作階段名不能證明身份隔離。

agent-browser --session refs-demo-b open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-b get text '#status'
agent-browser --session refs-demo-a get text '#status'

瀏覽器自動化 Agent · 瀏覽器 Agent 安全 · 接入現有瀏覽器

實驗用的瀏覽器

兩次實測均在 macOS 使用實際 Tabbit Browser Dev 可執行文件和獨立臨時設定。agent-browser 執行產品實驗，文章頁面另用 Tabbit CLI 驗收。這只是本次通過的一種設定，安裝請參照對應平台的官方文件。

選擇合適的隔離範圍

分頁選擇瀏覽器里的頁面，命名工作階段讓多條命令復用同一任務狀態，瀏覽器設定決定本地啓動時的數據存放位置。為了重復驗證，在單個工作階段中保持啓動設定一致，另一次運行用獨立臨時設定。當前 CLI 中更改啓動設定可能導致瀏覽器重啓。

結束工作階段並排查失敗

先核對結果再關閉對應工作階段。用 session list 確認還有哪些工作階段在運行，只關閉自己創建的工作階段。如果新 ref 仍失效，先核對 URL、分頁，再檢查角色、名稱、可見性。等待目標頁面狀態後再行動，不重復點擊過時引用。

agent-browser --session refs-demo-a close
agent-browser --session refs-demo-b close
agent-browser session list

首次任務驗收清單 · 排查瀏覽器錯誤

Secholar.L

Tabbit 成長與內容

Secholar.L 專注 AI 瀏覽器與 Agent 工作流的實測寫作,基於真實調研比較工具,引用可查證的一手來源。