browserforce

BrowserForce — 你的真实 Chrome 浏览器

BrowserForce 为你提供用户实际使用的 Chrome 浏览器——所有登录状态、 Cookie 和扩展程序都已启用。没有无头浏览器，也没有全新配置文件。

先决条件

用户必须：

1. 安装并连接 BrowserForce Chrome 扩展程序（绿色图标）
2. 中继服务会在首次执行命令时自动启动——无需手动操作

使用 browserforce status 检查。

优先使用命令

会话命令会在 CLI 调用之间共享同一个持久浏览器会话（包括当前活动标签页 和快照引用）。MCP browserforce 工具也使用相同的命令语言：

browserforce tabs                # List tabs: stable t<N> handles + names
browserforce use t2              # Switch the active tab
browserforce open <url> --as docs  # Open a new tab, optionally named
browserforce snapshot            # Accessibility tree + @eN refs
browserforce click @e2           # Act on a ref from the last snapshot
browserforce screenshot [n]      # Screenshot tab n (PNG to stdout)
browserforce -e "<code>"         # Raw Playwright JavaScript (one-shot escape hatch)

只有在命令层无法表达任务时才使用 -e。

在光标上标注你的名字

如果用户启用了幽灵光标，光标会显示当前由哪个 Agent 操作—— 但前提是你说明自己的身份。执行任何命令前，请导出此变量：

export BROWSERFORCE_AGENT_NAME="Claude"

最多 24 个字符，允许使用：A-Z a-z 0-9 space . _ -。其他字符会被 剥除（而不是拒绝），连续空白会合并，超长名称会被截断， 清理后为空的名称则不会显示标签。请选一个不会被改动的名称。

如果要与其他 Agent 共用机器，还要导出一个独立的 BF_SESSIOND_LOCK_PATH=/tmp/bf-<your-name>.json。每台机器上的所有 CLI 调用方 共用一个会话守护进程和一条连接，其名称取自启动它的环境，因此如果你没有自己的 守护进程，你的点击操作会被归到第一个 Agent 的名称下。

核心工作流：观察 → 操作 → 观察

browserforce open https://example.com/login
browserforce snapshot                      # find the email/password/submit refs
browserforce fill @e3 "[email protected]"
browserforce fill @e4 "hunter2"
browserforce click @e5
browserforce wait url "**/dashboard"
browserforce snapshot                      # verify the result

页面一旦发生变化，引用就会过时——下一次使用引用进行交互前，务必重新获取快照。

多标签页操作

browserforce open https://docs.example.com --as docs
browserforce open https://app.example.com --as app
browserforce snapshot --tab app            # read app without switching tabs
browserforce click @e2 --tab app
browserforce use docs                      # or switch the active tab

通过稳定句柄（t2）或名称定位标签页——切勿按列表位置定位。标签页 名称必须唯一；只有在你有意将名称移到另一个标签页时，才传入 --replace。

稳定句柄和名称在整个会话期间都会保留；使用 browserforce tabs 查找它们。句柄在 空闲后重新连接时仍然有效；只有执行 reset 才会使其失效。

将浏览器操作交给子 Agent

子 Agent 会自动共享你的浏览器会话——每台机器上只有一个守护进程，因此它们无需设置 就能看到你的标签页、登录状态和快照引用。将以下其中一段粘贴到子 Agent 的提示词中。

顺序执行的子 Agent。 它们共享你的活动标签页：

浏览器：使用 browserforce CLI。它已连接到用户的真实 Chrome，并共享此会话的标签页。运行 browserforce tabs 查看标签页， 运行 browserforce use <handle> 选择一个，然后执行 snapshot / click @eN / fill @eN <text>。

并行执行的子 Agent。 为每个子 Agent 分配独立 ID，它们各自拥有自己的活动标签页：

浏览器：使用 browserforce CLI，并导出 BROWSERFORCE_CLIENT_ID=<your-name>。 你与其他 Agent 共享会话中的标签页和登录状态，但活动标签页是你自己的——use 和 open 不会切换它们的标签页。

如果客户端无法设置 ID，则为每次运行固定指定标签页：在 snapshot、click、fill、type、press、hover、 wait、get 和 eval 命令中传入 --tab <handle>，并且不要运行 use 或 open。tabs 无需 --tab，也不接受该参数。

