實戰手冊 · Field Manual 2026 夏季號
github.com/citrolabs/ego-lite · 1,230 ★
e
GitHub Field Manual · Browser / AI Agent

人與 AI Agent,
共用一個瀏覽器的
分離工作空間

ego lite 是可由外部 coding agent 控制的 Chromium-based macOS 瀏覽器。每個 agent task 在獨立 Space 執行，並可重用使用者的登入狀態；ego-browser skill 以 Node.js runtime 暴露 page、browser 與 taskSpaces 介面。

1.2k
GitHub Stars
6
核心頁面工具
macOS
目前支援平台
MIT
Repo 開源授權
01
產品與 Skill 邊界

日常瀏覽器與
Agent 執行層

ego lite 提供人類使用者與 AI agent 共用的 Chromium-based browser。人類維持自己的 tabs；agent task 在隔離 Space 中執行，並可沿用使用者已存在的 login state。

ego-browser 是 agent 與 browser 之間的 skill/runtime 層。它預載 Playwright-style 的 page、page.locator(...)、browser 與 taskSpaces，並提供 fetch 與 cdp escape hatch。

Repository 內容採 MIT License；ego lite browser 本身是另外下載的免費 app。官方 README 目前將 Windows 與 Linux 列在 roadmap。

ego-browser task lifecycle
Create→ Open→ Observe→ Act→ Wait→ Verify→ Complete
「ego (lite) is a browser where you and your AI agents work in parallel.」
— citrolabs/ego-lite README
02
macOS 安裝

安裝 Skill 與
ego lite App

只安裝 ego-browser skill 時，使用 README 提供的 skills CLI 指令。第一次執行 browser task 時，skill 會引導安裝 ego lite app。

npx skills add citrolabs/ego-lite

交由 coding agent 安裝

也可把 repository URL 與官方 install reference 路徑交給 agent。Agent 會執行 macOS 安裝 script，開啟 app 後等待使用者完成 onboarding。

Set up ego lite for me: https://github.com/citrolabs/ego-lite Read skills/ego-browser/references/install.md and follow the steps to install ego lite.
平台與驗證:官方 install reference 目前只支援 macOS。完成 GUI onboarding 後執行 command -v ego-browser；通過條件是 shell 可找到指令，且最小 Node.js heredoc 能輸出結果。
03
ego-browser runtime

觀察、操作與
Task Space 生命週期

ego-browser nodejs 會預載 browser automation facade。單一 Bash invocation 內完成可預測的 observation、action、wait、extraction 與 verification；task 完成則使用獨立 invocation 提交 lifecycle。

Space · 01
taskSpaces.useOrCreate
工作空間選取
以相同名稱或 id 建立或重用單一 user goal 的隔離 Space。
Navigate · 02
browser.openOrReuseTab
頁籤開啟
開啟或重用指定 URL，並依 wait 與 timeout 等待初始載入。
Observe · 03
page.snapshot
語意快照
取得頁面可操作語意樹；每次新 snapshot 會重建 @N reference map。
Locate · 04
page.getByRole
語意定位
以 heading、button、link 等 accessible role 定位單一或一組元素。
Locate · 05
page.locator
DOM 查詢
支援 chaining、filter、集合讀取、form、keyboard、upload 與 element evaluation。
Act · 06
fill / click
表單與控制操作
填寫欄位、點擊控制，並以 resulting page state 判定結果。
Wait · 07
page.waitForResponse
網路同步
在觸發 action 前註冊 request、response 或 navigation wait。
Tabs · 08
browser.listTabs
頁籤發現
列出目前 Space 的 tabs，並在同一 invocation 內選取短效 targetId。
Tabs · 09
browser.switchTab
頁籤切換
切到已驗證的 targetId，再讀取 URL 與頁面狀態。
Visual · 10
page.screenshot
視覺證據
擷取頁面或 locator 畫面，用於 canvas、virtualized UI 與視覺 QA。
Network · 11
fetch.server / browser
Node 與頁面請求
fetch.server 由 Node 發送；fetch.browser 使用目前頁面 origin。
Complete · 12
taskSpaces.complete
生命週期提交
在獨立 final invocation 完成原始 task id，檢查 done 後回報。

依頁面狀態選互動路徑

頁面狀態 起始路徑 驗證方式
一般 DOM 與可存取控制 snapshot + semantic locator 讀回 URL、文字或 control state
Canvas、地圖或 AX-poor UI screenshot + mouse / keyboard 新 screenshot 或 export/readback
大量元素或資料抽取 locator.evaluateAll 結構化結果與 bounded count
facade 未涵蓋的 browser protocol cdp 目標 postcondition
04
官方執行規則

單一執行回合與
可觀察完成狀態

下列規則整理自 repository 內的 skills/ego-browser/SKILL.md。目標是減少跨 command 狀態遺失，並以頁面 postcondition 而不是 action 本身判定完成。

TIP 01

一個 browser task 使用一個 invocation

在 heredoc 內編排 observation、action、wait、extraction 與 verification；只在外部控制或 process failure 時開新回合。

來源 · ego-browser/SKILL.md
TIP 02

優先使用最少狀態的可靠路徑

若穩定 URL 已直接編碼目標條件，可直接開啟並驗證；使用者要求測試互動時才操作頁面控制。

來源 · ego-browser/SKILL.md
TIP 03

已符合 postcondition 時停止重播

先做最小讀取確認現況；值已正確時不開啟 editor，也不重複執行等價 action。

來源 · ego-browser/SKILL.md
TIP 04

在 action 前註冊 wait

先建立 response、request 或 navigation promise，再 click 或 submit；timeout 後立即檢查所需狀態。

