Agent Browser 是一个通过受控浏览器来验证行为、采集证据或提取信息的技能，适用于静态抓取无法触及的网页场景，例如单页应用（SPA）、需要登录的页面以及动态渲染内容。其核心定位是“受监督的验证”，而不是无人值守的爬取。
一、适用场景 当需要以下操作时可以使用本技能：
- 对已部署页面或本地开发服务器截图，以确认 UI 变更；
- 读取 curl/wget 无法看到的 JavaScript 渲染内容；
- 用户报告 UI 缺陷时，通过交互方式复现，并捕获控制台错误、网络请求或布局状态；
- 走一遍简短流程（加载页面、点击、观察）以验证验收标准。
二、不适用场景 以下情况不应使用本技能：
- 页面本身可作为静态 HTML 访问时，应改用 curl/HTTP 抓取，更省资源、更快、更可靠；
- 无人值守的大规模爬取任务，应交给具备速率限制、robots.txt 处理和真实用户代理策略的专用爬虫；
- 站点处于你没有凭据的认证之后，或其服务条款禁止自动化；
- 涉及敏感账户（银行、医疗、政府）的站点，自动化可能带来锁定或合规风险。
三、启动浏览器前的准备
- 确认 URL 以及导航后应达到的状态；
- 确定需要哪些证据：整页截图、视口截图、控制台日志、网络追踪、HTML 快照、提取的文本；
- 确定任务所需的视口尺寸（移动端还是桌面端），除非任务专门针对移动端，否则默认使用桌面尺寸；
- 对于本地开发服务器，确认服务器正在运行且端口符合预期。
四、驱动浏览器 一次典型的验证会话包括：
- 当目标是公共互联网时，使用看起来真实的用户代理启动，不真实的 UA 会被标记为自动化流量；
- 设置合理的视口（例如 1366×768 桌面、390×844 类 iPhone）；
- 导航并等待正确的信号，优先等待特定选择器或网络空闲，而非任意 sleep；
- 在等待条件满足后立即采集证据，避免交互扰动状态；
- 有意识地交互，一次点击一步，动作之间等待，每次有意义的状态变化后重新截图；
- 查看控制台和网络面板，发现意外错误、4xx/5xx 响应或缓慢请求；
- 完成后干净地关闭浏览器，长时间运行的浏览器会话会泄漏内存并占用端口。
五、应记录的证据 验证任务应交付：
- 每个有意义状态的整页或视口截图；
- 过滤出警告/错误的控制台日志；
- 任何非 2xx 网络响应，包含 URL、状态码和简短响应体摘录；
- 简短叙述：“导航到 X，观察到 Y，点击 Z，观察到 W”。
UI 缺陷复现还应记录：
- 用户可遵循的精确复现步骤；
- 视口尺寸以及（相关时）设备像素比；
- 缺陷是在首次加载时复现，还是在交互后复现。
六、登录受限页面
- 优先使用程序化认证（API 令牌、魔法链接）而非 UI 登录；
- 如果只能通过 UI 登录，用户必须为本次运行明确提供凭据，绝不在会话之外复用凭据；
- 不要在会话日志、截图或返回输出中存储凭据。
七、性能与礼貌性
- 访问共享基础设施时，限制为每几秒一次导航；
- 对任何规模的公共站点检查都应遵守 robots.txt；
- 页面超过合理超时（如 30 秒）时取消导航，说明页面已损坏或正在限流；
- 失败时不要无限重试，延长超时重试一次后升级处理。
八、常见失败模式
- 找不到选择器：页面已变化，或在渲染前等待，截图查看实际状态并调整选择器；
- 点击无反应：元素在屏幕外、被模态框遮挡或位于 shadow DOM 中，滚动到可见区域或穿透 shadow root；
- 无头检测：部分站点检测无头 Chrome 并返回不同页面，仅在获授权时使用非无头模式或指纹拟真配置；
- 跨源 iframe 阻塞：不属于你的 iframe 无法检查，页面必须在 iframe 外提供数据，否则任务不可行。
九、反模式
- 长时间无人监督的浏览器会话，偏离原始任务；
- 在你没有凭据的认证之后进行爬取；
- 仅给截图标注“看起来不错”，而不说明加载了什么状态、哪些选择器确认了它；
- 把一张通过的截图当作在未实际测试的视口上也正确的证明。