browse-stealth

browse-stealth：面向 AI Agent 的隐身网页自动化

目标决策 — 始终先检查这一项

运行任何 browse-stealth 命令前，先确认目标符合 stealth 的用途：

用户想要……	目标	命令模式
打开 Cloudflare/Turnstile 保护的网站	Camoufox	browse --runtime camoufox --headed goto <url>
绕过 Google“异常流量”拦截	Camoufox	browse --runtime camoufox --camoufox-profile google --headed goto @google "query"
抓取返回 403 或挑战页面的网站	Camoufox	browse --runtime camoufox --headed goto <url>
使用特定的 camoufox 指纹或代理配置	Camoufox	browse --runtime camoufox --camoufox-profile <name> --headed goto <url>
在隐身会话间保持登录状态	Camoufox + 浏览器配置文件	browse --runtime camoufox --camoufox-profile <n> --profile <p> --headed goto <url>
打开未被拦截的普通网站	默认浏览器	使用 browse 技能，而不是此技能
与 iOS/Android/macOS 应用交互	原生目标	使用 browse 技能，而不是此技能

关键规则：

• --runtime camoufox 选择经强化的 Firefox 引擎，支持 C++ 级指纹伪装。
• 强烈建议使用 --headed。无头 Firefox 更容易被检测到。
• --camoufox-profile <name> 会加载 .browse/camoufox-profiles/<name>.json。此设置仅在服务启动时应用——切换配置前先运行 browse stop。
• --profile <name> 会在重启后保留浏览器 Cookie/localStorage。它与 --camoufox-profile 相互独立。
• 切勿同时使用 --profile 和 --session。 --profile 用于保留身份；--session 用于在同一服务中隔离并行 Agent。
• 隐身功能无法替代 IP 信誉。 单靠指纹伪装无法绕过基于 IP 的拦截。对于防护严格的网站，请使用住宅代理。
• 如果网站无需隐身即可正常加载，请切回 browse 技能。 Camoufox 速度较慢。
• 如果不确定该使用哪个目标，请询问用户。 不要猜测。

目标

使用持久化的 browse CLI 和 camoufox runtime，以便：

• 访问会拦截普通浏览器的网站
• 通过 Cloudflare Turnstile 和类似的反机器人挑战
• 检查受保护页面上渲染的内容和状态
• 与 UI 元素交互，同时避免触发检测
• 捕获屏幕截图、控制台日志和网络活动
• 在重启后保持已验证的会话
• 针对每项任务轮换代理和指纹

步骤 0：检查可用性并选择隐身配置

首先检查：

browse --version
browse --runtime camoufox doctor

如果未安装 browse，请停止并告知用户：

使用以下命令安装：npm install -g @ulpi/browse

如果未安装 camoufox，请停止并告知用户：

使用以下命令安装：npm install camoufox-js && npx camoufox-js fetch

不要自动安装任何内容。

然后，选择适合任务的隐身配置。运行 /browse-config 生成配置，或选择现有预设：

预设	适用场景
stealth	通用反检测（geoip + humanize）
google	Google 搜索、SERP 抓取（geoip + humanize + 随机 OS）
scrape	高吞吐量抓取（拦截图片、WebRTC、WebGL；启用缓存）
custom	由用户逐项选择设置

然后，确定所需的会话类型：

• 普通单 Agent 工作使用默认会话
• 并行 Agent 隔离时使用 --session <id>（共用同一个 camoufox 服务）
• 持久化浏览器身份（重启后仍保留 Cookie）时使用 --profile <name>

成功标准：browse 和 camoufox 均可用；已选定隐身配置；会话/浏览器配置文件的选择符合任务需求。

步骤 1：安全导航并稳定页面

停止所有正在运行的服务（切换 --camoufox-profile 时必须执行），然后启动：

browse stop
browse --runtime camoufox --camoufox-profile <name> --headed goto <url>

如果不存在命名配置文件，则会自动使用 browse.json 中的 camoufox 部分：

browse stop
browse --runtime camoufox --headed goto <url>

导航完成后，务必先稳定页面，再进行读取或交互：

• 对于常见页面和 SPA，使用 browse wait --network-idle
• 或者在页面有已知信号时，使用条件更具体的 browse wait

重要规则：

