给 Ego SDK 补 Linux 宿主:Space 租约与人机交接

1 阅读7分钟

上游 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 表示宿主没了。

层关键文件职责硬边界
CLIsrc/cli.mjs起宿主、注入 globalThis.ego、跑 runMain20s 启动等待
协议src/bridge-server.mjs方法分发、名称与租约校验32 MB/帧,128 并发/连接
控制src/controller.mjsSpace/标签/渲染/view 挂载每 Space 30 个标签
持久化src/state.mjsspaces.json 原子写目录 0700,文件 0600
常驻companion/sdk_broker.pySDK 轮次的稳定父进程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 是三个值,不是布尔:

取值含义谁能把它改回去
agentAgent 持有控制权,SDK 调用放行用户点"接管"
agentDelegatedToUserAgent 主动交接给人,等人工处理用户在桌面端点"归还给 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_FOUNDid 或名字解析不到重新列举,不要复用旧 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_UNAVAILABLESpace 没有标签或没有活动页面先 createTab
EGO_TASK_HOST_DISCONNECTEDsocket 断了重开一轮 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 选择不改上游、只补对端,代价是所有语义都得自己守。

仓库:github.com/Cooperiano/…