browser-use：给 Buffin 加上 Agent 浏览器自动化能力

buffin-ai/buffin · 3d1545a3...browser-use · 2026-08-01 · 自包含，读完即弃

写法说明：本文按「逐跳走读」展开——每个机制都给真实代码片段（取自分支、经裁剪，青色斜体注释为解读所加，灰色斜体是源码原注释的保留或意译），每段代码标注所在文件。每条旅程结尾有一张「排查路标」：将来出问题时，症状对应去哪个文件看哪个函数。

1TL;DR

Buffin 现在可以用内嵌的 Electron WebContentsView 跑浏览器自动化任务了。Desktop 进程充当 Browser Host（提供真实浏览器页面），通过 tRPC WebSocket 连接 daemon 中新增的 Browser Coordinator（命令排队、租约管理）；外部 Agent 或 CLI 通过 browser.* tRPC 过程下发点击/填充/截取 accessibility snapshot 等操作。实际页面操作由捆绑的 agent-browser 0.33.1 二进制通过 CDP 页面网关完成。

整个体系是一个 command-queue 模式：外部调用方 → daemon coordinator（排队 + 选 host）→ desktop wire（轮询取件）→ adapter（调 agent-browser 进程）→ 回报结果。

2变更地图（称重）

3架构一图流

4数据与状态先行

合约层形状（packages/api/src/browser.ts）

整个合约围绕三个坐标：browserId（逻辑 target 标识，对应一个 WebContentsView）、epoch（导航代次，每次 main-frame navigation 递增；epoch 改变意味着旧 accessibility ref 失效）、leaseId（Host 持有的单租约凭证，30 秒过期需心跳续命）。

export const browserIdSchema = idSchema           // UUID v7 标识一个浏览器 tab
export const browserEpochSchema = z.number().int().nonnegative().safe()  // 导航代次
export const browserRefSchema = z.string().trim().min(1).max(256)       // accessibility 节点的不透明引用
export const browserLeaseIdSchema = idSchema      // Host 租约凭证

Action 是一个 discriminated union——只有五种受控操作（navigate / click / fill / press / scroll），每个 action 的输入是 ref（不透明引用）而非 CSS selector，也无法注入脚本。

export const browserActionSchema = z.discriminatedUnion('kind', [
  z.object({ kind: z.literal('navigate'), url: browserUrlSchema }).strict(),
  z.object({ kind: z.literal('click'), ref: browserRefSchema }).strict(),
  z.object({ kind: z.literal('fill'), ref: browserRefSchema, value: z.string().max(100_000) }).strict(),
  z.object({ kind: z.literal('press'), ref: browserRefSchema, key: z.string().trim().min(1).max(64) }).strict(),
  z.object({ kind: z.literal('scroll'), ref: browserRefSchema,
    deltaX: z.number().finite().min(-100_000).max(100_000),
    deltaY: z.number().finite().min(-100_000).max(100_000),
  }).strict(),
])

Accessibility snapshot 有结构化的 ref-graph 验证（唯一性、rootRef 存在、parentRef 合法）和文本预算（MAX_BROWSER_SNAPSHOT_TEXT = 100,000 字符）。

Coordinator 内存状态（apps/daemon/src/browser/coordinator.ts）

type HostRecord = {
  hostId: string        // Host 运行时的稳定 id
  leaseId: string       // 当前租约（独占）
  expiresAt: number     // 30 秒后过期
  capabilities: BrowserCapabilities
  targets: Map<string, number>  // browserId → epoch，多 tab 独立
}

type CommandRecord = {
  command: BrowserCommand
  state: 'offered' | 'accepted' | 'terminal'
  isWrite: boolean      // accepted 后 Host 掉线，write → outcome_unknown
  result?: BrowserCommandResult
  waiter?: { resolve, reject, kind }  // describe/snapshot/verify 的同步等待者
}

5底座：命令生命周期

一条命令从入队到完成经过固定四态：offered → accepted → terminal。写操作（action）在 accepted 后 Host 断连会进入 outcome_unknown——表示页面可能已经被修改了，读操作（describe / snapshot / verify）则直接 fail closed。

6旅程 A：Agent 下发一个"点击按钮"命令

这是最典型的端到端路径：外部调用方想让浏览器点击某个元素引用。走通后掌握所有层如何串联。

A.1API 入口：browser.action

调用方传入 browserId + epoch + action。Router 做 zod 校验后委托 BrowserService.action()。

action: publicProcedure
  .input(browserActionInputSchema)
  .output(browserCommandReceiptSchema)
  .mutation(({ ctx, input }) =>
    callService(() => requireBrowserService(ctx).action(input)),
  ),

如果 daemon 进程没有注入 BrowserService（desktop 没启动），requireBrowserService 抛 browser.hostUnavailable（HTTP 409）。

A.2Coordinator 接收排队

Coordinator 验证 epoch 一致、capability 允许，然后创建一条 CommandRecord 进入 offered 状态，返回 receipt。

action(input) {
  const parsed = browserActionInputSchema.parse(input)
  const active = requireActiveHost()
  requireExactEpoch(active, parsed.browserId, parsed.epoch)
  requireCapability(active.capabilities, { kind: 'action', action: parsed.action, ... })
  const command = createCommand({
    browserId: parsed.browserId, epoch: parsed.epoch,
    request: { kind: 'action', action: parsed.action, ... },
    isWrite: true,  // 点击是写操作——Host 断连后命令结果未知
  })
  return { browserId: command.browserId, epoch: command.epoch,
           commandId: command.commandId, state: 'offered' }
}

