ego-browser辅助函数API速查表：30个常用函数一次记全-平芜编程栈

ego-browser辅助函数API速查表：30个常用函数一次记全

【免费下载链接】ego-liteThe fastest browser for AI agents to run browser automation, built for sharing your logged-in browser state with your AI agents, like Codex or Claude Code, without disturbing you. Zero cost, zero config.项目地址: https://gitcode.com/GitHub_Trending/eg/ego-lite

ego-browser是 ego lite 浏览器为 AI Agent 提供的浏览器自动化命令行运行时，内置了 30 个高频辅助函数（helper functions），覆盖打开网页、点击输入、截图观察、任务空间管理等全部场景。本文按功能分类把这 30 个 ego-browser 辅助函数 API 整理成一张速查表，每个函数一句话讲清用途，帮你一次记全，随查随用。

一分钟认识 ego-browser

ego lite 是一款为「你 + AI Agent 并行使用」而设计的浏览器。你正常浏览网页，而 Codex、Claude Code 等 Agent 通过ego-browser在各自隔离的**任务空间（Task Space）**里运行自动化任务，复用你的登录状态却互不干扰，零成本、零配置。

官方基准测试显示：在复杂浏览器自动化任务上，ego-browser 比传统 CLI 方案最快完成 2.5 倍，且 token 消耗大幅更少。

所有辅助函数都预加载在ego-browser nodejs <<'EOF' ... EOF的 heredoc 脚本中直接调用，无需任何 import。函数文档详见 SKILL.md。

30 个辅助函数总览

分类	函数
🗂 任务空间（7）	`listTaskSpacesuseOrCreateTaskSpaceclaimTaskSpacehandOffTaskSpacetakeOverTaskSpacewaitForAgentControlcompleteTaskSpace`
🧭 导航与标签（7）	`listTabsopenOrReuseTabcloseTabgotoAndWaitcurrentTabswitchTabpageInfo`
👁 页面观察（3）	`snapshotTextcaptureScreenshotdrainEvents`
🖱 鼠标与滚动（6）	`clickdoubleClickhoverdragMousescrollByscrollToBottomUntil`
⌨️ 键盘与输入（4）	`fillInputtypeTextpressKeydispatchKey`
📎 文件上传（1）	`uploadFile`
⏳ 等待（4）	`waitwaitForLoadwaitForElementwaitForNetworkIdle`
🌐 网络请求（2）	`serverFetchbrowserFetch`
🔧 进阶执行（2）	`jscdp`
📣 输出与帮助（2）	`cliLoghelp`

任务空间函数：给 Agent 分配独立工位

任务空间是 ego-browser 的核心设计：每个 Agent 任务拥有独立的标签组，但自动继承你的登录态。

函数	用途
`useOrCreateTaskSpace(name)`	⭐ 首选入口：按名称复用或新建任务空间，多轮任务都靠它续接
`listTaskSpaces()`	列出所有任务空间及其归属状态
`claimTaskSpace(id)`	认领一个属于你的空间（如用户交还后），所有权转给 Agent
`handOffTaskSpace()`	需要登录/验证码时，把控制权交还给你
`takeOverTaskSpace()`	你确认「继续」后，Agent 重新拿回控制权
`waitForAgentControl(id)`	只读轮询，等待交还后的控制权（不会抢占）
`completeTaskSpace(name, { keep })`	任务收尾：`keep:false`关闭空间，`keep:true`保留页面给你

💡最佳实践：每个 heredoc 轮次开头都调用useOrCreateTaskSpace(task.id)复用同一空间；任务结束务必completeTaskSpace收摊。

导航与标签函数：打开页面不迷路

函数	用途
`openOrReuseTab(url, { wait })`	⭐ 打开或复用指定 URL 的标签页，最常用的入口
`listTabs()`	查看当前空间所有标签页
`switchTab(targetId)`	切换到指定标签页
`currentTab()`	获取当前活动标签页
`gotoAndWait(url)`	在当前标签页内导航并等待加载完成
`closeTab(target?)`	关闭指定标签页，省略参数则关当前页
`pageInfo()`	返回当前页`{ url, title, w, h, sx, sy, pw, ph }`，页面有弹窗时返回`{ dialog }`

页面观察函数：让 Agent「看见」网页

函数	用途
`snapshotText()`	⭐ 核心函数：生成全页语义快照，带`[ref=N, loc=...]`标注，是后续点击/填表的地基
`captureScreenshot()`	截取当前页面截图，视觉工作流（Canvas、富文本编辑器）必备
`drainEvents()`	消费页面产生的异步事件队列（导航、网络事件）

鼠标与滚动函数：像人一样操作

这四个元素函数都接受统一的定位方式：CSS 选择器、xpath=...、快照里的@N编号或loc=...稳定定位值，也可传坐标[x, y]。

函数	用途
`click(target)`	单击元素中心或坐标，支持`{ label: '描述' }`触发高亮动画
`doubleClick(target)`	双击，常用于打开应用、选中文字
`hover(target)`	悬停，用于展开隐藏菜单
`dragMouse([from, to])`	拖拽，处理卡片、滑块类交互
`scrollBy(distance)`	DOM 级滚动指定距离
`scrollToBottomUntil(cond, opts)`	无限滚动利器：滚动直到条件成立（如文章数量达标）

键盘与输入函数：填表单三件套

函数	用途
`fillInput(target, value)`	⭐ 直接填充输入框值，表单场景首选
`typeText(text)`	逐字键入，触发完整的键盘事件
`pressKey(key)`	按下按键，如`Enter`、`Tab`
`dispatchKey(type, key, init)`	派发底层按键事件，处理特殊场景

文件、等待与网络：三个实用小组

📎 文件上传

uploadFile(selector, "/abs/path.pdf")— 给文件输入框指定本地文件，一步完成。

⏳ 等待四兄弟（参数单位是秒，不是毫秒！）

wait(seconds)— 固定等待
waitForLoad()— 等待页面加载完成
waitForElement(target)— 等待指定元素出现
waitForNetworkIdle()— 等待网络空闲，防「内容没加载完就操作」

🌐 网络请求双子星

serverFetch(url, opts)— 从 Node 端发请求，绕开页面环境
browserFetch(url, opts)— 从当前浏览器上下文发请求，自动携带 cookie 与登录态

进阶与输出：js、cdp 和 cliLog

函数	用途
`js(codeString)`	在浏览器页面内执行 JS 并返回结果，本质是`Runtime.evaluate`；注意返回值是真实对象，不要再`JSON.parse`
`cdp(method, params)`	调用任意 CDP 协议方法，如`Page.handleJavaScriptDialog`处理弹窗，是函数的「万能后门」
`cliLog(value)`	打印到终端，heredoc 内唯一的输出通道，所有结果必须经过它
`help(name)`	查询任意辅助函数用法，如`cliLog(help('click'))`，内置文档不迷路

5 个避坑提醒，少走弯路

⏱单位陷阱：wait(...)与timeout都是秒；只有名字以Ms结尾的参数才是毫秒。
🎯@N 引用短命：@N只对最近一次snapshotText()有效，长期引用请用快照里的loc=...稳定值。
🔄操作后必验证：点击、填表后再次snapshotText()或captureScreenshot()确认成功，别想当然。
🧵js() 与 heredoc 分工：导航、等待、cliLog写在脚本主体；document、window、页面选择器才放进js(...)里。
📐视口为 0 先修再动：pageInfo()报w: 0或h: 0时，先切换真实标签或重载，再执行坐标操作。