Ego 任务空间浏览器

它解决的问题

AI Agent 在真实浏览器里干活时，通常面临两类麻烦：一是脚本只能操作干净环境里的 DOM，一旦遇到登录态、验证码或需要用户确认的页面就卡住；二是多个任务在同一浏览器上下文里互相踩踏，标签页和会话状态难以隔离。更麻烦的是，Agent 想自动干活，但用户也想随时接管，这中间的控制边界很难划定。ego-browser 想要解决的就是这个「真实浏览器里的任务隔离与控制交接」问题。

工作方式

ego-browser 通过一个 CLI 可访问的 Node.js 运行时，暴露一个真实的 Chromium 浏览器。它的 API 命名和调用方式参考了 Playwright，page.locator(...)、browser、taskSpaces 这几个入口用起来和 Playwright 类似，同时还有 site、fetch、cdp 这几个自带能力。

核心概念是任务空间（task space）。每个空间是一个隔离的浏览上下文，拥有自己的标签页，同时继承用户的登录状态。在脚本开头用 taskSpaces.useOrCreate(nameOrId) 选好空间，后续工作就在同一个 Bash 调用里完成，避免跨命令的状态丢失。

空间有所有权属性，分为 agent、agentDelegatedToUser、user 三种。如果目标空间是用户拥有的，Agent 想接管必须先拿到用户明确确认，然后走 taskSpaces.claim(id) 流程；switch 只对 Agent 拥有的空间生效。脚本结束时调用 taskSpaces.complete(nameOrId, { keep }) 收尾，keep 是必填项，默认 false，只有在用户明确要求保留页面时才传 true。

交互上提供三条路径：

• 语义路径：page.snapshot() 拿到页面结构，再用语义化 locator 或 @N 引用操作，适合常规 DOM 页面。
• 视觉路径：截图加鼠标键盘操作，适合 canvas、虚拟化编辑器、电子表格这类无障碍支持差的表面，编辑前先做一次小写入探针再截图验证。
• 直接路径：locator.evaluateAll(fn, arg) 处理元素集合，page.evaluate(fn, arg) 读取全页面状态，只有 facade 没覆盖的能力才上原始 CDP。

注意事项

几点容易踩的坑：

• 不要拿固定 sleep 当主要等待手段。导航、筛选、排序、提交这类操作的等待要走 Playwright 风格的等待机制，page.waitForTimeout(...) 最多 2000ms，而且只用于短暂的视觉稳定。
• @N 引用只在当前 Bash 调用的最新 snapshot 之后有效，每次 snapshot 都会重建引用表。跨命令要用语义化 locator 或重新 snapshot。
• page.evaluate(fn, arg) 的返回值直接就是数据，不要再 JSON.parse，也不要把函数体当字符串传。
• 时间单位大部分是毫秒，但 fetch.server / fetch.browser 的 timeout 和 taskSpaces.waitForAgentControl 的 interval/timeout 是秒。
• page.info() 报 { dialog: ... } 时，要先用 cdp('Page.handleJavaScriptDialog', ...) 处理弹窗；报 w: 0 或 h: 0 时停止截图和坐标类操作，直到视口恢复正常。
• Task spaces bridge 不暴露 Browser.grantPermissions 和 Browser.setPermission，遇到这类权限操作要报告能力边界，不要反复试探。