ego lite 新手教程

1 这是什么

ego lite（ego lite） 是 citrolabs/ego-lite 开源项目背后的一套「人和 AI Agent 共用的浏览器」方案。官方一句话定义："The fastest browser for AI agents to run browser automation"——但不是又一个自动化框架，而是一个从设计之初就让你和 Agent 一起用的真实浏览器。

一句话分清三个容易混淆的名字，这决定你理解整个项目：

2 为什么需要它

在它之前，"让 Agent 帮我开网页操作"基本靠三类凑合办法，每类都卡在一个痛点：

第二个关键设计是代码式（code-base）而非 CLI 式（command-base）：ego-browser 暴露给 Agent 的是可直接调用的 JS 函数。Agent 把多步任务写成一段脚本一次执行，而不是陷入「调两条命令 → 看结果 → 再调两条命令」的往返循环——这正是它声称比传统 CLI 自动化更快、token 更省的根因（见第 11 节基准）。

3 核心流程

一次典型的 ego lite 浏览器任务是这样的——你完全不碰浏览器，Agent 在自己的 Space 里走完：

4 安装

ego lite 目前只在 macOS 上运行（Windows / Linux 在路线图）。挑你顺手的路径装，每一条都会把 ego-browser 技能装进你机器上各个 Agent 的技能目录。

三种路径对应的做法，细节如下。App 直装：

# Apple Silicon / Intel 任选其一，点击下载后打开即装
open https://cdn.ego.app/setup/macos/arm64/egolite-Y7MbxKIuhzFB.dmg   # 或 x64 版

只装 skill（App 首跑任务时会提示你装）：

npx skills add citrolabs/ego-lite

第一次跑浏览器任务前，确认 ego-browser 命令存在（找不到多半是 ~/.local/bin 不在 PATH）：

command -v ego-browser
# 若找不到，临时补进 PATH 再试
export PATH="$HOME/.local/bin:$PATH"
command -v ego-browser

5 环境自检

装完 ego lite 且完成一次首次引导后，跑一个最小的 heredoc 验证运行时就绪：

ego-browser nodejs <<'EOF'
console.log('ego-browser ready')
EOF
# 打印出 ego-browser ready 即说明环境 OK

6 第一次实战

最简单的方式：把下面这句话粘给任何 Agent CLI（Codex / Claude Code / Cursor…），让它自己装并跑通：

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.

或者你已经装好，自己在终端里用 ego-browser nodejs 的 heredoc 手动跑第一个任务。注意不要把脚本先写进 .js 文件再执行，直接喂给 heredoc：

ego-browser nodejs <<'EOF'
// 给整段任务命名一个 Space，后续轮次复用它
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

第 6 节演示会告诉你发生了什么：

一段真实点儿的操作，用 @N ref 点击 + 填表 + 截图验证：

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('login check')
await openOrReuseTab('https://github.com', { wait: true })

// snapshotText 会给每个元素标 [ref=N, loc=...]，@N 只在最近一次快照内有效
const snap = await snapshotText()
cliLog(snap)

// 用快照里的 ref 点击、填表
await click('@21', { label: 'check login status' })
await fillInput('input[name="q"]', 'ego lite')
await pressKey('Enter')

// 语义工作流怀疑不准时，用截图核对
await captureScreenshot('/tmp/search-result.png')
cliLog('done')
EOF

7 产物结构

仓库里值得认识的目录与文件（理解了它，才知道「开源的到底哪几层」）：

8 日常怎么用

ego-browser 通过 ego-browser nodejs <<'EOF' 喂 Node 脚本，helper 全部预加载进脚本作用域。常用 helper 按用途分组：

三种工作流，先选再动手

9 进阶玩法

9.1 Space 是多任务并行的工作区

每个 Space 是一个隔离浏览上下文，默认继承你的登录态。你可以同时开多个：Claude Code 在 10 个 Space 里并行补 10 条线索、Codex 在另外 5 个 Space 里并行抓 5 个竞品站——它们互不干扰、也偷不走你的前台标签页，鼠标停在原地。

Node 运行时每次 heredoc 结束就退出、不留状态，所以多轮任务每轮开头都用 useOrCreateTaskSpace(nameOrId) 复用同一个 Space；优先用返回的 task.id（数字）跨轮次续接，避免名字撞车。

9.2 控制权交接：人和 Agent 随时切换

Space 有归属模型（agent / agentDelegatedToUser / user），任意时刻只有一方握着控制权。任务需要你介入（登录、验证码、手动确认）时，Agent 调 handOffTaskSpace() 把控制权交给你并告诉你该做什么；你确认「继续」后它才用 takeOverTaskSpace() 拿回。你在浏览器 GUI 里也能随时接管——等于手动触发一次 handoff。

9.3 站点经验包（Learnings）让 Agent 越用越快

skills/ego-browser/learnings/<site>/ 把对某网站的成功操作沉淀成「站点技能」——它负责记住"这个站怎么登录、哪个选择器稳定、抓这个数据该走哪条路"，避免每轮都从头试错。官方路线图把它扩展成通用的「经验积累」：把每次成功动作提炼成可复用工具/工作流，同类任务声称最高快 5×。

9.4 本地模式无 GUI 也能验证 helper

# 直接在本机跑 helper bundle（不需要真实浏览器，调试 helper 本身用）
node dist/out/index.js <<'JS'
console.log(await page.info())
JS

# 覆盖加载的 skill 工作区（站点学习默认来自相邻的 skills/ego-browser）
EGO_BROWSER_AGENT_WORKSPACE=/path/to/skill ego-browser nodejs <<'EOF'
console.log(await site.skills())
EOF

10 不止于此

名字叫"ego lite 浏览器"，但它能待的场景不止"自己开个页面让 Agent 点一点"：

11 性能与成本

官方基准拿 ego lite 对 Vercel 的 agent-browser，在四个复杂浏览器自动化任务上对比。核心结论（数据出自项目 README，条件：四个复杂任务、同为 agent 驱动的浏览器自动化）：

12 FAQ / 踩坑

13 合规与版权

开源边界先说清：仓库内容按 MIT 许可发布（含 ego-browser 技能、Node helper 运行时、文档与基准）；ego lite 浏览器本体是闭源、但免费下载的独立产物。

仓库开发层面的规矩（对贡献者）：main 分支只接受走 review 的 PR（连机器人定时推送都被规则集拒了，star 图因此挪到了独立分支）。想改代码自己用，从 package/ego-browser 走常规 Node 开发流（npm ci → npm run build → npm test）。

14 参考链接