> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Browser Automation
> browser(action=...) — DOM 感知浏览器自动化工具
# 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 模式（已运行的页面）
```python theme={null}
browser(action="screenshot", url="http://localhost:5173")
```
截取指定 URL 的页面。适用于有 dev server 运行的项目。
### 2. HTML 注入模式（零服务器）
```python theme={null}
browser(action="screenshot", html="Hello
")
```
通过 CDP `Page.setDocumentContent` 直接注入 HTML 并截图。无需启动任何服务器。
适用于快速验证生成的 HTML 片段。
### 3. 文件路径模式（本地文件）
```python theme={null}
browser(action="screenshot", file_path="/home/user/workspace/demo.html")
```
自动启动 `bun serve` 并截取指定文件。适用于包含本地资源引用的 HTML 文件。
## Accessibility Tree 工作流
推荐的交互模式是先获取元素 ref，再通过 ref 操作：
```python theme={null}
# 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 开发）
```python theme={null}
browser(action="screenshot", url="http://localhost:5173")
# 分析截图，发现布局问题
# 修改代码...
browser(action="screenshot", url="http://localhost:5173")
# 验证修复
```
### 表单填写
```python theme={null}
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 场景验证
```python theme={null}
browser(action="screenshot", html="......")
# 验证 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 注入）
```python theme={null}
browser(action="set_html", html="...")
```
通过 CDP `Page.setDocumentContent` 将 HTML 直接注入当前页面。无需 HTTP 服务器。
适用于 3D demo、Widget 预览等场景。
### viewport 自定义
```python theme={null}
browser(action="screenshot", url="http://localhost:5173",
viewport_width=1920, viewport_height=1080)
```
### 全页截图
```python theme={null}
browser(action="screenshot", url="http://localhost:5173", full_page=true)
```