◆

ego-browser-ops:ego 浏览器自动化与书签管理

2026-11-05 04:000

这是什么

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
列 profileawait profiles() → {id, name, isDefault}
建 / 续用 spaceawait taskSpace(nameOrId, { profileId? })
列所有 spaceawait listTaskSpaces()(字段是 id,不是 spaceId)
认领用户的 spaceawait claimTaskSpace(id)(仅用户明确要求时)
接回自己的 spaceawait 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 条留言
Markdown
0 字
对话记录每个声音,都值得被看见

对话,从你开始

还没有留言。分享一个想法,或只是打声招呼。

PAGE LOAD / LIVEego-browser-ops:ego 浏览器自动化与书签管理加载中