Hyperbrowser

Hyperbrowser 同时提供单页 Scrape 与可 CDP 连接的云浏览器 Session。多数“把页面变成 markdown/HTML/链接”的任务，应先走 Scrape；只有登录后多步点击、复杂状态机或必须自己驱动 Playwright 时，再创建 Session。两条路径的完成标准不同：Scrape 看 data 里的目标格式是否齐全，Session 看脚本产物是否正确且会话已 stop。

用 startAndWait 跑通最小 Scrape

安装官方 SDK 后，用 API Key 初始化客户端，对公开页（文档示例常用 https://example.com）调用 scrape.startAndWait。底层是异步任务：POST /api/scrape 先返回 jobId，再轮询到 completed 或 failed（还有 pending / running）。成功响应应能读到 data.metadata（如 title）以及请求的格式内容；默认常取 markdown。先确认标题与正文段落覆盖你的字段清单，再谈代理和隐身。

按阻塞原因追加 sessionOptions

内容被地区限制或挑战页挡住时，再在同一次 Scrape 上附加 sessionOptions：如 useProxy、proxyCountry、useStealth / useUltraStealth、solveCaptchas。官方说明代理与验证码能力通常属于付费项，且会变慢，因此只在复现到真实阻塞后启用。也可设置 formats、waitFor、waitUntil、onlyMainContent 与标签过滤；截图里 fullPage 与 cropToContent 不能同时为 true。

Session 路径：连接、观察、停止

创建 Session 后检查 status 是否为 active，保存 id、wsEndpoint、liveUrl。Playwright 使用 connectOverCDP(session.wsEndpoint)，在默认上下文执行登录与导航；可用 liveUrl 人工盯盘。默认断开自动化连接往往会结束会话；若需跨断开保活，按文档在 WebSocket URL 追加 keepAlive=true，并注意关闭全部页面仍可能导致会话结束。无论成功失败，都在 finally 调用 sessions.stop(session.id)，再确认状态变为 closed。

固化参数版本与验收样例

把最终采用的 formats、sessionOptions、是否升级 Session，以及一份对照原页的 markdown/字段样例写进配置版本号。下次同类站点优先复用该版本；只有复现到新阻塞时才加代理或验证码项，避免每次任务都从零猜测参数组合。

1. 最小 Scrape 产出 metadata + markdown，并对照原页。
2. 记录缺失字段与是否出现挑战页。
3. 仅对确认阻塞追加会话参数并重试。
4. 仍不足则改 Session 脚本，保留 liveUrl 排障记录。
5. stop 会话，固化参数版本与验收样例。

入口：https://www.hyperbrowser.ai/ ，文档：https://docs.hyperbrowser.ai/