ego-browser

ego-browser

ego-browser 為 AI Agent 提供了一個可透過 CLI 存取的 Node.js 執行環境，並內建輔助函式（helpers）——包含 snapshotText、click、js、cdp 等。Agent 可直接在 JS 腳本中呼叫這些函式來觀察頁面、與 UI 互動、執行瀏覽器端的 JavaScript，並操作真實瀏覽器以完成任何網頁自動化任務。

如需了解設定、安裝或連線相關問題，請參閱 references/install.md。

請使用 Bash 工具，透過 ego-browser nodejs <<'EOF' ... EOF 的 heredoc 方式執行所有瀏覽器操作。請勿先將程式碼寫入 .js 檔案。

快速開始

ego-browser nodejs <<'EOF'
// 為整個使用者任務命名任務空間（task space），並在多次 heredoc 執行輪次中複用該空間。
const task = await useOrCreateTaskSpace('inspect example page')
cliLog('task space id: ' + task.id)

await openOrReuseTab('https://example.com', { wait: true, timeout: 20 })

cliLog(await snapshotText())
EOF

heredoc 的主體內容會作為 Node.js 腳本執行，用來控制選定的 ego-browser 任務空間。所有 ego-browser 輔助函式皆已預先載入至該腳本中。

常用輔助函式

• 任務空間（Task spaces）：listTaskSpaces, useOrCreateTaskSpace, claimTaskSpace, handOffTaskSpace, takeOverTaskSpace, waitForAgentControl, completeTaskSpace
• 導覽 / 狀態（Navigation / state）：listTabs, openOrReuseTab, closeTab, gotoAndWait, currentTab, switchTab, gotoUrl, pageInfo, ensureRealTab
• 頁面觀察（Observation）：snapshotText, captureScreenshot, drainEvents
• 捲動 / 滑鼠（Scroll / mouse）：scrollBy, scrollToBottomUntil, scroll, click, doubleClick, hover, dragMouse
• 鍵盤與輸入（Keyboard & input）：typeText, fillInput, pressKey, dispatchKey
• 檔案（File）：uploadFile
• 等待（Wait）：wait, waitForLoad, waitForElement, waitForNetworkIdle
• 請求擷取（Fetch）：serverFetch, browserFetch
• CDP / 程式碼執行（CDP / evaluate）：js, cdp
• 輸出（Output）：cliLog, help

注意事項：

• cliLog(value) — 印出內容至終端機；這是 heredoc 內部唯一的輸出機制，所有最終結果都必須透過它輸出。
• await pageInfo() — 通常回傳 { url, title, w, h, sx, sy, pw, ph }；若此時開啟了原生瀏覽器對話框（dialog），則會因為頁面 JavaScript 被阻塞而改為回傳 { dialog: ... }。
• 若 await pageInfo() 回傳 { dialog: ... }，在執行頁面 JavaScript 之前，請先使用 await cdp('Page.handleJavaScriptDialog', { accept: true }) 或 accept: false 來處理該對話框。
• await ensureRealTab() — 必要時切換至已存在的非內部網頁分頁，並回傳該分頁物件；若不存在則回傳 null。此函式不會建立新分頁——若要建立分頁請使用 await openOrReuseTab(...)。
• await closeTab(target?) — 關閉指定的目標 ID / 分頁物件；若省略參數則關閉當前分頁。
• await drainEvents() — 清空並回傳由頁面產生的非同步事件佇列（導覽事件、網路事件等）。
• await serverFetch(url, options) — 從 Node 端發起請求並回傳回應主體（response body）。
• await browserFetch(url, options) — 從當前瀏覽器頁面情境（context）發起請求並回傳回應主體。
• help(name) — 印出指定輔助函式的使用說明，例如 cliLog(help('click'))。

任務空間（Task spaces）

任務空間是 ego-browser 為 AI Agent 提供的一種獨立隔離的瀏覽情境（context）。每個任務空間都擁有各自獨立的分頁集，但預設會直接繼承當前使用者的登入狀態，因此 Agent 可以在需要身分驗證的網站上操作，同時完全不會與使用者的日常瀏覽器視窗相衝突或干擾。

