跳到主要内容

浏览器的四层控制

沙箱里只有一个真实 Chrome,但暴露了四种不同抽象层去控制它。搞清这四层各是什么、何时用哪个,是用好沙箱浏览器的关键。

1. 四层控制总览​

怎么读这张图: 从下到上,抽象越来越高——越往下越接近「操作系统层面的输入」,越往上越接近「网页语义」。

   高 ┌─────────────────────────────────────────────┐
   抽 │ ④ Playwright 式页面操作  /v1/browser/page/*   │ browser-use 范式
   象 │    navigate/click/fill/type/scroll/evaluate   │ 按 DOM 选择器/语义操作
      ├─────────────────────────────────────────────┤
      │ ③ 像素级 GUI 动作      /v1/browser/actions    │ computer-use 范式
      │    CLICK/MOVE_TO/DRAG_TO/Typing/Hotkey(坐标)  │ 按屏幕坐标操作
      ├─────────────────────────────────────────────┤
      │ ② VNC 远程桌面         /vnc/index.html         │ 给人看 / 人接管
      ├─────────────────────────────────────────────┤
   低 │ ① CDP 协议            /cdp、/v1/browser/info   │ 给 Playwright/Puppeteer
   抽 │    cdp_url / webSocketDebuggerUrl              │ 直连
   象 └─────────────────────────────────────────────┘
层入口操作方式典型用户
① CDP/v1/browser/info、/cdp/json/version拿 cdp_url,自己接 Playwright/Puppeteer已有浏览器自动化栈的人
② VNC/vnc/index.html?autoconnect=true远程桌面,肉眼看 + 手接管人
③ GUI 动作/v1/browser/actions屏幕坐标级输入(点/移/拖/打字/热键)computer-use 类 agent
④ 页面操作/v1/browser/page/*DOM 选择器/语义级操作browser-use 类 agent

2. ① CDP:最底层的钩子​

CDP(Chrome DevTools Protocol,Chrome 的底层调试协议)是其它一切的地基。沙箱把它直接暴露,让你拿到一个 WebSocket 端点,再用任何标准自动化库连上去(website/docs/en/guide/basic/browser.mdx:24-58):

# 拿 CDP 地址
curl http://localhost:8080/v1/browser/info | jq '.data.cdp_url'
curl http://localhost:8080/cdp/json/version | jq '.webSocketDebuggerUrl'

README 的 browser-use 集成示例就是这条路:从 sandbox.browser.get_info().data.cdp_url 拿到地址,塞给 browser_use 的 BrowserProfile(cdp_url=...),让外部 agent 框架直接驱动沙箱里的 Chrome(README.md:363-397)。这是「沙箱出浏览器、外部框架出大脑」的标准接法。

3. ③ 像素级 GUI 动作:computer-use 范式​

/v1/browser/actions(sdk/python/agent_sandbox/browser/raw_client.py:133,符号 execute_action)接受一个**判别联合(discriminated union)**的动作对象,按屏幕坐标操作——本质上是「在这台机器的屏幕上点这里、打这串字」。动作类型清单(sdk/js/src/api/resources/browser/types/Action.ts:5-20):

类别动作
鼠标移动MOVE_TO MOVE_REL
鼠标点击CLICK RIGHT_CLICK DOUBLE_CLICK MOUSE_DOWN MOUSE_UP
拖拽DRAG_TO DRAG_REL
滚动SCROLL
键盘Typing Press KEY_DOWN KEY_UP Hotkey
其它Wait
# 示意,基于 Action 判别联合(action_type 是判别字段)
client.browser.execute_action(action={"action_type": "CLICK", "x": 320, "y": 240})
client.browser.execute_action(action={"action_type": "TYPING", "text": "hello"})

这层的特点:和网页 DOM 无关,纯屏幕坐标——所以它能操作任何 GUI(不止网页),对应「computer-use」那一类靠截图 + 坐标动作的 agent。配合 /v1/browser/screenshot(GET,sdk/python/agent_sandbox/browser/raw_client.py)拿截图,就是「看屏幕 → 决定坐标 → 发动作」的闭环。

4. ④ Playwright 式页面操作:browser-use 范式​

/v1/browser/page/*(sdk/python/agent_sandbox/browser_page/raw_client.py)是高层、按 DOM 语义的页面操作,等于把 Playwright 的常用 API 做成了 HTTP 端点。这层端点很全:

类别端点
导航navigate back forward reload
交互click fill type press_key hot_key hover select_option check uncheck upload_file fill_form
滚动scroll scroll_to scroll_to_element
提取html text markdown elements screenshot
高级console(读/导出)evaluate(执行 JS)find_text wait record

markdown 提取值得点名:GET /v1/browser/page/markdown 直接把当前页转成 markdown(sdk/python/agent_sandbox/browser_page/raw_client.py)。对「网页 → 喂给 LLM」的流水线,这一步省掉了自己抓 HTML 再清洗的活。配合 util 子系统的 /v1/util/convert_to_markdown(sdk/python/agent_sandbox/util/raw_client.py:23,符号 convert_to_markdown,即 markitdown),沙箱给「文档/网页转 markdown」提供了两条现成路径。

③ 和 ④ 怎么选? 知道选择器、要稳定可复现 → 用 ④ 页面操作(语义级,抗像素漂移);只有截图、要像人一样肉眼点 → 用 ③ GUI 动作。

5. 浏览器的「会话资产」:cookies / state / network / captcha​

围绕浏览器还有一圈管理子系统,处理「跨任务复用」和「拦截/观测」:

子系统端点前缀干什么
browser_tabsv1/browser/tabs列/开/关/激活标签页
browser_cookiesv1/browser/cookies读/写/删 cookie
browser_statev1/browser/state/save·load保存/恢复整个浏览器状态(登录态等)
browser_networkv1/browser/network/*设请求头、改路由、记录请求、导出 HAR
browser_captchav1/browser/captcha/detect·wait检测验证码、等待其被解决

几个亮点(均来自 sdk/python/agent_sandbox/browser_*/raw_client.py 的端点):

  • state/save + state/load 让 agent 把一次登录的成果存下来、下个任务直接恢复,免去反复登录——对需要登录态的长流程很关键。
  • network/route(POST/DELETE)+ network/export_har 提供请求拦截与改写,以及把整段网络活动导成 HAR 做事后分析。
  • captcha/detect + captcha/wait 把「页面上是否有验证码、等它被解掉」做成显式 API,而不是让 agent 去猜。

