browse

browse：面向 AI Agent 的浏览器与原生应用自动化

目标选择——务必先查看此部分

运行任何 browse 命令之前，先确定正确的目标：

用户想要……	目标	命令模式
打开 URL、测试网站、抓取网页内容	浏览器（默认）	browse goto <url>
测试本地开发服务器（localhost）	浏览器	browse goto http://localhost:3000
浏览会拦截机器人的网站（Cloudflare、Turnstile）	Camoufox	browse --runtime camoufox --headed goto <url>
使用特定的 camoufox 指纹配置浏览	Camoufox	browse --runtime camoufox --camoufox-profile <name> --headed goto <url>
搜索 Google、YouTube、Amazon 等	浏览器	browse goto @google "query"
与 iOS 应用交互（设置、Safari、自定义应用）	iOS 模拟器	browse --platform ios --app <bundleId> <cmd>
与 Android 应用交互（设置、Chrome、自定义应用）	Android 模拟器	browse --platform android --app <package> <cmd>
与 macOS 桌面应用交互（系统设置、文本编辑）	macOS 应用	browse --app <name> <cmd>
安装并测试 iOS .app 或 .ipa 文件	iOS 模拟器	browse sim start --platform ios --app ./MyApp.app --visible
安装并测试 Android .apk 文件	Android 模拟器	browse sim start --platform android --app ./app.apk --visible

关键规则：

• 不使用 --platform 或 --app 标志 → 浏览器目标（Chromium）。使用 goto 导航。
• --runtime camoufox --headed → 具有反检测能力的 Firefox。网站拦截普通浏览时使用。Turnstile/CAPTCHA 绕过模式请参阅 /browse-stealth 技能。
• goto URL 中的 @macro → 搜索宏展开。browse goto @google "query" 会展开为 Google 搜索 URL。共有 14 个宏：@google、@youtube、@amazon、@reddit、@wikipedia、@twitter、@yelp、@spotify、@netflix、@linkedin、@instagram、@tiktok、@twitch、@reddit_subreddit。
• 不带 --platform 的 --app → macOS 应用自动化。应用必须正在运行。
• --platform ios --app → iOS 模拟器。如果模拟器尚未运行，请先使用 browse sim start。
• --platform android --app → Android 模拟器。如果模拟器尚未运行，请先使用 browse sim start。
• 原生应用目标不支持：goto、js、eval、tabs、cookies、route、har。这些仅适用于浏览器。
• 所有目标均支持：snapshot、text、tap、fill、type、press、swipe、screenshot。
• 如果网站拦截你，切换到 --runtime camoufox --headed。如果仍被拦截，请使用 /browse-stealth 查看完整的 Turnstile 绕过模式。
• **如果不确定该使用哪个目标，请询问用户。**不要猜测——目标选错会浪费时间。

目标

使用持久运行的 browse CLI 来：

• 浏览真实网页
• 检查渲染后的内容和状态
• 与 UI 元素交互
• 捕获屏幕截图、控制台日志和网络活动
• 通过辅助功能 API 自动化原生应用（iOS、Android、macOS）
• 端到端验证浏览器或应用的行为，无需每一步都重新启动

步骤 0：确认是否可用并选择浏览模式

首先检查：

browse --version

如果未安装 browse：

• 停止
• 告知用户这是必需项
• 指引用户查看 references/commands.md 中的安装路径

然后确定需要哪种会话：

• 普通单 Agent 工作使用默认会话
• 并行 Agent 隔离使用 --session <id>
• 持久化浏览器身份使用 --profile <name>

对于原生应用目标，请先启动模拟器：

browse sim start --platform ios --app com.apple.Preferences --visible
browse sim start --platform android --app com.android.settings --visible
browse enable android    # first-time only: auto-installs adb, JDK, SDK, emulator
browse enable ios        # first-time only: builds iOS runner (needs Xcode)
browse enable macos      # first-time only: builds browse-ax bridge

成功标准：browse 可用，已确定目标（浏览器或原生应用），且所选会话/配置文件适合该任务。

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

使用 browse goto <url> 进行导航。

导航后，务必先等待页面稳定，再读取内容或进行交互：

• 对于常见页面和 SPA，使用 browse wait --network-idle
• 如果页面有已知信号，也可以使用更具体的 browse wait 条件

重要规则：

• 将 browse 作为 PATH 中的独立命令调用
• 不要使用 shell 变量作为 browse 命令前缀
• 避免使用 #id CSS 选择器；优先使用 [id=foo]
• 如果页面不可信，可考虑使用 --content-boundaries 和 --allowed-domains

成功标准：页面已充分加载，内容和交互状态都可靠。

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

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

• 使用 text 获取清理后的页面内容
• 使用 links 获取导航结构
• 使用 js 进行精确的定向提取
• 使用 console、errors 和 network 调试运行时问题
• 使用 snapshot -i 查看交互元素和稳定引用

对于交互繁多的任务，优先使用 snapshot -i，再考虑猜测选择器。

加载：

• references/commands.md 以获取准确的命令语法
• references/guides.md 以了解命令选择指南和速度规则

成功标准：你已获取所需信息，且没有浪费不必要的令牌或使用脆弱的选择器。

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

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

1. 优先使用 browse snapshot -i
2. 使用 @eN 引用进行交互
3. 仅当引用不可用或不实用时，才回退到 CSS 选择器

导航或 DOM 刷新后：

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

规则：

