ego-browser-ops:ego 浏览器自动化与书签管理
这是什么
ego-browser-ops 是 ego-browser(ego lite) 的操作手册。ego lite 是一个 Chromium 内核的浏览器,设计成人和 AI Agent 共用——Agent 可以直接用你已经登录好的站点和浏览器数据干活,页面里还会显示一个「Agent 光标」,你随时能看见它在点什么、填什么。
这个 skill 把 ego 的 CLI、脚本环境和 Page API 整理成一份「怎么用」的说明,覆盖四件事:
- 正常开浏览器干活:打开页面、点按钮、填表单、截图、抓数据;
- 复用登录态:在指定 profile 上开 task space,直接用已登录的账号;
- 管理书签:列 / 搜 / 增 / 改 / 移 / 删 / 导出;
- 排障:连不上、动作超时、输出拿不到、space 名被占用等。
它是公共层,不含任何个人账号;某个人的 profile 名、默认落哪个 profile 之类的私有约定,放在私有的 ego-browser-ops-private 里。
边界:能调接口就别点界面。登录、验证码、2FA、纯视觉验收留在浏览器里;认证之后的数据读写,优先用页面内的
fetch(复用登录态)拿真实接口,写完再独立回读一次。
入口与安装探测
入口判断只有一条:command -v ego-browser。有就直接用,没有才去装 / 升级。装上之后 ego-browser import list 能列出本机其他浏览器(Chrome / Edge / Brave)的 profile,返回 JSON 的 browser_sources,这是确认「后端 CLI 服务在跑」最快的探针。
ego 的真值永远是官方指南,不是这份文档:
ego-browser skill # 打印当前版本的使用指南
末行 [ego-browser:skill] end of guide 是完整性标记,没有就说明被截断了,要存文件分段读。升级会改 API / 命令集,所以 ego-browser upgrade 之后一定重跑一次 ego-browser skill;输出里出现 [ego-browser:notice] 时,先把当前任务做完、征得用户同意再升级。
task space:一个目标一个空间
ego 的核心概念是 task space。约定是「一个用户目标 = 一个 task space」:建一次、打印 spaceId,后续每一轮都续用它。
关键点是每轮都是新的 Node 进程:space、tab 和 Page label 是持久的,但 JS 变量不持久。所以每一轮开头都要重新 taskSpace(id) 拿回 space、task.page("p1") 拿回页面句柄,不能指望上一轮的变量还在。
| 操作 | API |
|---|---|
| 列 profile | await profiles() → {id, name, isDefault} |
| 建 / 续用 space | await taskSpace(nameOrId, { profileId? }) |
| 列所有 space | await listTaskSpaces()(字段是 id,不是 spaceId) |
| 认领用户的 space | await claimTaskSpace(id)(仅用户明确要求时) |
| 接回自己的 space | await takeOverTaskSpace(id) |
| 取页面 / 新开页面 | task.page("p1") / await task.newPage() / pages() / tabs() |
| 交还控制权 | await task.handOff()(验证码、2FA、扫码、权限弹窗时用) |
| 结束 | await task.finish({ keep }) |
几条纪律:
- 卡住、超时、页面异常,都在原 space 内恢复,不要新开 space;确实续不下去就停下问用户。
task.page(label)不创建、也不校验存在(句柄永远是真值);新 space 自带p1。要确认页面在不在,用await task.pages()。- 用户接管、或 space 失活,就停,不绕路。
openedBy: "unknown"的 tab 视为用户的,不要关。 finish({ keep })只调一次、放最后一轮最后一句;要留给用户看的页面写进keep(如keep: ["p2"]),因用户接管或报错停下时不要调。
Page API 速览
按用途记比按字母记有用:
| 类别 | 常用方法 |
|---|---|
| 状态 | url() title() info() label targetId(不跨轮保存) |
| 观察 | snapshot() / snapshot({ scope: "full_page" }) / screenshot({ path }) |
| 导航 | goto(url, { waitUntil }) reload() |
| 等待 | waitForURL() waitForSelector() waitForLoadState() waitForEvent("popup"|"download") |
| 元素 | click() dblclick() hover() fill() selectOption() press() dragAndDrop() setInputFiles() |
| 对话框 | acceptDialog() dismissDialog() |
| 鼠标 / 键盘 | mouse.* / keyboard.*(含 paste) |
| 代码 / 协议 | evaluate(fn, arg) fetch(url, opts) cdp(method, params) events() |
实践中的几条:
- 每次只取够下一步决策的最便宜状态:DOM 页用
snapshot()(语义化的定位真值),canvas / 地图 / 富文本用screenshot()+ 坐标;默认不要两个都取。snapshot()只截视口,末尾出现[more content below the viewport: ...]只是下方省略,不是不存在,别据此下结论。 - 选择器必须恰好匹配一个可操作元素。支持快照 ref(
@21)、text=、loc=css:/loc=role:、xpath=、裸 CSS,CSS 能穿透开放 shadow root。 - 一轮内能规划好的动作放同一次调用,末尾等最终状态并打印新快照;页面变了旧
@N就失效,要重拍。 - 动作不达预期,先看页面真实状态,别盲目重试、别急着降级到坐标或 CDP。
- 不是 Playwright:没有
locator()/getByRole()/context()/expect()/route(),不要 import Playwright、不要另起浏览器;不够用就走evaluate()/cdp()。
指定 profile
ego lite 每个 profile 是一套独立的 cookie、登录态、书签、扩展。要复用某个账号的登录态,就是把 task space 建在那个 profile 上:
const p = (await profiles()).find((x) => x.name === "<profile 名>");
const task = await taskSpace("<任务短名> " + p.id, { profileId: p.id });
- 默认不选 profile,新 space 落在默认 profile;用户没点名某个 profile 时,不要去查、去选。
- space 名带上 profile id 是个好习惯——因为「同名 space 已存在时会直接续用、忽略
profileId」这个行为就藏在这里(见下面「坑」)。 - 想把别的浏览器数据整体搬进 ego:
ego-browser import --browser chrome|edge|brave [--profile <目录名>],先import list看源 profile 目录名。
书签管理:用脚本,不要手动改文件
书签统一走 scripts/ego-bookmarks.sh($VFT_KIT_DIR/skills/web-automation/ego-browser-ops/scripts/ego-bookmarks.sh)。它的原理是:在目标 profile 开一个临时 task space,打开 chrome://bookmarks,调页内 chrome.bookmarks API——和书签管理器是同一条通道,浏览器运行中也安全。跑完自动 finish。
B=${VFT_KIT_DIR}/skills/web-automation/ego-browser-ops/scripts/ego-bookmarks.sh
$B <profile名或id> tree [文件夹] # 全部书签 id/path/url(JSON 到 stdout)
$B <profile> ls [文件夹] # 只列一层子项
$B <profile> search <关键词>
$B <profile> add <文件夹> <标题> <url> # 文件夹不存在会逐级创建
$B <profile> mkdir <文件夹>
$B <profile> mv <id> <目标文件夹> [index]
$B <profile> rename <id> <新标题> [新url]
$B <profile> rm <id>... # 删文件夹会连子项一起删,并打印被删内容
$B <profile> export <绝对路径.json> # 导出整棵树做备份
- 文件夹可以写数字 id,也可以写标题路径
书签栏/AI/tools;根别名bar= 书签栏、other= 其他书签。 - 批量删改前先
export备份;删除前用search/ls确认 id。 - 跨 profile 复制书签:源
tree拿 JSON,逐条对目标add。
踩坑
console.log走 stderr:在ego-browser nodejs里,console.log/console.error都输出到 stderr,$(...)或管道拿到的是空的。要给后续命令解析的结果,写临时文件再cat(ego-bookmarks.sh就是这么做的)。脚本也读不到 shell 的环境变量和 cwd——参数由外层拼进 heredoc(用json.dumps编码防注入),文件路径一律写绝对路径;内置模块用await import("node:fs/promises")。profileId只在新建 space 时生效:同名 space 已存在时,taskSpace(name, { profileId })会续用旧的、忽略profileId,于是落到错误的 profile 上。space 名里带上 profile id,或先listTaskSpaces()确认。- 不要直接改
Bookmarks文件:数据目录(macOS~/Library/Application Support/Citro Labs/ego lite/<profileId>/)里的Bookmarks、Cookies只读分析可以看,写入一律走浏览器内 API——运行中的浏览器会覆盖你对文件的外部修改。 - 它不是 Playwright:见上「Page API 速览」。没有 locator / expect / route 这一套,用之前先换脑筋。
- 清 cookie 要看清范围:
page.cdp("Network.clearBrowserCookies")、clearBrowserCache、不带browserContextId的Storage.clearCookies清的是整个 profile、无法恢复,会把该 profile 上所有站点登出。要未登录环境,优先换一个未登录的 profile,其次只清单个 origin;全 profile 清理必须先征得用户同意并告知代价。 - space 名被占用:报
EGO_TASK_SPACE_NAME_IN_USE说明这个名字属于用户的 space——问用户是否认领(claimTaskSpace(id)),或换个名字,不要硬抢。
参考
- 安装 / 升级 / 连通验证、profile 列举指定与导入、清理 cookie 缓存、排障(连不上、超时、旧 ref、stderr 输出、埋点抓包)都在 skill 的
references/下。 - 官方指南是真值:
ego-browser skill;脚本内的help()/help("page.click")打印签名和少见选项。

留言板
0 条留言对话,从你开始
还没有留言。分享一个想法,或只是打声招呼。