上游 ego-lite 的 README 写得很直白:官方客户端发的是 macOS 和 Windows 安装包,Linux 还在 roadmap 上。但它的 SDK 是 MIT 开源的,ego-browser CLI 只负责把一段脚本喂给"本机的原生浏览器环境",脚本里 globalThis.ego 那套 bindings 需要有人提供。
官方实现里,createTaskSpace / claimTaskSpace / snapshot / handOffTaskSpace 背后是一个真实的浏览器进程。Linux 上没有这个进程,于是 SDK 能加载、能执行,globalThis.ego 却是空的——这不是兼容性问题,是缺了一整个对端。
ego-linux 的路子不是 fork SDK,而是把 SDK 期望的"浏览器侧"实现出来。upstream.json 把这件事写成了可校验的承诺:
{
"repository": "https://github.com/citrolabs/ego-lite",
"commit": "d392204d1ea1a8027a591ab2b0129c2e11d85f26",
"sourceBlobsVerified": 215,
"modifiedUpstreamSourceFiles": 0,
"electron": "45.0.0"
}
modifiedUpstreamSourceFiles: 0 是这条路线的门票:SDK 原样躺在 vendor/,所有 Linux 侧逻辑都在宿主的 src/。代价是不能"差不多能用",必须逐条对齐 SDK 的语义——尤其是 Task Space 的身份、控制权和错误码。
三层进程、两条套接字
整条链路里没有 TCP 调试端口,全部是同用户本地 Unix socket:
ego-linux-browser nodejs 每次调用一个 CLI 进程
│ JSON lines,run/bridge.sock (0600)
▼
Electron main:Controller + StateStore + bridge-server
│ webContents.debugger(CDP 1.3),每个标签一个 WebContentsView
▼
Chromium renderer(sandbox,contextIsolation,无 nodeIntegration)
companion broker(Python)
│ companion/run/sdk.sock (0600, SO_PEERCRED 校验 uid)
▼
ego-linux-sdk 子进程(每轮一个,100s 上限,输出 1MB 上限)
协议本身很薄:一行一个 JSON,{ id, method, args, spaceId }。桥接层对每条连接做三件事——单帧超过 32 MB 直接 destroy(),同一连接在飞的请求超过 128 个直接 destroy(),JSON.parse 失败直接 destroy()。客户端 requestOnce 给每个请求 25 秒超时,错误码 EGO_TASK_HOST_DISCONNECTED 表示宿主没了。
| 层 | 关键文件 | 职责 | 硬边界 |
|---|---|---|---|
| CLI | src/cli.mjs | 起宿主、注入 globalThis.ego、跑 runMain | 20s 启动等待 |
| 协议 | src/bridge-server.mjs | 方法分发、名称与租约校验 | 32 MB/帧,128 并发/连接 |
| 控制 | src/controller.mjs | Space/标签/渲染/view 挂载 | 每 Space 30 个标签 |
| 持久化 | src/state.mjs | spaces.json 原子写 | 目录 0700,文件 0600 |
| 常驻 | companion/sdk_broker.py | SDK 轮次的稳定父进程 | 8 槽位,100s/轮 |
核心一:Space 的持久化模型与控制权三态
Task Space 没有数据库,就是一个 spaces.json,schema: 1。写盘用"临时文件 + rename",文件 0600、目录 0700,并且用一条 Promise 链把并发提交串行化——StateStore.save() 先把当前对象序列化成字符串快照,再排队落盘,避免两个 changed() 交错写出半截 JSON。读的时候如果 schema 不对就直接报 Cannot read task state,不会静默重置(有测试保证坏文件被原样保留)。
{
"schema": 1,
"nextId": 3,
"profiles": [{ "id": "Default", "name": "个人", "isDefault": true }],
"selectedId": 1,
"spaces": [
{
"id": 1,
"name": "checkout-flow",
"profileId": "Default",
"ownership": "agent",
"createdBy": "agent",
"activeTargetId": "ego:9f2c…",
"state": "正在读取结算页",
"tabs": [
{ "id": "9f2c…", "url": "https://example.com", "title": "示例", "openedBy": "agent" }
]
}
]
}
两个细节值得单独说。标签的 CDP targetId 不是 Chromium 的原生 id,而是宿主自己合成的 `ego:${tab.id}`;标签 id 是 randomUUID() 并落盘,所以跨 CLI 轮次、跨进程重启都稳定,Agent 上一轮拿到的 targetId 下一轮还能用。openedBy 记录了是谁开的标签,后面所有"能不能关"的判断都靠它。
ownership 是三个值,不是布尔:
| 取值 | 含义 | 谁能把它改回去 |
|---|---|---|
agent | Agent 持有控制权,SDK 调用放行 | 用户点"接管" |
agentDelegatedToUser | Agent 主动交接给人,等人工处理 | 用户在桌面端点"归还给 Agent" |
user | 任务已结束(completeTaskSpace),Space 留给人用 | 不回到 agent |
一切都从同一个函数出发:
// src/state.mjs
export function requireAgent(space) {
if (!space) throw failure("Task space not found", "EGO_TASK_SPACE_NOT_FOUND");
if (space.ownership !== "agent")
throw failure("manual_takeover", "EGO_TASK_SPACE_USER_IN_CONTROL");
return space;
}
既然 Agent 只能靠错误码决定"重试还是停手",这些字符串就不能含糊:
| 错误码 | 触发点 | Agent 侧该怎么应对 |
|---|---|---|
EGO_TASK_SPACE_NOT_FOUND | id 或名字解析不到 | 重新列举,不要复用旧 id |
EGO_TASK_SPACE_NOT_SELECTED | 任务级请求没有 spaceId | 先 claim,再 useTaskSpace |
EGO_TASK_SPACE_BUSY | 另一个连接正持有租约 | 可重试;客户端已做 2 秒退避 |
EGO_TASK_SPACE_USER_IN_CONTROL | 归属不是 agent,或 epoch 变了 | 立刻停手,等人处理完 |
EGO_TASK_SPACE_NAME_IN_USE | 新建/改名的名字已被占用 | 换名字,别用同一串重试 |
EGO_INVALID_ARGUMENT | 参数个数、类型或协议头不合法 | 改脚本,重试没意义 |
EGO_WEB_CONTENTS_UNAVAILABLE | Space 没有标签或没有活动页面 | 先 createTab |
EGO_TASK_HOST_DISCONNECTED | socket 断了 | 重开一轮 CLI |
EGO_SECURE_STORAGE_UNAVAILABLE | 启动时密钥环不可用 | 脚本层无法恢复 |
核心二:租约 + epoch,把"人接管"变成可检测状态
只靠 ownership 字段不够。想象 Agent 正在 await 一个 Page.navigate,中途用户点了"接管":命令已经发到 Chromium,字段才被改,于是指令在人的页面上生效了。这就是我需要第二个机制的原因——租约和 epoch。
租约是 Map<spaceId, client>,一个 Space 同时只能有一个连接持有:
// src/controller.mjs
ensureClient(space, client) {
if (this.userClosingSpaces.has(space.id))
throw failure("Space 正在关闭,请稍后重试", "EGO_TASK_SPACE_BUSY");
const owner = this.leases.get(space.id);
if (owner && owner !== client)
throw failure("Task space is busy in another invocation", "EGO_TASK_SPACE_BUSY");
this.leases.set(space.id, client);
for (const tab of space.tabs) this.startRendering(tab);
if (!owner) this.broadcast();
}
EGO_TASK_SPACE_BUSY 是可重试的,客户端因此做了一件很小但很有用的事:60 ms 一次、总共 2 秒的退避重试,而不是立刻把错误抛给 Agent——两个 CLI 轮次挨得太近是常态,不是异常。
epoch 是单调计数器。setOwnership() 每次真正改变归属就 epoch++,同时停掉帧订阅(endFrameSubscription)、释放该 Space 的下载、对所有标签发一条 Runtime.terminateExecution,并给正在这个 Space 上的 client 推一个 { event: "stopped" }。客户端收到就把所有 pending 的 CDP 请求用 EGO_TASK_SPACE_USER_IN_CONTROL 全部 reject。
真正的门禁是一个闭包,在每个危险操作前后各调一次:
guard(space, client) {
const epoch = space.epoch || 0;
return () => {
requireAgent(space);
if (
this.stopping ||
this.userClosingSpaces.has(space.id) ||
(client && (client.closed || this.leases.get(space.id) !== client)) ||
this.store.space(space.id) !== space ||
(space.epoch || 0) !== epoch
)
throw failure("manual_takeover", "EGO_TASK_SPACE_USER_IN_CONTROL");
};
}
用法是 const check = this.guard(space, client); check(); await doThing(); check();。五分钟后回头看,这个"夹心"写法比任何回调锁都好读:接管发生在 await 中间,后置 check() 一定会抛,Agent 不会误以为自己的动作成功了。
顺带一个安全上的坑:CDP 的 Target.getTargets 返回的是整个浏览器进程的原生清单,直接转发等于把别的 Space 的页面泄漏给当前 Agent。所以宿主先通过 Page.getFrameTree 建立"已证明属于本 Space"的集合,再拿它过滤原生清单:
const owned = new Map();
for (const tab of space.tabs) {
for (const [id, info] of tab.nativeTargets) owned.set(id, info);
const tree = await tab.view.webContents.debugger.sendCommand("Page.getFrameTree");
check();
const visit = (node) => {
if (node !== tree.frameTree)
owned.set(node.frame.id, { targetId: node.frame.id, type: "iframe", url: node.frame.url, title: "" });
for (const child of node.childFrames || []) visit(child);
};
visit(tree.frameTree);
}
const active = await this.activeTab(space)?.view.webContents.debugger.sendCommand("Target.getTargets");
const children = (active?.targetInfos || []).filter(
(info) => owned.has(info.targetId) && info.type !== "page",
);
同一层还硬拒了 Browser.* 和大部分 Target.*,Page.navigate 先过 navigationUrl()(只允许 http/https/about/data/blob,且 about: 只认 about:blank),file://、javascript:、chrome:// 一律 EGO_INVALID_ARGUMENT。
核心三:交接是单向的,这不是疏漏
SDK 文档里 handOffTaskSpace() 和 takeOverTaskSpace() 看着像一对。但在这个宿主里,后者在用户控制期间会失败:
// src/bridge-server.mjs(节选:注意 requireAgent 的位置)
const space = app.store.space(spaceId);
if (!space) throw failure("Task space not found", "EGO_TASK_SPACE_NOT_FOUND");
requireAgent(space); // 人已接管 → EGO_TASK_SPACE_USER_IN_CONTROL
app.ensureClient(space, client);
if (method === "takeOverTaskSpace") {
if (args.length) throw invalid("takeOverTaskSpace takes no arguments");
return `${space.id} is under agent control.`;
}
requireAgent() 在 switch 之前,所以 takeOverTaskSpace 只在"本来就在 agent 手里"时是个空操作;一旦 ownership !== "agent",它抛 EGO_TASK_SPACE_USER_IN_CONTROL。换句话说:Agent 只能把控制权交出去,拿回来必须由人在桌面端点一下。UI 上就是那个按钮,文案随状态翻转:
$("#control").textContent =
active?.ownership === "agent" ? "接管" : "归还给 Agent";
这个决定看起来反直觉,但它解决的是真实故障:人接管页面往往是因为遇到了登录验证、验证码、支付确认。如果 SDK 能自己把控制权抢回去,人就永远没有一段"确定属于自己"的时间窗。README 里那句 "Returning an Agent Space from human control requires the desktop UI" 不是限制,是承诺。
代价也很明确:无人值守的场景里,交接之后必须有人在场。这是设计取舍,不是待修 bug。
踩到的坑
1. Space 名字是查找键,重名会静默吃掉一个 Space。 现象是"这个 Space 永远关不掉,下次启动又冒出来一个"。原因:SDK 按名字解析到第一个匹配项,重名让新的那个按名字不可达,旧的永远占着名字。改法是在创建和重命名两条路径上都做 trim 后比对,冲突直接 EGO_TASK_SPACE_NAME_IN_USE——宁可让 Agent 换个名字,也不能让它操作一个自己以为存在的 Space。
const nameTaken = (app, name, except) =>
app.store.data.spaces.some(
(space) => space !== except &&
typeof space.name === "string" &&
space.name.trim() === name.trim(),
);
2. createTaskSpace 失败后留下了一个幽灵租约。 建 Space 时先 ensureClient 拿租约,再建首个标签;标签建失败(比如 profile 被删)时我只回滚了 spaces 数组,忘了 leases。于是那个 id 下次被 claim 时报 "busy in another invocation",而 Space 根本不存在。改法是在 catch 里一并删租约,并加了一条测试专门盯这个:
if (app.leases.get(space.id) === client) app.leases.delete(space.id);
await app.changed();
throw error;
3. 首帧比 IPC handler 快。 现象是启动时偶发 No handler registered for 'ego:command'。渲染进程一 paint 就发 state 查询,而 ipcMain.handle 是在 whenReady 之后才注册的,谁先到看运气。改法很土但彻底:先注册 handler,用一个 booted Promise 把请求挂住,初始化完成后再放行。
4. 没有 WebContents 的标签不该让整个关闭流程崩掉。 之前 closeTab 直接摸 tab.view.webContents.isDestroyed(),遇到 hydration 失败、启动中断留下的"无 view 标签"就抛 Cannot read properties of undefined,一个 Space 卡在关闭中途。现在把缺失的 view 当成纯粹的记账清理,而不是关闭失败。
5. 截图超时会继续占着原生队列。 概览预览要在一个面板里截最多 4 张图(2 个 worker 并发),每张 jpeg quality 60、缩到 480 px、上限 400 KB,Page.captureScreenshot 1.8s 超时。问题是 CDP 超时并不取消原生命令,如果直接放行下一个 capture,两张图的返回会错位。所以每个标签上有一条 captureQueue:超时后仍然把队列位置留给那条命令,直到它自己 settle 才 release()。
边界与代价
这套东西是 Linux x86_64 的开发预览,不是一个可以随便交给同事的发行版。几个我认为必须写进文档的边界:
- 密钥环缺失就拒绝启动,而不是退回明文。
safeStorage不可用或后端是basic_text时直接抛EGO_SECURE_STORAGE_UNAVAILABLE;basic后端只在EGO_LINUX_TEST_MODE=1且显式EGO_LINUX_TEST_BASIC=1时才允许。 - "Cookie 加密"不等于资料整体加密。Local Storage、history 等仍是明文,README 里专门写了一句话防止误解。
- 功能缺口是有的:没有书签(没有 store,菜单里也不放一个点不动的假入口)、没有自动更新、OAuth 弹窗上下文不完整、麦克风/摄像头没有授权界面。
- 未验证的面比验证过的多:Wayland、HiDPI、多显示器、长时间真实账号使用都不在已接受范围内。
- 测试自己也会骗人:
tests/ui-app.mjs还在断言改版前的侧栏布局,所以它被明确排除在发布门禁之外,而不是被改成"通过"。 - 代理配置是"受限"的:
network.json用O_NOFOLLOW打开,校验属主、0600、≤8 KB、只允许127.0.0.1/localhost/[::1]的http/socks5,bypass 列表禁止<-loopback>。
还有一条不那么技术的代价:这层宿主必须跟着 SDK 走。vendor/ 钉在某个 commit 上,SDK 一旦改 takeOverTaskSpace 的语义或新增错误码,宿主的 dispatch 就得跟着改,否则 Agent 会拿到它不认识的错误。docs/verification.md 里那句"532/532 上游 SDK 测试通过"看着像炫耀,其实是维护成本清单。
小结
在 Linux 上接管一个没有 Linux 客户端的浏览器 SDK,难点不在 Electron 窗口,而在把 SDK 的隐式约定——数字 id、名字唯一、控制权归属、跨 Space 隔离——显式实现成可校验的状态机和错误码。ego-linux 选择不改上游、只补对端,代价是所有语义都得自己守。