A.3Wire 轮询取件并执行

Desktop 进程的 BrowserHostWireRuntime 通过定期 poll（idle 1s / active 50ms）调 browser.commands.offer 拿到命令，先 accept，再分发给 adapter。

private async processCommand(command: BrowserCommand, generation: number) {
  // ...
  await this.client?.accept(acceptedInput)      // 通知 coordinator 已接手
  this.acceptedCommand = { commandId, generation }
  const controller = new AbortController()
  this.activeCommand = { commandId, generation, controller }
  const outcome = await this.commandOutcome(command, preAcceptanceFailure, target, controller.signal)
  await this.client?.complete({ ...acceptedInput, outcome })  // 上报结果
  this.completedCommandIds.add(command.commandId)
}

A.4Adapter 落地执行

Control Adapter 把 { kind: 'click', ref: 'button-1' } 映射为 agent-browser CLI 参数 ['click', '@button-1']，然后通过 CDP Gate 转发给实际页面。

function actionCommands(action: BrowserAction): string[][] {
  switch (action.kind) {
    case 'navigate': return [['navigate', action.url]]
    case 'click':    return [['click', `@${action.ref}`]]
    case 'fill':     return [['fill', `@${action.ref}`, action.value]]
    case 'press':    return [['focus', `@${action.ref}`], ['press', action.key]]
    case 'scroll':   // ... deltaX / deltaY 拆成 left/right/up/down 命令
  }
}

每次调用前，Gate 会 issue() 一个只活在命令执行期间的 capability URL，之后立即 revoke()。这个 URL 是 agent-browser 进程唯一能拿到的 CDP 连接方式——env 变量 BUFFIN_BROWSER_GATE_URL 只在子进程生存期内有效。

7旅程 B：读取 Accessibility Snapshot

Agent 调用 browser.snapshot 获取页面当前可交互元素的结构化表示。与旅程 A 的区别：snapshot 是同步 await 风格——调用方的 RPC 会一直挂着直到 Host 完成 snapshot 并回报结果。

B.1同步 await 风格

Coordinator 内部用 enqueueWaiter() 创建一个 Promise——命令入队同时把 resolve/reject 存在 CommandRecord 的 waiter 字段上。Host 完成后 settleWaiter() 把 snapshot 结果直接 resolve 给等待者，调用方的 tRPC query 才返回。

snapshot(input) {
  // ...
  return enqueueWaiter({
    browserId: parsed.browserId, epoch: parsed.epoch,
    request: { kind: 'snapshot', ... },
    kind: 'snapshot',
  }) as Promise<BrowserSnapshot>  // tRPC 调用者 await 此 promise 直到 Host 回报
}

B.2Snapshot 转换

agent-browser 返回的 snapshot 是纯文本 + refs map 格式。Adapter 的 convertSnapshot() 逐行解析文本，映射 ref 到结构化节点，最后用 browserSnapshotSchema.parse() 做边界校验（唯一性、节点数上限、文本预算）。

8旅程 C：Host 掉线与恢复

Desktop 进程重启或 WebSocket 断开时，wire 执行以下恢复路径：

1. Wire 检测到 tRPC connectionState 变为 connecting + error ≠ null，触发 reconnect()
2. 如果有 activeCommand，abort 它的 AbortController（adapter 中的进程被 SIGTERM）
3. 尝试 disconnect 旧 lease（best-effort）
4. 关闭旧 client，exponential backoff（250ms → 10s 上限）后重新 connect()
5. 新 client ready 后重新 attach()，coordinator 给出新 lease，恢复 heartbeat + poll

Coordinator 侧对旧 lease 的处理：clearHost() 遍历 commandOrder——offered 态的命令留着供新 Host 重新取件；accepted 态的写命令标 outcome_unknown；accepted 态的读命令标 failed: targetDisconnected。

9计划 vs 实现偏差

10心智模型补丁

11新词表

12测试与风险地图

13验收提示

• BrowserService 在 Services 接口上是 optional——这是有意的：daemon 只在 desktop 连接后才有 browser 能力，CLI-only 场景合法缺失
• docs/ 的两篇文档（profile-import design + research）描述的功能本 PR 尚未实现——它们是路线图文档，不是功能声明
• browser.js 文件是 Node source TypeScript loader 的运行时 shim（export * from './browser.ts'），不是手写逻辑
• electron.vite.config.ts 的重写是为了把 daemon URL 注入 main bundle 的 __BUFFIN_MAIN_DAEMON_URL__ define——不是格式化

14覆盖声明

主力全量精读了 packages/api/src/browser.ts（511 行）、packages/api/src/trpc.ts diff、所有 error 注册、apps/daemon/src/browser/coordinator.ts（519 行）及其测试、apps/desktop/src/main/browser-host.ts、browser-control-adapter.ts（前 990 行）、browser-host-wire.ts（全文 731 行）、shared/browser.ts（全文）、browser-bridge.ts（全文）、preload/index.ts diff、BrowserPanel.tsx 前 80 行、CLI browser 相关全部 diff、docs 两篇（前 30 行 + 结构）。

未精读：browser-control-adapter.ts 末尾的辅助解析函数（约 240 行）、inspect/ 子目录四个文件的实现细节、BrowserPanel.tsx 后半部分的 JSX 渲染。这些属于终端实现，不影响架构理解。

buffin-ai/buffin · browser-use · 83 files, +10,640 / −192 · 本报告为一次性理解辅助，不维护、不作为真相源。