# Browser Guide

> 用 omp browser 工具做网页数据提取、抓取、自动化操作时加载

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

---


# browser-guide

本技能把使用 omp browser 的通用方法前置：任务分类、成本意识、状态管理、能力分层。

## 心智模型

### 任务分类：先问"我要做什么"

浏览器任务分三类，决定从哪层开始：

- **拿数据** → 数据接口：挂 `page.on('response')` 抓接口响应。页面上的文字是画出来的，不是数据本身。
- **看页面** → 页面结构：`observe` 拿无障碍树，`ariaSnapshot` 拿 ARIA 结构。
- **操作页面** → 交互：`click`/`type`/`select`/`press`。

别默认从页面开始——任务类型决定层，不是工具列表决定路径。

### 成本意识：看页面贵，操作便宜

- 每次 observe/截图/读页面都消耗 AI 的注意力，操作本身便宜。
- 一次拿全量：循环、批量、数据处理在 `code` 里一次写完，不拆多轮。
- 等条件用 `wait(fn)` 轮询、等响应用 `waitForResponse`，不固定 sleep。
- 每页调用超过 10 次说明你在慢慢抠数据，不是正常操作——考虑走数据接口或一次 code 拿全量。
- 截图是给人类看的：费注意力、信息少，除非页面真是视觉的（验证码、图表）。

### 状态管理：页面是活的

- tab 跨调用存活，页面随时会变（跳转、局部更新、重画）。
- 操作前确认状态，操作后验证结果。
- 元素标记会失效，重画后重新获取。
- 更危险的是悄悄匹配错：页面变化后旧标记可能匹配到新页面上形状相似的元素——跳转后不要复用旧标记。

### 以实际页面为准

- 文档、经验、预期都是参考，实际页面才是事实。
- 页面与预期不符时，先检查登录态、语言/区域、视图切换、A/B 测试，再决定下一步。
- 不要因为"文档说应该这样"而继续按预期操作。

### 能力分层：从够用的最低层开始

- tab helper → page（完整 Puppeteer）→ `code`（全 Node）→ relay（用户真实浏览器）。
- helper 不够就换用更底层的能力，别硬凑。
- relay 操作属于用户，注意边界。

## 规范

### 拿数据

1. 挂监听：`page.on('response', handler)`，按 URL 特征过滤数据接口。
2. 触发请求：跳转、滚动、切 tab 都会发新请求，监听器持续捕获。
3. 解析：`await resp.json()`，先看响应形状，再取目标字段——避免一次拉全量费注意力。
4. 只有数据接口拿不到（无网络请求、数据在服务端画好）才退回页面提取。
5. 页面内容不完整（懒加载、分页、自动翻译）时，优先走数据接口拿原文全量，不要逐个处理画出来的问题。
6. 时间过滤用数据接口的时间戳，不用页面上的相对时间。
7. 空结果先判断再换路：接口返回成功（HTTP 200）但内容为空，可能是假空结果（内容被隐藏/删除）或平台故意少给数据，不是监听器问题——先确认请求确实发生、响应确实为空，再决定换路径。

### 看页面

- 用 `observe`/`ariaSnapshot` 读结构，截图只用于外观验证。
- 页面内容与预期不符时，先检查语言/区域设置、登录态、视图切换。

### 操作页面

- 操作前确认目标存在且唯一（模糊匹配时先查再点，别点第一个）。
- 表单写入后必须验证：自动补全、受控输入框、掩码输入框会悄悄吞字符——type/fill 后读回值，select 后读回值。
- 自定义控件（非原生 select 的下拉/选择器）用"点触发器 → 点选项 → 验证"流程，不要当原生控件操作。
- 不要用 JS 提交表单：现代站点拦截，悄悄丢弃，用真实点击。
- 跳转或重画后重新获取元素标记，旧标记会失效或匹配错。

### 验证

- 数据任务：核对数据量与预期一致。
- 操作任务：验证状态变化。
- 页面与数据接口不一致时以数据接口为准。

## 排查

- 监听器没捕获到：先确认请求确实发生，再检查 URL 过滤条件。
- 滚动不加载：换键盘事件或直接跳转触发，或走数据接口拿全量。
- 操作没生效：确认元素存在、标记未失效、页面未跳转。
- 写入没生效：自动补全/受控输入吞字符，读回值确认。
- 同一步失败 2-3 次就换办法，不要一直重试。