数据截至 (上游 commit 0f23e3c9395c)
浏览器的四层控制
沙箱里只有一个真实 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_tabs | v1/browser/tabs | 列/开/关/激活标签页 |
browser_cookies | v1/browser/cookies | 读/写/删 cookie |
browser_state | v1/browser/state/save·load | 保存/恢复整个浏览器状态(登录态等) |
browser_network | v1/browser/network/* | 设请求头、改路由、记录请求、导出 HAR |
browser_captcha | v1/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:133 | execute_action(v1/browser/actions) |
| 动作类型清单 | sdk/js/src/api/resources/browser/types/Action.ts:5-20 | Action(判别联合,action_type) |
| 页面操作(④) | sdk/python/agent_sandbox/browser_page/raw_client.py | v1/browser/page/*(navigate,click,markdown,evaluate) |
| CDP 接入(①) | sdk/python/agent_sandbox/browser/raw_client.py、website/docs/en/guide/basic/browser.mdx:24-58 | v1/browser/info(cdp_url) |
| browser-use 集成示例 | README.md:363-397 | BrowserProfile(cdp_url=...) |
| 状态保存/恢复 | sdk/python/agent_sandbox/browser_state/raw_client.py | v1/browser/state/save·load |
| 网络拦截 / HAR | sdk/python/agent_sandbox/browser_network/raw_client.py | v1/browser/network/route·export_har |
| 验证码 | sdk/python/agent_sandbox/browser_captcha/raw_client.py | v1/browser/captcha/detect·wait |