In App Browser

---
name: in-app-browser
description: 控制 Wevir 的内置浏览器：打开、导航、查看页面结构与可见状态、点击、输入、截图，以及测试本地的 Web 应用（localhost、127.0.0.1、::1、file://）和显示在 Wevir 里的网页。内置浏览器有自己独立的登录状态。要对链接指向的资源做语义操作（例如读写某个服务的数据）时，有专用的插件、API 或 CLI 就优先用它们。
---
<!--
Wevir 内置浏览器插件的技能说明草稿。工具一节按 Host 的 `browser_*` 应用工具写（browser-tools.ts、browser-batch.ts），
其余规则与实现无关。
Wevir 自己写的说明，做法参考了维护者提供的 Codex 桌面版浏览器插件资料，没有摘抄原文。
-->
# 内置浏览器

用这个技能做浏览器相关的工作：查看页面、导航、测试本地应用、点击、输入、截图、读取页面上可见的状态。

内置浏览器是 Wevir 桌面端里的一个浏览器，有自己独立的 cookie 与登录状态，和用户日常用的 Chrome 不共享。任务需要用户 Chrome 里已经登录的网站、已经打开的标签页或扩展时，用 Chrome 插件。

如果本会话列出了这个插件，做浏览器工作之前必须先按这份说明操作。不要在没试过它的情况下就说浏览器不可用，也不要直接退回到自己写的 Playwright 脚本或电脑操作。电脑操作的工具看起来更顺手，也不代表它是操作浏览器的首选。

## 什么时候让用户看到浏览器

默认在后台操作浏览器。

用户的请求主要是想把某个页面摆到眼前、或者想看着你操作时，把浏览器显示出来，例如“打开 localhost:3000”“去文档页”“带我看那个 PR”“给我看当前的标签页”“开着浏览器让我看你测下单流程”。

浏览只是回答问题或验证行为的手段时，不要显示，例如“看看 localhost:3000 的登录能不能用”“看一下文档页，总结改了什么”“确认弹窗还能正常打开”。本地地址和普通的页面跳转本身不构成显示的理由。

## 工具

工具的具体名称与参数以本回合提供的工具列表为准。显示或隐藏浏览器、刷新页面都要用对应的工具明确去做。

内置浏览器的工具是 `browser_*`：`browser_new_tab` 开一个自己的标签页（返回 `browserId`），`browser_snapshot` 读页面结构（可操作的元素带 `@e3` 这样的引用，跨站点的 iframe 也在里面），`browser_click`、`browser_fill`、`browser_type`、`browser_keypress`、`browser_select` 按引用操作，`browser_screenshot` 看视觉效果，`browser_wait` 等页面就绪。

### 一步一个工具，还是一次做多步

- **单个工具**：下一步要看上一步的结果才能决定时（还不知道页面长什么样、要从快照里挑元素、要看截图判断），一次调用一个工具。
- **`browser_batch`**：已经知道要做哪几步、中间不用看结果时，把它们放进一次调用，例如填完一个表单再点提交：`actions` 里每一项是 `{name, input}`，`name` 是上面的工具名，`input` 是那个工具的参数，`browserId` 写在外层一次就够。按顺序执行，哪一步出错就停在那里，结果逐步列出。全是只读步骤的批量不用用户批准，有会改页面的步骤时用户看到的是整串步骤。
- **`browser_run`**：步骤要按条件分支、循环、或要从页面上取数再算时，写一小段 JavaScript。脚本在隔离的沙箱里跑，只能用 `tab.snapshot()`、`tab.click(ref)`、`tab.fill(ref, value)`、`tab.wait(...)`、`tab.query(selector)` 这类函数（每个都要 `await`）和 `console.log`，没有 Node、文件和网络；用 `return` 交回结果。整段脚本一次批准，有总时限和调用次数上限。能用 `browser_batch` 做的不要写脚本。

### 少读快照

- 元素的引用在页面换文档之前不变，已经拿到的引用可以接着用。
- 页面变了以后再取快照时传 `changes: true`，只回和上一次比变了的行（`+` 新增、`-` 去掉），比整页短得多；没有可比的快照或变化太大时会自动给整页。
- 会改页面的工具（点击、填写、按键、导航、等待等）可以带 `snapshot: true`，做完直接附上变了的部分，省一次调用。

{{> plugins/shared/browser-operation.md }}

{{> plugins/shared/ui-action-confirmations.md }}