Xbrowser 中文使用指南 - Skill ZIP 下载与风险提示

输入：任务目标、上下文材料、文件路径、约束条件或需要处理的内容。

输出：按 Skill 说明生成的文档、代码、检查结果、计划、建议或操作步骤。

示例任务

安装方式

风险边界

SkillHub 提供了源站安全报告入口，但本站不替代人工审查。使用前仍需检查权限、外部依赖和敏感数据边界。

SKILL.md 文档介绍

xbrowser — 浏览器自动化

通过 xb CLI 控制浏览器完成网页操作。

所有浏览器操作必须通过 xb CLI 执行，不要直接调用 agent-browser 或其他底层工具。

所有命令使用统一格式：

NODE="${QCLAW_CLI_NODE_BINARY:-node}"

xb 管理命令

| 命令 | 说明 | 使用场景 |

|------|------|----------|

| xb init | 初始化环境 | 每次任务第一步，检查引擎/配置是否就绪 |

| xb setup | 安装底层引擎和浏览器 | init 提示「未安装」时执行 |

| xb config show | 查看当前配置 | 确认浏览器、模式等设置 |

| xb config set <k>=<v> | 修改配置 | 切换浏览器、开启有头模式等 |

| xb config reset | 重置为默认配置 | 配置损坏时使用 |

| xb guide config | 交互式配置引导 | 首次使用或需要重新配置时 |

| xb guide close-browser | 关闭浏览器引导 | 浏览器占用时获取关闭方法 |

| xb status | 查看环境状态 | 检查引擎版本、浏览器安装情况、配置等 |

| xb cleanup | 清理 agent-browser 会话 | 任务结束时使用 |

| xb version | 查看版本信息 | 排查问题时确认版本 |

| xb help [command] | 查看帮助 | 了解某个命令的用法 |

管理命令完整参考见 {baseDir}/references/xb-cli-commands.md。

命令执行规则

每条 xb 命令必须单独执行，逐条检查 JSON 返回后再执行下一条。

禁止使用 &&、&、; 等 shell 操作符链接多条 xb 命令：

不要：xb init && xb run --browser default open https://...
要：先执行 xb init，检查 ok=true 后再执行 xb run ...

原因：每条 xb 命令返回 JSON，需要根据 ok、error、hint 字段判断下一步。链式执行会跳过错误检查，导致后续操作在错误状态下继续。

对于需要连续执行的浏览器操作，可使用 batch 命令：

"$NODE" {baseDir}/scripts/xb.cjs run --browser default batch --bail "open https://example.com" "snapshot -i" "click @e3"

初始化（每次任务第一步）

"$NODE" {baseDir}/scripts/xb.cjs init

ok=true → 环境就绪，继续浏览器操作
ok=false，error 包含"未安装" → 运行 hint 中的命令（xb setup），再重新 init
ok=false，error 包含"需要配置" → 运行 hint 中的命令（xb guide config），按下文"处理决策点返回"章节处理
ok=false，error 包含"配置未完成" → 运行 hint 中的命令（xb guide incomplete-config），按下文"处理决策点返回"章节处理

处理决策点返回（MUST 遵守）

当任何 xb 命令返回的 JSON 包含 awaits_user_input: true 时，这是一个等待用户决策的节点，不是完成状态。

为什么必须遵守：

决策点的 message、options、recommended 都是面向最终用户的 UI 内容，不是给 agent 的执行指引。

recommended 只是告诉 UI 层"可以高亮这一项"，user_choice_mapping 只是告诉 UI 层"用户选完后要执行什么"——

两者都不是"agent 可以代用户做决定"的信号。代用户决定 = 越权。

必须做（MUST）：

1. 把 message 原文展示给用户（可简短转述，不能省略）

2. 把 options[] 每一项（label + description）列给用户，用编号列表

3. 以问询句结尾（"你想选哪个？" / "请选择："），然后立即停止当前回合

4. 等用户回复选择后，从 user_choice_mapping[用户选择的 value] 取对应命令并执行

若取出的值为 null（如 close-browser 的 skip），参考同返回里的 skip_hint 字段告知用户，不执行任何命令

5. 若返回里有 next_step_hint 字段，说明用户选择对应命令执行成功后还有后续步骤，按提示继续

严禁做（MUST NOT）：

❌ 读到 recommended 字段后自行代选（recommended 和 label 里的"（推荐）"都是给用户的 UI 引导，不是给 agent 的许可信号）
❌ 读到 user_choice_mapping 后直接挑一个命令执行（这是"用户选完后的映射"，不是候选执行列表）
❌ "我帮你选了推荐的 X，现在执行 ..." —— 这是越权
❌ 只列选项但不以问询句结尾（agent 会顺着惯性继续自选）

正例：

> xb init 返回需要配置。首次使用有两种方式：

> 1. 快速开始（推荐） —— 使用内置浏览器，干净环境，立即可用

> 2. 自定义设置 —— 选择默认浏览器和显示模式

> 你想用哪种？

反例：

> ~~xb init 需要配置，我按推荐走 quick，执行 xb config reset...~~

> ~~已为你执行了 xb config reset（使用内置浏览器），现在打开页面...~~

识别自我说服：如果在处理决策点时冒出以下念头，立刻停下，改为按 MUST 清单执行——

