Ego 浏览器

要解决什么问题

浏览器自动化脚本最怕两件事：环境不一致和「看不见的手」打架。Agent 在同一个浏览器里跑任务时，常常会踩到这些坑：

• 多个任务共享同一个上下文，Cookie 和登录态互相污染；
• 用户正在手动操作页面，Agent 却不知道，直接覆盖了对方的动作；
• 想用语义定位，但有些界面（画布、电子表格、地图）根本没有可访问性树；
• 脚本结束后留下一堆标签页，或者把别人的标签页关掉了。

ego-browser 的做法是给每个任务一个隔离的浏览上下文（task space），同时把控制权交给人和 Agent 显式协商。

核心能力与关键步骤

每个 task space 拥有独立的标签页，但会继承用户当前的登录态，所以 Agent 不需要重新登录就能操作已登录站点。任务开始时通过 taskSpaces.useOrCreate(nameOrId) 选择或创建空间，之后所有操作都在同一个 Bash 调用里完成。

交互路径有三条，可以根据页面类型组合使用：

• 语义路径：page.snapshot() 拿到可交互元素的快照，再用语义定位符、@N 引用或稳定的 loc=... 值操作。适合普通 DOM 页面。
• 视觉路径：截图 + 鼠标键盘。适合画布、虚拟化编辑器、电子表格和地图这类缺少 AX 树的界面。编辑前先做一个小的写入探测，截图或回读验证后再继续。
• 直接路径：locator.evaluateAll(fn, arg) 和 page.evaluate(fn, arg) 读取页面状态。只有 facade 覆盖不了的能力才用裸 CDP。

任务结束时必须调用 taskSpaces.complete(nameOrId, { keep })，keep 是必填项。默认 false，关闭空间；只有在用户明确要求保留页面、需要人工介入，或结果无法以 URL/文件/摘要形式交付时才设为 true。

适用边界与注意点

• 所有权是硬约束。taskSpaces.switch 只能切换 agent 拥有的空间；对 user-owned 空间必须先 claim。如果遇到「用户正在控制」的错误，整条任务立即停止，不要自动重试或绕过，而是询问用户。
• 快照引用有生命周期。@N 引用只在当前 Bash 调用内有效，每次快照都会重建引用表。命令结束后重新快照，或改用语义定位符。
• 不要依赖固定 sleep。导航、筛选、排序、提交等操作要用页面事件等待，page.waitForTimeout(...) 控制在 2000 ms 以内，只用于短暂的视觉稳定。
• 弹窗和零尺寸视口。page.info() 返回 { dialog: ... } 时，需要用 cdp('Page.handleJavaScriptDialog', ...) 处理；w: 0 或 h: 0 时停止截图和坐标操作。
• 超时单位不一致。Playwright 风格的 page、locator、导航辅助函数使用毫秒；fetch.server / fetch.browser 和 taskSpaces.waitForAgentControl 使用秒。
• 不要硬编码标签页 ID，需要切换或关闭时重新调用 browser.listTabs() 验证。