• 将 browse 作为 PATH 中的裸命令调用
• 不要使用 shell 变量设置 browse 命令前缀
• 避免使用 #id CSS 选择器；优先使用 [id=foo]
• 后续命令始终传入 --runtime camoufox，或在环境中设置 BROWSE_RUNTIME=camoufox
• BROWSE_CONSENT_DISMISS=1 会自动关闭 Cookie 横幅（适用于欧盟地区）

成功标准：受保护的页面已加载，挑战（如有）已完成，且内容可靠。

步骤 2：选择成本最低且有效的检查方法

使用能解答问题的最轻量命令：

• 使用 text 获取清理后的页面内容
• 使用 links 获取导航结构
• 使用 js 精确提取目标内容
• 使用 console、errors 和 network 调试运行时
• 使用 snapshot -i 获取交互元素和稳定引用
• 在 Google 上使用 --serp，无需引用即可按 SERP 结构提取内容

对于交互密集型任务，优先使用 snapshot -i，再尝试选择器。

加载：

• /browse 参考资料，了解完整命令语法（browse 技能中的 references/commands.md）
• /browse 参考资料，了解速度规则（references/guides.md）

成功标准：无需消耗不必要的 token 或使用脆弱的选择器，即可获得所需信息。

步骤 3：优先使用 refs 进行交互，其次使用选择器

对于点击、填写、勾选、选择等操作：

1. 优先使用 browse --runtime camoufox snapshot -i
2. 使用 @eN refs 进行交互
3. 仅在 refs 不可用时才回退到 CSS 选择器

导航或 DOM 刷新后：

• 假设 refs 可能已失效
• 继续操作前重新获取快照

规则：

• 在配置文件中启用 humanize: true（或更高数值，如 1.5–2.0），以产生类似真人的延迟
• 将描述性截图保存到 .browse/sessions/<id>/ 下
• 除非有意隔离，否则在同一会话中完成有状态流程
• 与 iframe 内容交互前先使用 frame（Turnstile 位于 iframe 中）

成功标准：交互稳定、不易被检测，并且与当前渲染的页面状态相对应。

步骤 4：调试阻碍和特殊情况

遇到问题时：

• 使用 console 和 errors 检查页面或运行时问题
• 使用 network 查看请求（查找挑战端点）
• 检查 src 中包含 challenges.cloudflare.com 的 iframe（Turnstile）
• 检查是否出现“unusual traffic”或“verify you are human”等文本

网站仍然拦截访问时，按以下顺序升级隐匿措施：

1. 提高 camoufox 配置文件中的 humanize 数值（尝试 1.5 或 2.0）
2. 切换 OS 指纹（设置 os: ["windows", "macos", "linux"] 以随机选择）
3. 在配置文件中添加住宅代理，然后运行 browse stop 并重新启动
4. 如果之前以无头模式运行，则使用 --headed
5. 最后，可通过 browse handoff 将操作交给用户——先用 AskUserQuestion 询问

如果网站在某个时刻能够正常加载，则剩余任务改用默认的 browse 技能。

成功标准：要么在隐匿运行时中解决阻碍，要么按照正确的移交流程升级处理。

第 5 步：收集证据并清晰报告

如果任务涉及验证，请收集所需的最少证据：

• 相关页面文本或结构化提取结果
• 视觉内容相关时的截图路径
• 调试时的控制台／网络发现
• 报告问题时失败的确切步骤或选择器／ref
• 如果与复现相关，记录所用的 camoufox 配置文件和代理

报告以下内容：

• 你访问了什么页面
• 使用了哪个 camoufox 配置文件和浏览器配置文件
• 执行了哪些操作
• 页面实际发生了什么（包括检测到的挑战）
• 创建了哪些产物，例如截图、HAR 或视频

成功标准：其他工程师使用相同的配置文件和代理，可以复现观察到的隐蔽行为。

重要规则

• 浏览器会在命令之间保持运行；Cookie、标签页和会话状态都会保留。
• 执行 goto 后，请先等待，再读取内容或进行操作。
• snapshot -i 是默认交互界面，与常规 browse 技能相同。
• --camoufox-profile 仅适用于启动服务时——切换配置文件前，必须先执行 browse stop。
• humanize 会为点击和输入添加随机延迟。设置为 true 或数字（0.5–2.0）。
• geoip 会根据出口 IP 伪装位置。与代理结合使用时，时区／语言区域／地理位置将根据代理 IP 确定。
• 强烈建议使用有头模式——无头 Firefox 更容易被检测到。
• IP 信誉很重要——仅伪装指纹无法绕过基于 IP 的封锁。
• 切勿混用 --profile（持久化浏览器）和 --session（共享多路复用）。
• 将截图保存到 .browse/sessions/<session-id>/ 或 .browse/sessions/default/。
• 不要自动安装任何内容。
• 不要自动修改 Claude 设置；请引导用户参阅 browse/references/permissions.md。