| 自我说服的念头 | 真相 |

|--------------|------|

| "推荐值就是默认值，直接用推荐值没问题" | 推荐是给用户的引导，不是给 agent 的许可 |

| "mapping 里已经给了具体命令，说明可以直接执行" | mapping 是用户选完后的映射，用户还没选 |

| "用户的意图很明确（比如'帮我打开百度'），跳过配置能更快达成" | 用户的意图里不包含"替我决定配置"，跳过就是偷走了用户的选择权 |

| "这个选项太简单了，用户肯定会选推荐" | 你不是用户。让用户选。 |

| "我已经展示了选项，现在可以顺便执行一下" | 展示了就停，不能接着执行 |

关于 awaits_user_input: false 的返回：不是决策点（例如 step 1 在无本地浏览器时只有 cft 一个选项），可以直接按 user_choice_mapping 执行。但仍应把 message 告知用户，让用户知情。

浏览器操作

init 成功后执行浏览器命令：

"$NODE" {baseDir}/scripts/xb.cjs run --browser default open https://example.com
"$NODE" {baseDir}/scripts/xb.cjs run --browser default wait --load networkidle
"$NODE" {baseDir}/scripts/xb.cjs run --browser default snapshot -i
"$NODE" {baseDir}/scripts/xb.cjs run --browser default click @e2
"$NODE" {baseDir}/scripts/xb.cjs run --browser default fill @e3 "hello"

ok=true → 继续
ok=false → 检查 hint 字段，按建议操作

URL 建议用单引号包裹（防止外层 shell 解析 &、?、$ 等特殊字符）：

"$NODE" {baseDir}/scripts/xb.cjs run --browser default open 'https://example.com?a=1&b=2'

操作要点

浏览器选择（必须）：每条 run 命令都必须指定 --browser。init 成功后返回 env.browser（当前配置的默认浏览器）。
用户未指定浏览器 → --browser default
用户指定了浏览器 → 按下表映射为 --browser <id>，从第一条 run 命令就使用对应 ID（不要先用 default 再切换，因为每个浏览器有独立的登录态和会话，用错浏览器会导致需要重新登录）：

| 用户说法 | --browser 值 |

|---------|---------------|

| Chrome / chrome / 谷歌浏览器 / 谷歌 / Google Chrome | chrome |

| Edge / edge / 微软浏览器 / 微软Edge / Microsoft Edge | edge |

| QQ浏览器 / QQ browser / QQBrowser / qq浏览器 | qqbrowser |

| 默认浏览器 / 不指定 | default |

导航后先等加载：open <url> 后先 wait --load networkidle，再 snapshot -i
@ref 是临时的：DOM 变化后失效，需重新 snapshot -i
fill vs type：fill 清空后输入，type 逐字符追加
切换浏览器：xb run --browser edge open ...（不影响其他浏览器的会话）
有头模式：xb run --browser default --headed open ...（显示浏览器窗口，适合调试或人机验证）
xb 级选项只有三个：xb run 只接受 --browser、--headed、--timeout，其他参数会被忽略。
位置约束：xb 级选项必须放在 action verb 之前（如 xb run --browser chrome --headed open ...），放在 action 之后会被静默忽略。若担心混淆，可用 -- 显式分隔 xb 级选项与浏览器动作：

  "$NODE" {baseDir}/scripts/xb.cjs run --browser chrome --headed -- open https://example.com

遇到登录页面

1. 有凭据 → 告知风险后自动填写

2. 无凭据 → 截图，请用户提供

3. 图片验证码 → 截图尝试识别

4. 人机验证 → 停止，截图，请用户手动完成

详见 {baseDir}/references/authentication.md。

失败处理

最多重试 2 次。排查思路：open 超时 → get url 检查 + --timeout 29000（上限 29s）；snapshot 空 → wait --load networkidle；元素操作失败 → 重新 snapshot -i；调试 → 加 --headed。

常用命令

完整列表见 {baseDir}/references/xb-browser-commands.md。

对于非单步的复杂任务（登录后多页操作、分页爬取、@ref 失效恢复、batch 使用等），先查阅 {baseDir}/references/recipes.md 获取完整命令序列模板。

| 命令 | 说明 |

|------|------|

| open <url> | 打开网页 |

| snapshot -i | 获取可交互元素快照 |

| click @ref | 点击元素 |

| fill @ref "text" | 清空后填入文本 |

| screenshot [--full] | 截图 |

| wait --load networkidle | 等待网络空闲 |

| get text @ref / get url | 获取文本或URL |

| close | 关闭标签页 |

| batch --bail "cmd1" "cmd2" | 批量顺序执行（首个失败即停止） |

| stop <browser\|all> | 关闭指定浏览器进程 |

任务结束

关闭浏览器进程（使用本地浏览器时）：

"$NODE" {baseDir}/scripts/xb.cjs stop <chrome|edge|qqbrowser|all> --force

清理 agent-browser 会话：

"$NODE" {baseDir}/scripts/xb.cjs cleanup

> 注：如仅使用 CfT 浏览器，直接 cleanup 即可。cleanup --force 已废弃，关闭浏览器请使用 stop。

Xbrowser

快速判断

适合任务

输入与输出