Browser Agent

---
name: browser-agent
description: 用 browser MCP(常驻 Playwright)操作浏览器:快照→找 ref→动→复验的循环。凡要"打开某网页点某钮/填表单/查下载"的任务,先读这份。
---

# Browser Agent 操作纪律

浏览器状态在服务进程手里,不在你这边。页签、Cookie、登录态、下载,
全由那只常驻 browser server 保管;你每回只拿到一份快照、一批 ref。
导航一次,generation 翻一页,旧 ref 即刻作废。纪律一条:**先快照,
再动手,动完再看一眼**。拿着旧 ref 乱点,是这条纪律的死罪。

## 开工三步

1. `browser_status`:确认引擎(chromium/webkit)、headless 与否、
   profile 目录。headless 下你**看不见画面**——别向用户描述"我看到的
   页面",你没看,你只读了快照。
2. `browser_open` 打开目标页(http/https;别的协议工具会拒,别绕)。
3. `browser_snapshot` 拿结构快照:可点/可填的元素各带一枚 ref。
   记下 page_id 与 generation——ref 只在这一次快照里有效。

## 动作

- `browser_click` / `browser_type` 都吃 snapshot 发的 ref,不吃坐标。
  快照里找不到目标元素,先想页面是不是没加载完(`browser_wait`),
  再想要不要滚动后重新快照——不许凭记忆猜 ref。
- 下拉框(`<select>`)用 `browser_select`(ref + value 或 label),
  快照里下拉行自带"选项: value=文本"清单,照单挑。别拿
  `browser_type` 往下拉里发箭头键——那是往框里打字,选不动下拉。
- 导航发生后(点链接、提交表单、跳转),**旧 ref 全部作废**,
  工具会报 `stale_ref`——这不是故障,是保护。重新 snapshot 拿新 ref。
- 同名元素多枚 ref 时工具会拒(目标不唯一):换更精确的描述重新定位,
  或用文本锚辅助,不许"挑第一枚试试"。
- 多页签:`browser_tabs` 列,`browser_select_tab` 切;每只页签自己的
  generation 各算各的。

## 复验

- 每次动作后 `browser_snapshot` 确认真发生了:按钮点了,看状态变没;
  表单交了,看 URL/内容变没。**没复验过的不说"已完成"**。
- 需要视觉判断(截图配色、布局对不对)时用 `browser_screenshot`
  拿图——注意当前会话若不是多模态模型,你读不了图,如实请用户人工核对。
- 报错查账:`browser_console`(须给 page_id)翻 Console journal,
  error 与未捕获异常都在册,每条带 seq 与 source 行列;`browser_network`
  翻 Network journal,failed 请求、状态码、耗时一目了然。两本账都是
  环形账,溢出明记 dropped,`since_seq` 可断线补账。审查页面先翻这两本,
  别只看页面表面。
- 下载:动作后 `browser_downloads` 对账,别只信页面提示"下载已开始"。

## 停手线

- 登录、支付、删数据、发帖这类不可逆动作:先向用户复述一遍将要点的
  东西(页面标题+按钮文字),得到明确许可再动。
- 密码框:工具侧永不回显密码值,你也别让用户把密码贴进对话——指路
  让用户在浏览器里自己输,你只做后面的步骤。
- 同一动作连败两次:停,报告页面上实际有什么,让用户指路。别换着
  花样盲试第三次。

## 收工

- 交代三笔账:动过哪些页(开/关)、下载了什么(文件名与路径)、
  登录态有没有动。没把握的如实说没验证。
- 审查类差事另缴证据:结论后头跟上 page_id 与 generation,报错引
  console 账的 seq,请求引 network 账的条目——没账的话就说没账,
  不编。