何时加载参考资料

• browse/references/commands.md 用于查阅准确的命令语法、标志和扩展示例——所有内容均适用于 --runtime camoufox。

• browse/references/guides.md 用于了解速度规则、命令选择指南、架构说明，以及强制执行的 CAPTCHA／MFA 交接协议。

• browse/references/permissions.md 用于用户希望在 Claude 设置中预先允许 browse 命令时。

防护规则

• 不要添加 disable-model-invocation；用户提出要求时，隐蔽功能应保持可用。
• 不要添加 context: fork；通常需要在当前流程中使用隐蔽操作的结果。
• 不要添加 paths:；这是通用工作流技能。
• 不要在此处保留完整的 CLI 手册；请指向 browse 技能的参考资料。
• 不要自动安装 camoufox、代理或系统依赖项。
• 未经用户明确确认，不要运行 browse handoff。
• 不要将截图保存到 browse 会话目录之外。
• 最终报告中不要包含代理凭据或会话 Cookie。

隐蔽操作手册

针对最常见封锁情况的具体操作模式。每个操作手册都适用于上文第 1–5 步。

Cloudflare Turnstile

识别挑战：

browse --runtime camoufox --headed goto https://target-site.com/login
browse --runtime camoufox snapshot -i

查找 src 中包含 challenges.cloudflare.com 的 iframe、标签为“验证您是人类”的复选框，或类名／ID 中包含 cf-turnstile 的元素。

等待自动解决（humanize 通常可以通过验证）：

browse --runtime camoufox wait --network-idle
browse --runtime camoufox snapshot -i

如果挑战仍然存在，请使用对应的 ref 点击复选框，然后重新执行快照。如果仍然受阻，将 humanize 调高至 2.0，执行 browse stop，然后重新启动。

绕过 Google“异常流量”封锁

使用 Google 安全配置文件（geoip + humanize + random OS）：

browse stop
browse --runtime camoufox --camoufox-profile google --headed goto @google "your query"
browse --runtime camoufox wait --network-idle
browse --runtime camoufox snapshot -i

如果出现同意对话框，请处理它（点击 Accept 对应的 ref）。在查询之间添加 browse wait --network-idle，以避免触发速率限制。如果仍然受阻，说明 IP 已被标记——请切换到住宅代理。

已认证的会话

将 --camoufox-profile（指纹）与 --profile（Cookie）结合使用：

browse stop
browse --runtime camoufox --camoufox-profile stealth --profile mysite --headed goto https://target-site.com/login
# log in once through the normal flow

后续使用相同 --profile 启动时，无需再次登录：

browse stop
browse --runtime camoufox --camoufox-profile stealth --profile mysite --headed goto https://target-site.com/dashboard

对于自动化流程，请使用凭据保险库（browse auth save / browse auth login）——切勿将凭据粘贴到命令行参数中。

代理轮换

每个代理都使用单独命名的 camoufox 配置文件：

.browse/camoufox-profiles/proxy-us.json
.browse/camoufox-profiles/proxy-eu.json
.browse/camoufox-profiles/proxy-asia.json

配置文件示例：

{
  "geoip": true,
  "humanize": true,
  "proxy": {
    "server": "http://proxy:8080",
    "username": "user",
    "password": "pass"
  }
}

停止服务并使用不同的配置文件重新启动，即可切换区域：

browse stop
browse --runtime camoufox --camoufox-profile proxy-eu --headed goto <url>

每次切换都需要重启，因为代理是在浏览器启动时配置的。

输出约定

报告以下内容：

1. 测试的页面或流程
2. camoufox 配置文件（以及使用的浏览器配置文件）
3. 代理区域（如适用）
4. 执行的关键命令或交互
5. 观察到的结果，包括遇到的任何验证挑战
6. 任何产物或阻碍，例如截图、控制台错误、网络故障或交接状态