比OCR快221倍:深入typesafe-computer-use的CDP DOM感知浏览器后端

原创2026-10-13 21:08:101,740 阅读

比OCR快221倍:深入typesafe-computer-use的CDP DOM感知浏览器后端

typesafe-computer-use(简称 jev)是一个用纯英文目标驱动电脑完成操作任务的 AI 开源项目,每一步成本约 $0.0002。它的浏览器后端走了一条完全不同的路:不截屏、不做 OCR,而是通过 Chrome DevTools Protocol(CDP)直接读取页面的 DOM 树。官方实测中,DOM 感知比"截图 + Vision OCR"最快快了 221 倍,准确率也从不足 10% 提升到 100%。这篇文章带你完整拆解这套 CDP DOM 感知浏览器后端的设计。

背景:为什么截图 + OCR 是浏览器任务的天生瓶颈

jev 的桌面后端(macos.py)感知屏幕的方式是:截屏 → Vision OCR 识别文字 → 合并成文本块 → 排出阅读顺序。这条路对"通用桌面"很合理,但对浏览器页面却处处别扭:

  • 慢:一次感知 ≈ 143–177 ms 截图 + 573–710 ms Vision OCR,合计约 300–900 ms;
  • 不准:OCR 读出来的是"像素猜出来的字",真实网站上它对 DOM 标签的逐字复现率只有 7/13、7/88、3/85——不到 10%。分类器在一堆乱码字符串里做选择,当然容易犯错;
  • 重:需要 Screen Recording(屏幕录制)权限,还要处理 Retina 像素到屏幕坐标的换算。

而浏览器页面其实"自带答案":每个元素的文本、角色、标签、可点击位置,DOM 里都写得清清楚楚。

typesafe-computer-use 浏览器自动化需要感知的 Chrome 页面截图,包含书签管理器和恢复页面气泡

核心原理:一次 Runtime.evaluate 读完整个页面

浏览器后端位于 typesafe_computer_use/browser/,整个数据流只有四步:

Runtime.evaluate ─► 有序元素列表(文本、角色、点击点、是否在屏、是否被遮挡)
                  + 页面可见文本(价格、日期、错误提示;仅作证据)
                    │
       一次 TypeSafe 请求,两个 Choice
       kind    : click | type_text | navigate | press_enter | scroll_down | ... | done
       element : 点击/输入哪一个元素
                    │
       真实 Input 输入事件 ─► 观察直到页面变化 ─► 下一步

一个 WebSocket 连上 Chrome

typesafe_computer_use/browser/cdp.py 是整个后端中唯一与浏览器打交道的模块,也是唯一会启动浏览器的地方。它的启动策略值得注意:

  • 全新临时 profile:每次运行创建独立用户目录(--user-data-dir),绝不动你本人的 Chrome 配置,关闭时自动删除;
  • 只监听回环地址:调试 socket 绑定在 127.0.0.1 的随机端口上,并只接受单一 origin 的 WebSocket 连接——Chrome 111+ 会拒绝任何其他来源,网页自己无法劫持这个浏览器;
  • 端口防抢:获取页面调试地址时,会校验它确实指向本实例的 loopback 端口,防止其他进程抢端口后应答。

一段 JS 收集"干净"的元素列表

typesafe_computer_use/browser/perceive.py 里埋了一段约 130 行的 JavaScript,通过一次 Runtime.evaluate 完成全部感知。它做了几件非常讲究的事:

  1. 视口检查放在样式解析之前。getComputedStyle 是循环里最贵的调用,而重载页面上大多数候选元素根本不在屏内——先把它们丢掉,省下的开销就是这 1–14 ms 的来源;
  2. 元素盖章:每个入选元素被打上 data-tscu="<index>" 属性,作为后续步骤稳定点击、聚焦的句柄;每次感知前会先清掉上一轮的旧章,消失的元素不可能被误点;
  3. 去重与排序:按"标签 + 坐标 + 标签名"去重(导航栏副本、ARIA 重复项会被合并),再按阅读顺序(先 y 后 x)重排索引;
  4. 遮挡检测:用 elementFromPoint 判断元素中心点是否被浮层盖住,被盖住的元素会标记 covered,分类器会优先选"没被弹层挡住"的。

元素与可见文本严格分离

同一次脚本还顺带收集页面的可见文本(page_text):价格、日期、报错提示等非控件内容,最多 120 块、每块 240 字符,按阅读顺序排列。关键点在于:

  • 文本块永远不是点击目标,只用于判断 done/satisfied;
  • 输入框里已输入的内容、未发送的 contenteditable 草稿一律不读——用户打了一半的密码或卡号不会进入分类器、writer、日志或运行记录。

221 倍快在哪里:官方实测数据