• 将描述性截图保存到 .browse/sessions/<id>/ 下
• 除非有意隔离，否则在同一会话中完成有状态流程
• 与 iframe 内容交互前先使用 frame

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

第 4 步：排查阻塞问题和特殊情况

遇到问题时：

• 使用 console 和 errors 排查页面或运行时问题
• 使用 network 查看请求
• 仅当任务需要模拟或故障模式测试时，才使用 route 或 offline
• 仅在遇到 CAPTCHA、MFA 或 OAuth 拦截等实际阻塞时，才使用有头浏览器或移交浏览器控制权

如果尝试几次后仍遇到阻塞：

• 加载 references/guides.md
• 严格遵循移交协议
• 任何人工接管流程开始前，先使用 AskUserQuestion

成功标准：阻塞问题已解决，或已按照正确的移交协议升级处理。

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

如果任务涉及验证，请收集最低限度的必要证据：

• 相关页面文本或结构化提取结果
• 涉及视觉内容时，提供截图路径
• 调试时提供控制台或网络检查结果
• 报告问题时，提供失败的具体步骤或选择器／引用

汇报以下内容：

• 导航到了哪里
• 执行了哪些操作
• 页面实际出现了什么情况
• 创建了哪些产物，例如截图、HAR 或视频

成功标准：其他工程师无需盲目重跑整个流程，就能理解观察到的浏览器行为。

重要规则

• 浏览器会在命令之间保持运行；Cookie、标签页和会话状态都会保留。
• 执行 goto 后，先等待，再读取内容或进行操作。
• snapshot -i 是默认的交互界面。
• 将截图保存到 .browse/sessions/<session-id>/ 或 .browse/sessions/default/ 下。
• 写入命令后，使用 --context delta 获取带引用的 ARIA 差异，使用 --context full 获取带引用的完整快照。
• 不要自动安装任何内容。
• 不要自动修改 Claude 设置；如果用户希望预先允许 browse 权限，请引导其查看 references/permissions.md。

何时加载参考资料

• references/commands.md 用于查询准确的命令语法、标志和扩展示例。

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

• references/permissions.md 当用户希望在 Claude 设置中预先允许浏览命令时使用。

防护规则

• 不要添加 disable-model-invocation；这是通用的浏览器验证技能。
• 不要添加 context: fork；通常需要在当前流程中使用浏览结果。
• 不要添加 paths:；这是通用工作流技能。
• 不要在 SKILL.md 中保留完整的 CLI 手册。
• 未经用户明确确认，不要运行 browse handoff。
• 不要将截图保存在浏览会话目录之外。

运行时选择

默认情况下，browse 使用 Playwright 驱动的 Chromium。其他运行时：

运行时	引擎	使用场景	安装
playwright（默认）	Chromium	常规浏览、测试	已包含
camoufox	Firefox（反检测）	带有机器人检测的网站	npm install camoufox-js && npx camoufox-js fetch
rebrowser	Chromium（隐身）	另一种隐身方案	npm install rebrowser-playwright
lightpanda	Lightpanda	快速无头渲染	参见 lightpanda.io
chrome	系统 Chrome	使用带扩展程序的真实 Chrome	必须安装 Chrome

browse --runtime camoufox --headed goto https://protected-site.com
BROWSE_RUNTIME=camoufox browse goto https://example.com

新功能

搜索宏

browse goto @google "best coffee beans"    # Google search
browse goto @youtube "tutorial"            # YouTube search
browse goto @amazon "laptop"               # Amazon search
browse goto @reddit "programming"          # Reddit search

所有宏：@google、@youtube、@amazon、@reddit、@reddit_subreddit、@wikipedia、@twitter、@yelp、@spotify、@netflix、@linkedin、@instagram、@tiktok、@twitch

安全标志（可选功能）

标志	默认值	功能
BROWSE_CONSENT_DISMISS=1	关闭	导航后自动关闭 Cookie 横幅
BROWSE_CLICK_FORCE=1 或 --force	关闭	强制点击，绕过覆盖层拦截
BROWSE_READINESS=1 或 --ready	关闭	goto 后等待页面完成水合
BROWSE_SERP_FASTPATH=1 或 --serp	关闭	提取 Google SERP DOM（速度快，不含引用）
BROWSE_COMMAND_LOCK=0	开启	禁用每个会话的命令串行化
BROWSE_CAMOUFOX_PROFILE=<name>	关闭	使用命名的 camoufox 配置文件（.browse/camoufox-profiles/<name>.json）

新命令

命令	描述
images [sel] [--limit N] [--inline]	列出页面图片及其 src/alt/尺寸
youtube-transcript <url> [--lang en]	通过 yt-dlp 或浏览器提取 YouTube 字幕
schema	提取 JSON-LD、Microdata、RDFa 结构化数据（解析后的 JSON）
meta	提取页面元标签（标题、描述、规范链接、OG、Twitter、hreflang、robots、viewport）
headings	提取 H1-H6 标题层级，包含计数和缩进树
profiles	列出 .browse/camoufox-profiles/ 中可用的 camoufox 配置文件

快照窗口化

大型快照（>80K 个字符）会自动分页：

browse snapshot -i                     # first page
browse snapshot -i --offset 500        # next page (line offset from previous output)

输出要求

报告：

1. 测试的页面或流程
2. 使用的会话/配置文件模式（如相关）
3. 执行的关键命令或交互
4. 观察到的结果
5. 任何产物或阻碍因素，例如截图、控制台错误、网络故障或移交状态