cnife 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 操作属于用户，注意边界。
规范
拿数据
- 挂监听：
page.on('response', handler)，按 URL 特征过滤数据接口。 - 触发请求：跳转、滚动、切 tab 都会发新请求，监听器持续捕获。
- 解析：
await resp.json()，先看响应形状，再取目标字段——避免一次拉全量费注意力。 - 只有数据接口拿不到（无网络请求、数据在服务端画好）才退回页面提取。
- 页面内容不完整（懒加载、分页、自动翻译）时，优先走数据接口拿原文全量，不要逐个处理画出来的问题。
- 时间过滤用数据接口的时间戳，不用页面上的相对时间。
- 空结果先判断再换路：接口返回成功（HTTP 200）但内容为空，可能是假空结果（内容被隐藏/删除）或平台故意少给数据，不是监听器问题——先确认请求确实发生、响应确实为空，再决定换路径。
看页面
- 用
observe/ariaSnapshot读结构，截图只用于外观验证。 - 页面内容与预期不符时，先检查语言/区域设置、登录态、视图切换。
操作页面
- 操作前确认目标存在且唯一（模糊匹配时先查再点，别点第一个）。
- 表单写入后必须验证：自动补全、受控输入框、掩码输入框会悄悄吞字符——type/fill 后读回值，select 后读回值。
- 自定义控件（非原生 select 的下拉/选择器）用"点触发器 → 点选项 → 验证"流程，不要当原生控件操作。
- 不要用 JS 提交表单：现代站点拦截，悄悄丢弃，用真实点击。
- 跳转或重画后重新获取元素标记，旧标记会失效或匹配错。
验证
- 数据任务：核对数据量与预期一致。
- 操作任务：验证状态变化。
- 页面与数据接口不一致时以数据接口为准。
排查
- 监听器没捕获到：先确认请求确实发生，再检查 URL 过滤条件。
- 滚动不加载：换键盘事件或直接跳转触发，或走数据接口拿全量。
- 操作没生效：确认元素存在、标记未失效、页面未跳转。
- 写入没生效：自动补全/受控输入吞字符，读回值确认。
- 同一步失败 2-3 次就换办法，不要一直重试。