Browser Automation

browser(action=...) 提供 DOM 感知的浏览器控制能力，通过 Chrome DevTools Protocol (CDP) 与浏览器交互。

概述

Browser 工具是中间层交互工具——它理解网页的 DOM 结构，可以通过 CSS 选择器或 Accessibility Tree 的 ref 来精确操作元素。适用于所有网页交互场景。

可用 Actions

Action	说明	关键参数
`navigate`	导航到 URL	`url`, `new_tab`
`screenshot`	页面截图	`url`/`html`/`file_path`, `full_page`
`snapshot`	获取 Accessibility Tree	`selector`
`click`	点击元素	`ref`, `button`, `double_click`
`type`	逐键输入	`ref`, `text`, `clear`, `submit`
`fill`	瞬间设置值	`ref`, `text`
`scroll`	滚动	`direction`, `amount`, `ref`
`press_key`	按键	`key`
`tabs`	Tab 管理	`tab_action`, `tab_index`
`set_html`	注入 HTML	`html`
`go_back`	返回上一页	—

Screenshot 三种模式

browser(action="screenshot") 支持三种内容来源，覆盖不同使用场景：

1. URL 模式（已运行的页面）

browser(action="screenshot", url="http://localhost:5173")

截取指定 URL 的页面。适用于有 dev server 运行的项目。

2. HTML 注入模式（零服务器）

browser(action="screenshot", html="<html><body><h1>Hello</h1></body></html>")

通过 CDP Page.setDocumentContent 直接注入 HTML 并截图。无需启动任何服务器。适用于快速验证生成的 HTML 片段。

3. 文件路径模式（本地文件）

browser(action="screenshot", file_path="/home/user/workspace/demo.html")

自动启动 bun serve 并截取指定文件。适用于包含本地资源引用的 HTML 文件。

Accessibility Tree 工作流

推荐的交互模式是先获取元素 ref，再通过 ref 操作：

# 1. 获取页面结构
browser(action="snapshot")
# 返回: [0] button "Submit" [1] input "Email" [2] link "Home" ...

# 2. 通过 ref 操作
browser(action="fill", ref="input[1]", text="user@example.com")
browser(action="click", ref="button[0]")

这比 CSS 选择器更可靠，因为 ref 是基于 Accessibility Tree 的语义标识。

使用示例

视觉验证（Sites 开发）

browser(action="screenshot", url="http://localhost:5173")
# 分析截图，发现布局问题
# 修改代码...
browser(action="screenshot", url="http://localhost:5173")
# 验证修复

表单填写

browser(action="navigate", url="https://example.com/form")
browser(action="snapshot")
browser(action="fill", ref="input[0]", text="John Doe")
browser(action="fill", ref="input[1]", text="john@example.com")
browser(action="click", ref="button[0]")

3D 场景验证

browser(action="screenshot", html="<!DOCTYPE html>...<script>THREE.js code</script>...")
# 验证 3D 场景正确渲染

执行后端

环境	后端	说明
Cloud Sandbox	CDP on sandbox Chromium	通过 CDP 协议直接控制沙箱内浏览器
Desktop	Electron in-app browser	通过 WebSocket MCP 控制内置浏览器

与 chrome 的区别

维度	browser	chrome
环境	沙箱/受控浏览器	用户真实 Chrome
认证状态	干净（无登录态）	用户已登录
确认策略	不需要（沙箱隔离）	4 级确认
Tab 管理	AI 自由创建	需要 claim
风险	无（完全隔离）	真实世界操作
适用	公开页面、开发测试	认证工作流

高级用法

set_html（零服务器 HTML 注入）

browser(action="set_html", html="<html>...</html>")

通过 CDP Page.setDocumentContent 将 HTML 直接注入当前页面。无需 HTTP 服务器。适用于 3D demo、Widget 预览等场景。

viewport 自定义

browser(action="screenshot", url="http://localhost:5173",
        viewport_width=1920, viewport_height=1080)

全页截图

browser(action="screenshot", url="http://localhost:5173", full_page=true)

开始使用

核心概念

与专家对话

创作与自动化

插件工具

记忆与个性化

市场与内容

IM 渠道

账户与计费

团队版

技术揭秘

帮助

Browser Automation

Browser Automation

概述

可用 Actions

Screenshot 三种模式

1. URL 模式（已运行的页面）

2. HTML 注入模式（零服务器）

3. 文件路径模式（本地文件）

Accessibility Tree 工作流

使用示例

视觉验证（Sites 开发）

表单填写

3D 场景验证

执行后端

与 chrome 的区别

高级用法

set_html（零服务器 HTML 注入）

viewport 自定义

全页截图

​Browser Automation

​概述

​可用 Actions

​Screenshot 三种模式

​1. URL 模式（已运行的页面）

​2. HTML 注入模式（零服务器）

​3. 文件路径模式（本地文件）

​Accessibility Tree 工作流

​使用示例

​视觉验证（Sites 开发）

​表单填写

​3D 场景验证

​执行后端

​与 chrome 的区别

​高级用法

​set_html（零服务器 HTML 注入）

​viewport 自定义

​全页截图

Browser Automation

概述

可用 Actions

Screenshot 三种模式

1. URL 模式（已运行的页面）

2. HTML 注入模式（零服务器）

3. 文件路径模式（本地文件）

Accessibility Tree 工作流

使用示例

视觉验证（Sites 开发）

表单填写

3D 场景验证

执行后端

与 chrome 的区别

高级用法

set_html（零服务器 HTML 注入）

viewport 自定义

全页截图