需要保持独立会话的子 Agent。 为它配置独立的守护进程：

浏览器：使用 browserforce CLI，并导出 BF_SESSIOND_LOCK_PATH=/tmp/bf-<name>.json 和 BROWSERFORCE_CDP_CLIENT_LABEL=<name>。你将获得独立的会话 状态，并拥有自己的 Chrome 窗口，供你创建标签页。

最后一种方式会隔离会话状态，并决定新标签页的打开位置。它不是 沙盒：每个 BrowserForce 客户端都能查看和操作浏览器中的所有标签页。如果某个标签页 不能被操作，就不要委派会触及该标签页的任务。

句柄（t<N>）在整个会话期间保持稳定，因此你传给子 Agent 的句柄在它运行时 仍会指向同一个标签页。

命令参考

browserforce snapshot [--tab docs] [--selector "#main"] [--search "login"] [--interactive]
browserforce hover @e3                         # Hover a ref
browserforce type @e2 "more text"              # Type without clearing
browserforce press Enter                        # Send a key
browserforce wait text "Saved"                  # Wait for text
browserforce wait url "**/dashboard"            # Wait for a URL glob
browserforce wait load domcontentloaded          # Wait for a load state
browserforce wait fn "window.ready === true"    # Wait for a JavaScript predicate
browserforce get url|title                      # Read the current page
browserforce get text|html @e5                  # Read a referenced element
browserforce eval --stdin                       # Run piped JS in the persistent session
browserforce rename docs api-docs                # Rename a tab
browserforce forget api-docs                     # Remove a tab name
browserforce run "click @e2 --tab docs"         # Run a command string

Refs 可使用 @e1、e1 或 ref=e1。Ref/read 命令支持 --tab <handle|name|text>，且不会更改当前活动标签页。eval 使用与 MCP exec 相同的受保护边界；它会公开 page、context、state 和 snapshot()，并且 state 会在会话命令之间持久保留。添加 --json 可获取机器可读的命令结果。

提取数据

browserforce get url                       # current URL
browserforce get text @e5                  # text content of a ref
browserforce get html @e5                  # innerHTML of a ref
echo "return await page.title();" | browserforce eval --stdin

一次性 -e（应急方式）

每次调用 browserforce -e 都是独立的（状态不会在多次 -e 调用之间持久保留）。请在单个代码片段中完成所有操作：

browserforce -e "
  state.page = await context.newPage();
  await state.page.goto('https://example.com');
  await waitForPageLoad();
  return await snapshot();
"

规则

1. 优先使用 snapshot，而非 screenshot — snapshot 返回文本（速度快、成本低）；仅在验证视觉布局时使用 screenshot。
2. 每次页面更改后都重新获取 snapshot — refs 会立即失效。
3. 不要跳转现有标签页 — 通过 browserforce open 打开自己的标签页。
4. 优先使用命令，而非 -e — 仅当命令层无法表达任务时，才使用原始 Playwright。
5. 命令错误会提示下一步操作 — ref 过期 → 重新获取 snapshot；标签页未知 → browserforce tabs。修复后重试。
6. 后端回退会明确提示 — 扩展已连接时，auto 会使用真实 Chrome；如果回退到托管的 Chrome，则会发出警告；使用 --real 可在回退时直接失败。

页面已渲染并不能证明一切

你读取的标签页可能在你更改之前就已打开并登录；页面能够正确渲染，可能与该更改毫无关系。在认定某个流程已验证之前，请用独立证据（重新导航、服务器日志、测试）佐证浏览器结果。

故障排除

错误恢复

• “Unknown ref”：页面已更改 — 执行 browserforce snapshot，使用新的 refs
• “No tab named …”：执行 browserforce tabs，指定列出的句柄或名称
• 连接丢失：用户必须检查 browserforce status
• 没有标签页：执行 browserforce open https://example.com
• 未找到元素：执行 browserforce snapshot --search "button"

重要提示

这是用户的真实浏览器。请尊重用户：

• 不要关闭你未打开的标签页
• 不要跳转到你未创建的标签页
• 不要修改浏览器设置或存储的数据