6. 重启与配置​

v1/browser/restart、v1/browser/config(sdk/python/agent_sandbox/browser/raw_client.py)允许重启浏览器、改配置;v1/browser/proxy.pac 暴露 PAC 文件(配合代理,见第 4 章)。VNC(/vnc/index.html,README.md:65)始终是那条「人接管」的后路——当 agent 卡住,人可以直接连进桌面手动操作,这是 AIO「人机共用一个浏览器」的体现。

7. 代码地图​

主题文件路径符号名
GUI 像素动作(③)sdk/python/agent_sandbox/browser/raw_client.py:133execute_action(v1/browser/actions)
动作类型清单sdk/js/src/api/resources/browser/types/Action.ts:5-20Action(判别联合,action_type)
页面操作(④)sdk/python/agent_sandbox/browser_page/raw_client.pyv1/browser/page/*(navigate,click,markdown,evaluate)
CDP 接入(①)sdk/python/agent_sandbox/browser/raw_client.py、website/docs/en/guide/basic/browser.mdx:24-58v1/browser/info(cdp_url)
browser-use 集成示例README.md:363-397BrowserProfile(cdp_url=...)
状态保存/恢复sdk/python/agent_sandbox/browser_state/raw_client.pyv1/browser/state/save·load
网络拦截 / HARsdk/python/agent_sandbox/browser_network/raw_client.pyv1/browser/network/route·export_har
验证码sdk/python/agent_sandbox/browser_captcha/raw_client.pyv1/browser/captcha/detect·wait