browserforce

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BrowserForce — Your Real Chrome Browser

BrowserForce — 你的真实Chrome浏览器

BrowserForce gives you the user's actual Chrome browser — all their logins, cookies, and extensions already active. No headless browser, no fresh profiles.

BrowserForce为你提供用户真实的Chrome浏览器——所有登录状态、Cookie和扩展程序均已激活。无需无头浏览器，无需全新配置文件。

Prerequisites

前提条件

The user must have:

BrowserForce Chrome extension installed and connected (green icon)
The relay auto-starts on first command — no manual step needed

Check with:

browserforce status

用户必须满足：

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

使用以下命令检查状态：

browserforce status

Quick Reference

快速参考

bash

browserforce status              # Check relay + extension status
browserforce tabs                # List open tabs
browserforce snapshot [n]        # Accessibility tree of tab n
browserforce screenshot [n]      # Screenshot tab n (PNG to stdout)
browserforce navigate <url>      # Open URL in new tab
browserforce -e "<code>"         # Run Playwright JavaScript (one-shot)

bash

browserforce status              # 检查中继和扩展程序状态
browserforce tabs                # 列出所有打开的标签页
browserforce snapshot [n]        # 获取标签页n的可访问性树
browserforce screenshot [n]      # 捕获标签页n的截图（PNG输出至标准输出）
browserforce navigate <url>      # 在新标签页打开URL
browserforce -e "<code>"         # 执行一次性Playwright JavaScript代码

Important: One-Shot Execution

重要提示：一次性执行

Each

browserforce -e

call is independent — state does NOT persist between calls. Do everything you need (navigate, act, observe) within a single

-e

call.

每次

browserforce -e

调用都是独立的——调用之间状态不会保留。请在单次

-e

调用内完成所有需要的操作（导航、执行操作、观察结果）。

Core Workflow: Observe → Act → Observe

核心工作流程：观察 → 执行 → 观察

Quick observation (no code needed)

快速观察（无需代码）

bash

browserforce snapshot 0          # See what's on tab 0
browserforce tabs                # List all tabs

bash

browserforce snapshot 0          # 查看标签页0的内容
browserforce tabs                # 列出所有标签页

Navigate and read a page

导航并读取页面内容

bash

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

Note:

snapshot()

reads from

state.page

(if set) or

page

(default tab 0). Always assign

state.page

when creating a new page so

snapshot()

reads the right tab.

bash

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

注意：

snapshot()

会读取

state.page

（若已设置）或

page

（默认标签页0）。创建新页面时务必赋值

state.page

，这样

snapshot()

才能读取正确的标签页。

Click and verify

点击并验证

bash

browserforce -e "
  state.page = context.pages()[context.pages().length - 1];
  await state.page.locator('role=button[name=\"Next\"]').click();
  await waitForPageLoad();
  return await snapshot();
"

bash

browserforce -e "
  state.page = context.pages()[context.pages().length - 1];
  await state.page.locator('role=button[name=\"Next\"]').click();
  await waitForPageLoad();
  return await snapshot();
"

Fill a form

填写表单

bash

browserforce -e "
  state.page = context.pages()[context.pages().length - 1];
  await state.page.locator('role=textbox[name=\"Email\"]').fill('user@example.com');
  return await snapshot();
"

bash

browserforce -e "
  state.page = context.pages()[context.pages().length - 1];
  await state.page.locator('role=textbox[name=\"Email\"]').fill('user@example.com');
  return await snapshot();
"

Extract data

提取数据

bash

browserforce -e "
  const p = context.pages()[context.pages().length - 1];
  return await p.evaluate(() => document.querySelector('.price').textContent);
"

bash

browserforce -e "
  const p = context.pages()[context.pages().length - 1];
  return await p.evaluate(() => document.querySelector('.price').textContent);
"

Screenshot

截图

bash

browserforce screenshot 0 > page.png

bash

browserforce screenshot 0 > page.png

or via -e:

或通过 -e:

browserforce -e " state.page = context.pages()[0]; return await state.page.screenshot(); " > page.png

undefined

browserforce -e " state.page = context.pages()[0]; return await state.page.screenshot(); " > page.png

undefined

Rules

规则

snapshot() over screenshot() — snapshot returns text (fast, cheap). Use screenshot only for visual layout verification.
One-shot execution — each -e call is independent. Do all steps in one call.
Don't navigate existing tabs — create your own via
```
context.newPage()
```
or
```
browserforce navigate <url>
```
.

Use convenience commands for simple operations:

browserforce tabs

browserforce snapshot

browserforce screenshot

waitForPageLoad() — call after navigation or clicks that trigger page loads.

优先使用snapshot()而非screenshot()——snapshot返回文本内容（快速、轻量）。仅在需要验证视觉布局时使用screenshot。
一次性执行——每次-e调用都是独立的。所有步骤需在单次调用内完成。
不要导航现有标签页——通过
```
context.newPage()
```
或
```
browserforce navigate <url>
```
创建自己的标签页。

简单操作使用便捷命令：

browserforce tabs

、

browserforce snapshot

、

browserforce screenshot

。

waitForPageLoad()——在导航或触发页面加载的点击操作后调用该方法。

Error Recovery

错误恢复

Connection lost: User must check
```
browserforce status
```

No tabs:

browserforce navigate https://example.com

Element not found:

browserforce -e "return await snapshot({ search: 'button' })"

连接丢失：用户需执行
```
browserforce status
```
检查状态

无标签页：执行

browserforce navigate https://example.com

元素未找到：执行

browserforce -e "return await snapshot({ search: 'button' })"

Important

重要提示

This is the user's REAL browser. Be respectful:

Don't close tabs you didn't open
Don't navigate tabs you didn't create
Don't modify browser settings or stored data

这是用户的真实浏览器，请务必谨慎操作：

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