來源 · ego-browser/SKILL.md
TIP 05

使用穩定的語意 locator

結構未知時一次收集 controls 或 candidates，再在 JavaScript 內選擇；避免跨 command 猜測 selector。

來源 · ego-browser/SKILL.md
TIP 06

失敗後只做一次目標觀察

用觀察結果更換策略；不要重複近似 locator 或 command。

來源 · ego-browser/SKILL.md
TIP 07

同一 user goal 重用 task id

useOrCreate 後保存 task id；後續必要 command 使用相同 id 或精確相同名稱。

來源 · ego-browser/SKILL.md
TIP 08

targetId 只在當前回合使用

每次需要切換或關閉 tab 時重新呼叫 browser.listTabs()，並驗證搜尋結果存在。

來源 · ego-browser/SKILL.md
TIP 09

人工控制需要 handoff

登入、captcha 或 user-owned Space 是 hard stop。呼叫 handOff 後等待使用者明確確認，再接回控制。

來源 · ego-browser/SKILL.md
TIP 10

完成是獨立 lifecycle commit

先輸出全部 browser 證據；確認 postcondition 後再以無 page action 的 final invocation 呼叫 complete。

來源 · ego-browser/SKILL.md
05
單一執行回合

搜尋、等待與
結果驗證

下列示例依官方 composite pattern 組成 browser task。Agent 在同一 heredoc 內建立 Space、開頁、填寫欄位、預先註冊 response wait，最後讀回可觀察結果。

~/projects/ops · ego-browser nodejs
You › 打開訂單頁，搜尋 pending，回報可見的結果列與目前 URL。
[starts one Bash invocation] ego-browser nodejs <<'EOF'
const task = await taskSpaces.useOrCreate('search orders') await browser.openOrReuseTab('https://example.com/orders', { wait: true, timeout: 20000, })
const responsePromise = page.waitForResponse( response => response.url().includes('/api/orders') && response.ok(), { timeout: 15000 }, )
await page.getByLabel('Search orders').fill('pending') await page.getByRole('button', { name: /search/i }).click() const response = await responsePromise
const rows = await page.locator('table tbody tr').allInnerTexts() if (!rows.length) throw new Error('No visible rows') const url = await page.url()
console.log(JSON.stringify({ taskSpaceId: task.id, status: response.status(), url, rows, }, null, 2)) EOF
[reviews output: task id, successful response, URL, visible rows]
Agent › 瀏覽器工作已完成；所有 requested postconditions 已由輸出證明。
[starts dedicated lifecycle invocation] const result = await taskSpaces.complete(taskId, { keep: false }) if (!result.done) throw new Error(JSON.stringify(result))
Task space completed after browser evidence review
「Emit final results with console.log(...).」
— ego-browser/SKILL.md

兩個 invocation 的責任

第一個 invocation 完成 browser observation、action 與 verification，並輸出 task id 與證據。若結果不完整，繼續使用原 task Space 修正。

第二個 invocation 只呼叫 taskSpaces.complete(...)，不再操作 page 或 browser。done 為 true 後才能把 task lifecycle 視為完成。

06
平台與控制邊界

macOS 限制與
人工接管規則

  • 目前 app 只支援 macOS。官方 README 將 Windows 與 Linux 列在 roadmap；repository 內的 install script 也會檢查 Darwin。
  • Skill 與 app 是兩個安裝層。npx skills add 可先安裝 skill；browser task 仍需要 ego lite app 與完成 onboarding。
  • Chrome 資料移轉是使用者選擇。首次啟動由 GUI 詢問是否匯入 login、cookies、extensions 與 bookmarks；Agent 必須等待使用者完成 onboarding。
  • User-controlled Space 是 hard stop。遇到 user controlling、inactive 或 not assigned error 時停止自動操作，取得使用者確認後才 claim 或 take over。
  • @N reference 不是持久 handle。每次 snapshot 都會重建 ref map；command 結束後重新 snapshot，或改用穩定 locator。
  • Wait timeout 可能回傳 falsy。waitForURL、waitForLoadState 與 locator wait 後必須檢查回傳值或直接驗證目標狀態。
  • Completion 不能代替驗證。結果非空、partial output、stalled page 或 fallback attempt 都不是完成證據。
  • Update notice 不在 task 中途處理。先完成或停止目前 browser task，再告知版本提示並另行取得升級授權。
07
進階路徑

從單一頁面到
可交接 Browser Task

熟悉單一頁面的 semantic route 後，再處理多 tab、iframe、visual fallback、人工 handoff 與 reusable learnings。每個擴充仍使用一個原始 task id，並保留明確完成證據。

進階玩法地圖

1. 建立 composite script。把可預測的抽取、選擇、navigation、wait 與 verification 放入同一 heredoc。

2. 管理多 tab。以 browser.listTabs() 找到目前 target，再於同一 invocation 切換、驗證與清理。

3. 加入 visual route。AX tree 無法表達 canvas 或虛擬化介面時，先 screenshot，再以 mouse／keyboard 操作並讀回結果。

4. 設計人工 handoff。登入或 captcha 前完成安全準備，呼叫 taskSpaces.handOff，並在使用者確認後恢復原 Space。

5. 保存 reusable learning。依 skill 的 learnings 結構保存已驗證的 site-specific route，避免把暫時 selector 當成持久契約。

最該讀的三份延伸閱讀

① README.md：產品定位、macOS quick start、Spaces 與官方比較。
② skills/ego-browser/SKILL.md：runtime map、execution rules 與 task lifecycle。
③ references/install.md：app 安裝、onboarding 與 PATH 驗證。

「Treat completion as a terminal commit.」
— ego-browser/SKILL.md