ego-browser

ego-browser

ego-browser 为 AI Agent 提供了可经 CLI 访问的 Node.js 运行时，内置了一系列辅助工具（Helpers）——包括 snapshotText、click、js、cdp 等。Agent 可直接在 JS 脚本中调用它们来观察页面、与 UI 交互、执行浏览器端 JavaScript，并驱动真实浏览器完成各类 Web 自动化任务。

如需了解安装配置或连接故障排查，请参阅 references/install.md。

请使用 Bash 工具，通过 ego-browser nodejs <<'EOF' ... EOF Heredoc 方式运行所有浏览器操作。不要先将代码写入 .js 文件。

快速开始

ego-browser nodejs <<'EOF'
// 为整个用户任务命名任务空间，随后在多次 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 辅助函数（helpers）均已预加载至该脚本上下文中。

常用辅助工具（Common helpers）

• 任务空间管理（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: ... }，必须先调用 await cdp('Page.handleJavaScriptDialog', { accept: true }) 或 accept: false 处理对话框，然后再执行页面 JavaScript。
• await ensureRealTab() —— 必要时切换到已存在的非内部页面标签页（tab）并返回该标签页对象；若不存在则返回 null。该函数不会新建标签页 —— 如需新建，请使用 await openOrReuseTab(...)。
• await closeTab(target?) —— 关闭指定的 target id / tab 对象；若省略参数则关闭当前标签页。
• await drainEvents() —— 消费并返回由页面产生的异步事件队列（如导航事件、网络请求事件等）。
• await serverFetch(url, options) —— 从 Node 端发起 HTTP 请求并返回响应体。
• await browserFetch(url, options) —— 从当前浏览器页面上下文发起请求并返回响应体。
• help(name) —— 打印指定 helper 的使用说明，例如 cliLog(help('click'))。

任务空间（Task spaces）

任务空间是 ego-browser 为 AI Agent 提供的隔离浏览上下文。每个任务空间都拥有独立的标签页集合，但默认继承当前用户的登录状态。因此 Agent 可以在受身份验证的网站上执行操作，而不会与用户的正常浏览器窗口产生冲突或干扰。

关闭某个任务空间内的所有标签页，等同于关闭该任务空间。

完成一个任务往往需要多轮 heredoc 操作。由于 Node.js 运行时在每次 heredoc 执行完毕后都会退出且不保留任何内存状态，因此常规的作业 heredoc 首行应当显式调用 useOrCreateTaskSpace(nameOrId) 来复用同一个空间 —— 这能让你跨多轮交互实现连续操作并复用标签页。唯二的例外是在控制权交接（handoff）后恢复操作：一旦用户通过确认（通过 Ask 组件或聊天消息）选择“继续”，下一轮 heredoc 应改用 takeOverTaskSpace(nameOrId) 开头。

nameOrId 可以是任务空间名称、数字 ID，或仅含数字的 ID 字符串。传入字符串时，优先匹配 name/taskId；若匹配不到且字符串纯数字，则回退为按数字 ID 匹配。传入数值（number）类型时，仅精确匹配已存在的数字 ID；若无对应 ID，useOrCreateTaskSpace 将直接报错失败，而不会新建空间。

在创建新任务空间时，请针对当前用户的具体目标使用简明扼要的名称。后续针对该目标的补充提问、纠错、细化、重新检查或结果校验，即使你之前认为任务已完成，也应继续复用该任务空间。只有在用户明确发起另一个完全无关的新目标时，才选择创建新的任务空间。在后续轮次中，推荐优先使用 useOrCreateTaskSpace 返回的数字 id（例如 task.id）来恢复已知任务，避免名称冲突。

对于针对同一用户目标的任何后续交互 —— 包括继续、纠错、重试、校验、用户反馈的问题，以及在执行 completeTaskSpace(..., { keep: true }) 后的后续工作 —— 如果原始任务空间仍然存在，请首先恢复原空间。除非用户要求创建全新空间、发起了无关的新目标，或者经检查发现原空间已不可用，否则切勿为同一目标创建新空间。如必须创建新空间，请明确说明原因。

在获得用户明确确认后，如需继续操作某个已存在、属于用户、未激活或未分配的任务空间，请先调用 await listTaskSpaces() 查找该空间，再调用 await claimTaskSpace(id) 夺取所有权并选中它，随后调用 await listTabs() 和 await switchTab(targetId) 选中具体的标签页后再开展操作。

所有权策略（Ownership policy） —— 每个任务空间都带有 ownership: 'agent' | 'agentDelegatedToUser' | 'user' 属性；辅助函数对用户所有的空间（user-owned）有特殊处理逻辑：

辅助函数	当目标空间属于用户（user-owned）时
switchTaskSpace	抛出异常 —— 仅支持 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 就足够了，无需专门花一轮 heredoc 去查询。当临时标签页（搜索结果页、交叉核对页及其他一次性页面）堆积时，应随时随地顺手关闭，而不是任由它们积攒到最后。若最终以 { keep: true } 结尾以留存页面给用户，请清理掉多余的临时标签页，仅保留值得展示给用户的页面。使用 await closeTab(targetId) 关闭单个标签页（targetId 来自 listTabs() 或 openOrReuseTab 的返回值）。

控制权交接（Control handoff）

在任何时刻，任务空间的控制权仅能由 Agent 或用户其中一方持有。当用户持有控制权时，Agent 尝试执行的任何浏览器操作都会报错“user is controlling” —— 切勿重试；请遵循以下步骤恢复。

“user is controlling”错误是对整个任务的硬性终止信号，而不是需要绕过的障碍。这代表用户主动接管了浏览器，通常是因为你当前的操作偏离了预想。尊重用户的接管才是正确的行为；强行推进目标反而是失败的做法。此时你唯一能做的就是询问用户并等待。

出现“inactive”、“not assigned to an 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