# Browser Ops Skill

> 当用户要求对具体网页做页面级交互时触发：登录、填表、点按钮、翻页抓取、截图、下载页面图片、处理验证码或反爬、访问 SPA 动态内容；也用于 WebFetch 拿到空壳或被风控后的降级。典型说法"帮我登录 X 然后抓 Y"、"截个图"。**不用于**：事实性问题或"xx 是什么"（→`WebSearch`）、单纯读取静态网页文本（先试 `WebFetch`）。

- Skill: `openloaf/browser-ops-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openloaf/browser-ops-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openloaf/browser-ops-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openloaf (https://skillmd.com/u/openloaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openloaf/browser-ops-skill

---


# 浏览器操作指南

## 工具清单

| 工具 | 职责 | 只读 |
|------|------|------|
| `OpenUrl` | 打开网页（headless / tab / window 三模式） | 是 |
| `BrowserSnapshot` | 一次拿到页面文本 + 交互元素列表 + 截图 + rawHtml | 是 |
| `BrowserAct` | 页面交互（点击 / 输入 / 滚动 / 按键） | 否 |
| `BrowserWait` | 等待页面状态（load / networkidle / url / text / timeout） | 是 |
| `BrowserDownloadImage` | 下载页面中的图片到本地 | 否 |

> **加载**：全部为 deferred 工具，调用前须先 `ToolSearch(names: "OpenUrl,BrowserSnapshot,BrowserAct,BrowserWait,BrowserDownloadImage")` 激活 schema。

## 核心心智模型

浏览器操作 = **观察-行动-验证** 循环。每次操作后必须 snapshot 确认状态，因为网页是有状态的——点击可能触发导航、弹窗、AJAX 加载，你无法预测结果。盲目连续操作是最常见的失败原因。

```
OpenUrl → BrowserSnapshot → 分析 → BrowserAct → BrowserWait → BrowserSnapshot → ...
```

## OpenUrl 打开模式

- **`headless`** — 纯自动化首选。无 UI，适合抓取、后台 Agent、批量操作。
- **`tab`（默认）** — 用户需要看到/操作页面时用。内嵌面板。
- **`window`** — 用户需要独立窗口深度交互时用。

**速记**：用户不需要看 → `headless`；用户要看 → `tab`；用户要独立窗口 → `window`。

## BrowserSnapshot 说明

BrowserSnapshot 一次调用返回：
- **页面信息**：URL、标题、readyState
- **全量文本**：body.innerText（截断 32KB）
- **交互元素列表**：最多 120 个可点击/可输入元素及其 selector
- **iframe 内容**：同源 iframe 的文本和元素
- **截图**：默认截取完整页面（fullPage），保存到会话资源目录
- **rawHtmlPath**：完整 outerHTML 存盘路径

**文本超 32KB 怎么办？** 用 `Read`/`Grep` 读 `rawHtmlPath` 获取完整 DOM，不要反复调 BrowserSnapshot 重抓。

**截图控制**：`fullPage: false` 仅截取当前可视区域。

## 三大核心工作流

### 工作流 1：信息提取

`OpenUrl` → `BrowserWait { type: "load" }` → `BrowserSnapshot`

直接从返回的文本中提取所需信息。

翻页抓取：`BrowserSnapshot` → `BrowserAct { action: "click-text", text: "下一页" }` → `BrowserWait { type: "networkidle" }` → 循环。每页都要 snapshot。

### 工作流 2：表单填写与登录

1. `OpenUrl` → `BrowserSnapshot` 看表单结构和 selector
2. 对每个字段 `BrowserAct { action: "fill", selector: "...", text: "..." }`
3. 提交：`BrowserAct { action: "click-css", selector: "button[type=submit]" }`
4. `BrowserWait { type: "urlIncludes", url: "/success" }` 确认成功
5. `BrowserSnapshot` 最终确认

**fill vs type**：`fill` 原子性地清空+输入，适合表单；`type` 在当前焦点追加字符，适合搜索框。

**登录注意**：Cookie 在会话期间持久，登录一次后续自动带认证。**不要** snapshot 密码字段。

### 工作流 3：截图与图片下载

- `BrowserSnapshot` — 快照 + 完整页面截图（默认 fullPage）
- `BrowserSnapshot { fullPage: false }` — 仅可视区域
- `BrowserDownloadImage { selector: ".product-image" }` — 下载页面中的图片

截图是调试利器：文本看不出问题时，看截图一目了然。

## Selector 选择策略

从 BrowserSnapshot 返回的元素列表中选择 selector，**不要自己猜**。

优先级：`#id` > `[data-testid]` > `input[name]` > `.class` > `click-text`

## 等待策略

- **`load`**：传统页面导航后用
- **`networkidle`**：SPA/AJAX 页面首选，最安全但最慢
- **`urlIncludes`**：表单提交后等待跳转
- **`textIncludes`**：等待异步加载的内容
- **`timeout`**：最后手段

## 错误诊断

**元素未找到？** → BrowserSnapshot 确认页面状态 → 可能已导航到别处 → 可能在视口下方（scroll 后再试）→ 可能在 iframe 中（不支持跨 iframe）

**页面加载超时？** → BrowserSnapshot 看加载到哪了，可能内容已够用

**操作没反应？** → 页面没加载完（加 BrowserWait）→ selector 匹配了错误元素（snapshot 检查）→ 弹窗遮挡（先关闭）

**SPA 内容为空？** → `BrowserWait { type: "networkidle" }` 后再 snapshot → 还是空则 `textIncludes` 等具体内容

## CAPTCHA 与反爬

遇到验证码、403/429、反机器人页面时**立即停止并告知用户**，不要盲目重试。

## 铁律

1. **每次操作后 BrowserSnapshot 验证状态**
2. **先 snapshot 再行动**，不要猜 selector
3. **等待页面就绪后再操作**
4. **文本不够看截图**
5. **不要暴露敏感信息**（密码填写后不要 snapshot）
6. **遇到反爬立即停止**