關閉某個任務空間中的所有分頁，即等同於關閉該任務空間。

一項任務通常需要經過多個 heredoc 輪次才能完成。由於 Node.js 執行環境在每次 heredoc 結束後就會退出且不保留任何狀態，因此一般運作中的 heredoc 開頭都應明確呼叫 useOrCreateTaskSpace(nameOrId) 來複用同一個空間——這樣才能跨輪次持續操作並重用分頁。唯一的例外是在交接（handoff）後恢復控制：一旦使用者確認「繼續」（透過 Ask 按鈕或在聊天中），下一個 heredoc 的開頭應改為呼叫 takeOverTaskSpace(nameOrId)。

nameOrId 可以是任務空間的名稱、數字 ID，或是全數字的字串 ID。字串型別會優先比對 name/taskId，若無匹配且為純數字字串則退回比對數字 ID。數值型別則僅會比對現有的數字 ID；若找不到匹配的 ID，useOrCreateTaskSpace 會直接報錯失敗而不會建立新空間。

建立新任務空間時，請根據使用者當前目標給予簡短名稱。對於後續追問、修正、細化、二次確認及結果驗證，即使先前認為任務已完成，也應持續複用該任務空間。只有當使用者明確開啟另一個全新且不相關的目標時，才選擇建立新的任務空間。在後續輪次中，建議優先使用 useOrCreateTaskSpace 回傳的數字 id（例如 task.id）來恢復已知任務，以避免名稱衝突。

針對相同使用者目標的任何後續操作——包括繼續執行、修正、重試、驗證、處理使用者回報的問題，或是執行 completeTaskSpace(..., { keep: true }) 之後的後續工作——只要原本的任務空間仍存在，都應優先恢復該空間。切勿為同一個目標建立新的任務空間，除非使用者明確要求開啟新空間、發起了無關的新目標，或經檢查後發現原空間已無法使用。若確實需要建立新空間，請說明原因。

在取得使用者明確確認後，若要從現有由使用者持有（user-owned）、非作用中（inactive）或未分配的任務空間繼續工作，請使用 await listTaskSpaces() 找出該空間，呼叫 await claimTaskSpace(id) 取得所有權並選取它，接著在執行操作前使用 await listTabs() 與 await switchTab(targetId) 選取確切的分頁。

所有權政策（Ownership policy）——每個任務空間皆具備 ownership: 'agent' | 'agentDelegatedToUser' | 'user' 狀態；輔助函式對使用者持有的空間處理方式有所不同：

輔助函式（Helper）	當目標任務空間為使用者所有（user-owned）時
switchTaskSpace	拋出異常（throws）——僅限 Agent 所有之空間
claimTaskSpace	宣告所有權（將所有權轉移給 Agent）並將其選取
handOffTaskSpace	跳過——回傳 { done: false, skipped: 'user-owned' }
completeTaskSpace(…, { keep: true })	跳過——回傳 { done: false, skipped: 'user-owned' }
completeTaskSpace(…, { keep: false })	宣告所有權後直接關閉
takeOverTaskSpace / waitForAgentControl	不檢查所有權

handOffTaskSpace 與 completeTaskSpace 只有在操作實際完成時才會回傳 { done: true }。在向使用者說明交接或清理已完成前，請先檢查 done 狀態——如果結果為 skipped，通常代表你所指定目標的空間從未屬於你。

completeTaskSpace(nameOrId, { keep }) 必須單獨佔用最後一個專屬的 heredoc 執行，且只有在先前 heredoc 的輸出已確認任務確實完成後才能執行。 keep 為必填參數，且依政策預設為 false：除非有具體理由需要讓即時頁面保持可見，否則任務完成後一律關閉任務空間。

僅在以下情況使用 { keep: true }：使用者明確要求保持頁面開啟、任務需要在該特定頁面進行手動操作，或結果無法妥善以 URL、檔案、產物（artifact）或摘要呈現時。切勿僅因為曾造訪某頁面、建立過文件或使用了截圖進行驗證，就保持任務空間開啟。

