日常瀏覽器與 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。
Create
Open
Observe
Act
Wait
Verify
Complete
「ego (lite) is a browser where you and your AI agents work in parallel.」
安裝 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.觀察、操作與 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 |
單一執行回合與可觀察完成狀態
下列規則整理自 repository 內的 skills/ego-browser/SKILL.md。目標是減少跨 command 狀態遺失，並以頁面 postcondition 而不是 action 本身判定完成。
一個 browser task 使用一個 invocation
在 heredoc 內編排 observation、action、wait、extraction 與 verification；只在外部控制或 process failure 時開新回合。
來源 · ego-browser/SKILL.md
優先使用最少狀態的可靠路徑
若穩定 URL 已直接編碼目標條件，可直接開啟並驗證；使用者要求測試互動時才操作頁面控制。
來源 · ego-browser/SKILL.md
已符合 postcondition 時停止重播
先做最小讀取確認現況；值已正確時不開啟 editor，也不重複執行等價 action。
來源 · ego-browser/SKILL.md
在 action 前註冊 wait
先建立 response、request 或 navigation promise，再 click 或 submit；timeout 後立即檢查所需狀態。
來源 · ego-browser/SKILL.md
使用穩定的語意 locator
結構未知時一次收集 controls 或 candidates，再在 JavaScript 內選擇；避免跨 command 猜測 selector。
來源 · ego-browser/SKILL.md
失敗後只做一次目標觀察
用觀察結果更換策略；不要重複近似 locator 或 command。
來源 · ego-browser/SKILL.md
同一 user goal 重用 task id
useOrCreate 後保存 task id；後續必要 command 使用相同 id 或精確相同名稱。
來源 · ego-browser/SKILL.md
targetId 只在當前回合使用
每次需要切換或關閉 tab 時重新呼叫 browser.listTabs()，並驗證搜尋結果存在。
來源 · ego-browser/SKILL.md
人工控制需要 handoff
登入、captcha 或 user-owned Space 是 hard stop。呼叫 handOff 後等待使用者明確確認，再接回控制。
來源 · ego-browser/SKILL.md
完成是獨立 lifecycle commit
先輸出全部 browser 證據；確認 postcondition 後再以無 page action 的 final invocation 呼叫 complete。
來源 · ego-browser/SKILL.md
搜尋、等待與結果驗證
下列示例依官方 composite pattern 組成 browser task。Agent 在同一 heredoc 內建立 Space、開頁、填寫欄位、預先註冊 response wait，最後讀回可觀察結果。
$ You ›
打開訂單頁，搜尋 pending，回報可見的結果列與目前 URL。
> 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
claude: Agent ›
瀏覽器工作已完成；所有 requested postconditions 已由輸出證明。
const result = await taskSpaces.complete(taskId, { keep: false })
if (!result.done) throw new Error(JSON.stringify(result))
ok: Task space completed after browser evidence review
「Emit final results with console.log(...).」
兩個 invocation 的責任
第一個 invocation 完成 browser observation、action 與 verification，並輸出 task id 與證據。若結果不完整，繼續使用原 task Space 修正。
第二個 invocation 只呼叫 taskSpaces.complete(...)，不再操作 page 或 browser。done 為 true 後才能把 task lifecycle 視為完成。
macOS 限制與人工接管規則
從單一頁面到可交接 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.」