下面这组数据来自 docs/browser-backend.md,同一台机器、同一时刻、同一页面,每条路径各做一次完整感知:

页面 DOM(CDP 感知) 截图 + Vision OCR 倍数
本地 fixture 页面 1.3 ms(28 个元素) 288.0 ms(31 个文本块) 221x
news.ycombinator.com 4.5 ms(120 个元素) 697.3 ms(46 个文本块) 155x
en.wikipedia.org/wiki/Singapore 14.4 ms(91 个元素) 897.0 ms(50 个文本块) 62x

放到完整步骤循环里,端到端 p50 是 302–380 ms/步(约 2.6–3.5 步/秒),其中约 280–350 ms 是 TypeSafe 决策本身。感知几乎不再占用任何时间。

快只是其次:准确率才是关键的一半

速度只是这个故事的一半。OCR 在三类页面上对 DOM 标签的逐字复现率都不到 10%,意味着分类器在 OCR 路径下其实是在"拼写错的字符串"里做选择题;而在 DOM 路径下,它选的是页面真实存在的标签——正确的文本、正确的角色、正确的点击坐标,一步到位。

动作层:真实输入事件,等待近乎免费

决策由 typesafe_computer_use/browser/decide.py 完成:一次 TypeSafe 请求回答两个 Choice——动作类型(click、type_text、navigate、scroll_down、done……)和具体元素。有一个非常克制的设计:动作集合会按页面实际能力过滤——没有输入框就不给 type_text,没有 writer 就不给 navigate,页面滚不动就不给 scroll_down。一个执行不了的动作必然导致卡死,而卡死会被误读成"模型没把握",其实模型的锅。

执行侧 typesafe_computer_use/browser/act.py 有两个亮点:

  • 真输入事件:每次点击都是 Input.dispatchMouseEvent 的 press/release 序列,输入用 Input.insertText,而不是 JS .click()——监听真实指针事件的框架(如 React)行为与人类操作完全一致;
  • 观察即等待:动作执行后的"等待页面变化"和下一步需要的"感知"是同一个调用(observe_until_changed,8 ms 轮询、300 ms 超时)。常见情况 20–40 ms 内页面就变了,等待几乎不花额外往返。

隐私与安全:字段内容永远读不到

这套后端把隐私做成了架构约束而非承诺:

  • 不读输入值:感知阶段从不采集 input 的 value,任何元素也不会用输入内容命名,页面上的密码到不了分类器、writer 或磁盘;
  • 凭证字段拒写:type=password 以及 autocomplete 含 current-password、cc-number 等凭证标记的字段被标记为 secret,循环在调用 writer 之前就拒绝向其输入,每步日志会记录文字来源(writer/writer_declined/refused_credential/no_writer);
  • 独立浏览器:专用临时 profile + 仅回环地址 + 单 origin,与你的日常浏览器完全隔离。

如何使用:clicker-bench 三条命令

浏览器后端是显式开启的,clicker 本身不会用它。clicker-bench 会自己拉起一个全新 Chrome,读取环境变量或 ./.env 中的 TYPESAFE_API_KEY:

uv run clicker-bench loop --fixture --runs runs   # 端到端步骤循环
uv run clicker-bench perception --url https://news.ycombinator.com
uv run clicker-bench replay --run runs/<ts> --step 2   # 离线重放某一步决策

每次运行会写入与桌面版同构的运行文件夹 runs//,浏览器版的可重放工件是 step-NN-elements.json(浏览器步骤没有像素可存)。replay 命令用它重建页面状态,并校验重建出的 state 与原始发送的是否一致,让你不开浏览器就能复查一次卡住的决策。

浏览器后端的适用边界

诚实地说,DOM 感知有明确的适用边界(见 docs/browser-backend.md):

  • 只看得见视口:与 OCR 只看可见屏幕同理,折叠线以下的元素需要先 scroll_down;
  • 看不见画出来的东西:canvas 绘制的 UI、烘焙进图片里的文字,DOM 里不存在——这类场景请回落到 macos.py 的 OCR 路径,两条路径互补而非互斥;
  • 单标签页:一个页面 target,不穿透 iframe 和 shadow DOM。

小结

typesafe-computer-use 的浏览器后端证明了:当感知对象本身就是结构化数据时,与其"截个图再猜",不如直接读它。CDP DOM 感知用一次 Runtime.evaluate 换来了 221 倍的速度、100% 的标签准确率、零屏幕权限,还顺带把隐私做成了架构级保证。对想给自己的 AI agent 加"浏览器手"的团队来说,typesafe_computer_use/browser/ 是一个可以直接借鉴的最小实现——核心逻辑不到 1000 行 Python。

登录后查看全文
typesafe-computer-use