當傳入可能建立新任務空間的字串時，該字串應真實反映任務意圖（例如 'search github issues'），請勿使用字面上的占位符。

若任務結束後需要保留任務空間，請僅保留需要展示給使用者的分頁。 對開啟的分頁數量保持基本留意即可——執行一次簡單的 (await listTabs()).length 就足夠，無需專門花費一整個輪次進行檢查。當臨時分頁（搜尋結果頁、交叉比對頁及其他一次性頁面）堆積時，請隨手關閉，而不是全部留到最後。當以 { keep: true } 結尾留給使用者時，請清理剩餘的臨時分頁，僅留下值得展示的頁面。可使用 await closeTab(targetId) 關閉單一分頁（targetId 來自 listTabs() 或 openOrReuseTab 的回傳值）。

控制權交接（Control handoff）

在任何時間點，任務空間的控制權僅能由一方（Agent 或使用者）持有。當使用者持有控制權時，Agent 發起的任何瀏覽器操作都會失敗並提示 "user is controlling" 訊息——請勿重試，請依循以下步驟恢復控制。

"user is controlling" 錯誤代表整個任務必須強制停下——這並非可以繞過的障礙。這代表使用者已主動收回瀏覽器控制權，通常是因為當前的處理方式出現偏差。尊重此狀況才是正確的處理方式；若仍強行推進目標反而屬於失敗行為。你此時唯一能做的是詢問使用者並等待指令。

出現 "inactive"（非作用中）、"not assigned to an agent"（未分配給 Agent）或類似的任務空間錯誤時，同樣屬於強制停下並需遵守相同確認流程。請務必在取得使用者明確確認後才恢復執行，並以 await claimTaskSpace(id) 開頭。

交接給使用者（Handing off）：當任務需要使用者介入（例如登入、驗證碼、手動確認）時，請呼叫 await handOffTaskSpace([nameOrId]) 將控制權移交給使用者，並明確告知使用者需要進行的操作。若省略 nameOrId，將使用當前選定的任務空間；建議跨 heredoc 輪次傳遞 task.id 以避免歧義。

重新取得控制權（Regaining control）：僅在使用者明確確認後才能重新接管控制權——例如透過 Ask（平台提示按鈕/選項，如「繼續」與「結束任務」）或是聊天中的「繼續」訊息。接著開啟新的 heredoc 並以 await takeOverTaskSpace([nameOrId]) 開頭恢復執行；若使用者選擇結束，則呼叫 await completeTaskSpace(nameOrId, { keep }) 收尾。切勿自行呼叫 takeOverTaskSpace 強行搶回控制權——該函式不會檢查所有權，會直接從使用者手中奪走瀏覽器控制權。

使用者意外接管（Unexpected takeover）：使用者可隨時透過瀏覽器 GUI 主動接管——效果等同於 Agent 呼叫了 handOffTaskSpace。請勿重試失敗的操作，也不要自動重新接管；請提示上述 Ask 選項（繼續 / 結束），並僅在使用者選擇「繼續」時才恢復執行。

await waitForAgentControl(nameOrId) 是一個唯讀的阻塞式輪詢（它絕不會主動接管控制權）；僅用於在當前 heredoc 內部等待由你主動發起的交接。

捲動 / 滑鼠（Scroll / mouse）

// DOM 捲動
await scrollBy(900)
await scrollToBottomUntil(
  async () => await js(String.raw`document.querySelectorAll('article').length`) >= 20,
  { step: 900, wait: 1, maxSteps: 20 }
)

// 真實滾輪事件
await scroll({ dy: 900 })

元素目標輔助函式（如 click、doubleClick、hover、dragMouse、fillInput、uploadFile 及 waitForElement）支援相同的選擇器/參照語法：原始 CSS、xpath=...、@N / ref=N，以及來自 snapshotText() 的 loc=... 值（loc=css:...、loc=role:...、loc=href:...）。@N 參照僅適用於 ego-browser 輔助函式，並非 document.querySelector(...) 內合法的選擇器。

click、doubleClick、hover 及 dragMouse 共用上述目標格式。座標單位為 CSS