browser git:20260830.eb20a27A

Immutable. This exact content never changes and is served at /api/v1/blob/9f89393a9085289e.

---
name: browser
description: |
  操作和观察真实网页：导航、可访问性快照、UID 交互、对话框、文件上传、控制台、网络、截图、页面管理与受控脚本执行。
  适用于网页探索、表单交互、动态内容检查和浏览器自动化。
---

# Browser

函数签名、参数和返回值以当前工具 schema 为准。本文只说明稳定的操作方法。

## 交互循环

1. 进入或切换页面后，先取当前快照了解页面结构。
2. 优先用快照返回的 UID 点击、填写、悬停、拖放或上传文件，不用坐标猜测交互位置。
3. 页面导航、刷新、切换标签页或 DOM 显著变化后，重新取快照。
4. 工具结果已返回新快照时，直接使用它；不要为了“确认”立即再取一次快照。

## UID 时效

- UID 只属于生成它的那份快照。再次取快照后，旧 UID 失效。
- 拿到 UID 后立即使用，不要在中间插入另一次快照。
- UID 操作失败时，先检查页面是否已变化；如果已变化，用新快照重新定位，不反复重试旧 UID。

## 动态页面

- 已知目标文本时用 `waitFor` 等待；快照只有“加载中”、空列表或骨架屏时，等待页面实际变化后再观察。
- 点击可能打开新标签页时，先检查页面列表，再选择真正的目标页。
- 页面弹出 alert、confirm、prompt 或 beforeunload 时，先用 `handleDialog` 明确接受或拒绝，再继续操作。
- 快照足以完成操作时不执行脚本。只有需要读取快照不包含的 DOM 属性或结构化数据时，才使用脚本。
- 脚本返回值必须可 JSON 序列化。不返回 DOM 节点、函数或循环引用。

## 文件与调试观察

- `uploadFile` 只读取当前工作区或任务临时目录内的文件，传入其中的绝对路径。
- 用 `listConsoleMessages` / `getConsoleMessage` 检查页面日志和错误；用 `listNetworkRequests` / `getNetworkRequest` 检查请求、响应和可用正文。
- console/network 工具只观察浏览器已有数据，不用于重放请求或把正文写入文件。

## 视觉信息

可访问性快照无法表达布局、图表、画布或视觉状态时，再用截图补充判断。截图用于观察，不取代可验证的 UID/DOM 交互。