cmux-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux Browser

cmux 浏览器

Use this skill for browser automation inside cmux webview surfaces. It is different from a standalone browser automation tool because every browser surface lives inside a cmux workspace, pane, and surface topology.

本技能用于在cmux webview界面中实现浏览器自动化。它与独立的浏览器自动化工具不同，因为每个浏览器界面都存在于cmux工作区、面板和界面拓扑结构中。

Default Rule

默认规则

Open and control browser surfaces in the current caller workspace unless the user explicitly names another workspace or window.

Before mutating browser state, identify the caller:

bash

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

Use

CMUX_WORKSPACE_ID

for new browser splits and

CMUX_SURFACE_ID

to understand the terminal that invoked the automation. Do not open a browser in the visually focused workspace if it differs from the caller workspace.

除非用户明确指定其他工作区或窗口，否则在当前调用者的工作区中打开并控制浏览器界面。

在修改浏览器状态之前，先识别调用者：

bash

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

创建新的浏览器拆分时使用

CMUX_WORKSPACE_ID

，通过

CMUX_SURFACE_ID

了解触发自动化操作的终端。如果视觉聚焦的工作区与调用者工作区不同，请勿在该聚焦工作区中打开浏览器。

Core Workflow

核心工作流程

bash

undefined

bash

undefined

Open in the caller workspace and capture the returned surface ref.

在调用者工作区中打开浏览器，并捕获返回的界面引用。

cmux --json browser open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}"

Use the returned surface, for example surface:7.

使用返回的界面，例如surface:7。

cmux browser surface:7 get url cmux browser surface:7 wait --load-state complete --timeout-ms 15000 cmux browser surface:7 snapshot --interactive --compact cmux browser surface:7 click e2 --snapshot-after cmux browser surface:7 snapshot --interactive --compact


Loop: navigate, verify URL, wait, snapshot, act, then re-snapshot. Snapshot refs are temporary. Re-snapshot after navigation, modal changes, tab changes, or DOM updates.


循环流程：导航、验证URL、等待、快照、执行操作、重新快照。快照引用是临时的。在导航、模态框变化、标签页切换或DOM更新后重新生成快照。

Targeting

目标定位

Most subcommands require a browser surface:

bash

cmux browser identify
cmux browser identify --surface surface:2
cmux browser surface:2 get url
cmux browser --surface surface:2 get title

Open commands can create or reuse a browser split:

bash

cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux browser open-split https://example.com --workspace workspace:2 --json
cmux browser new https://example.com --window window:1 --json

Keep one browser surface per task unless the user asks for multiple tabs or pages.

大多数子命令需要指定浏览器界面：

bash

cmux browser identify
cmux browser identify --surface surface:2
cmux browser surface:2 get url
cmux browser --surface surface:2 get title

打开命令可以创建或复用浏览器拆分：

bash

cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux browser open-split https://example.com --workspace workspace:2 --json
cmux browser new https://example.com --window window:1 --json

除非用户要求多个标签页或页面，否则每个任务保留一个浏览器界面。

Command Groups

命令组

See references/commands.md for the full command list. Main groups:

Navigation and targeting:

identify

open

open-split

new

navigate

goto

back

forward

reload

url

focus-webview

is-webview-focused

Waiting:

wait --selector

--text

--url-contains

--load-state

--function

DOM interaction:

click

dblclick

hover

focus

check

uncheck

scroll-into-view

type

fill

press

keydown

keyup

select

scroll

Inspection:
```
snapshot
```
,
```
screenshot
```
,
```
get
```
,
```
is
```
,
```
find
```
,
```
highlight
```
.
JavaScript and injection:
```
eval
```
,
```
addinitscript
```
,
```
addscript
```
,
```
addstyle
```
.
Frames, dialogs, downloads:
```
frame
```
,
```
dialog
```
,
```
download
```
.
State and session:
```
cookies
```
,
```
storage
```
,
```
state
```
.
Tabs and diagnostics:
```
tab
```
,
```
console
```
,
```
errors
```
.

Environment and lower-level APIs:

viewport

geolocation

offline

trace

network

screencast

input

完整命令列表请查看references/commands.md。主要命令组如下：

导航与目标定位：

identify

、

open

、

open-split

、

new

、

navigate

、

goto

、

back

、

forward

、

reload

、

url

、

focus-webview

、

is-webview-focused

。

等待操作：

wait --selector

、

--text

、

--url-contains

、

--load-state

、

--function

。

DOM交互：

click

、

dblclick

、

hover

、

focus

、

check

、

uncheck

、

scroll-into-view

、

type

、

fill

、

press

、

keydown

、

keyup

、

select

、

scroll

。

检查操作：
```
snapshot
```
、
```
screenshot
```
、
```
get
```
、
```
is
```
、
```
find
```
、
```
highlight
```
。
JavaScript与注入：
```
eval
```
、
```
addinitscript
```
、
```
addscript
```
、
```
addstyle
```
。
框架、对话框、下载：
```
frame
```
、
```
dialog
```
、
```
download
```
。
状态与会话：
```
cookies
```
、
```
storage
```
、
```
state
```
。
标签页与诊断：
```
tab
```
、
```
console
```
、
```
errors
```
。

环境与底层API：

viewport

、

geolocation

、

offline

、

trace

、

network

、

screencast

、

input

。

Common Patterns

常见模式

Durable Captures

持久化捕获

Save browser screenshots, traces, downloaded diagnostics, and reusable session state under

/cmux-assets/<branch>/browser/...

, not

/tmp

, before reporting them to the user.

bash

BRANCH="$(git branch --show-current 2>/dev/null || true)"
BRANCH="${BRANCH:-$(basename "$PWD")}"
BRANCH="$(printf '%s' "$BRANCH" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//;s/-$//')"
ASSET_BASE="/cmux-assets"
if ! mkdir -p "$ASSET_BASE/$BRANCH" 2>/dev/null; then
  ASSET_BASE="$(pwd)/cmux-assets"
  mkdir -p "$ASSET_BASE/$BRANCH"
fi
BROWSER_ASSET_ROOT="$ASSET_BASE/$BRANCH/browser/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BROWSER_ASSET_ROOT"

/cmux-assets

is unavailable because the root volume is read-only, use the fallback path and state it. Do not leave final screenshots or session files only in

/tmp

在向用户报告之前，将浏览器截图、跟踪信息、下载的诊断文件以及可复用的会话状态保存到

/cmux-assets/<branch>/browser/...

下，而非

/tmp

目录。

bash

BRANCH="$(git branch --show-current 2>/dev/null || true)"
BRANCH="${BRANCH:-$(basename "$PWD")}"
BRANCH="$(printf '%s' "$BRANCH" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//;s/-$//')"
ASSET_BASE="/cmux-assets"
if ! mkdir -p "$ASSET_BASE/$BRANCH" 2>/dev/null; then
  ASSET_BASE="$(pwd)/cmux-assets"
  mkdir -p "$ASSET_BASE/$BRANCH"
fi
BROWSER_ASSET_ROOT="$ASSET_BASE/$BRANCH/browser/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BROWSER_ASSET_ROOT"

如果因根卷为只读导致

/cmux-assets

不可用，请使用备用路径并告知用户。请勿将最终截图或会话文件仅保存在

/tmp

中。

Navigate, Wait, Inspect

导航、等待、检查

bash

cmux --json browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 get title

bash

cmux --json browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive --compact
cmux browser surface:7 get title

Form Fill

表单填充

bash

cmux browser surface:7 fill "#email" --text "ops@example.com"
cmux browser surface:7 fill "#password" --text "$PASSWORD"
cmux browser surface:7 click "button[type='submit']" --snapshot-after
cmux browser surface:7 wait --text "Welcome" --timeout-ms 15000
cmux browser surface:7 is visible "#dashboard"

bash

cmux browser surface:7 fill "#email" --text "ops@example.com"
cmux browser surface:7 fill "#password" --text "$PASSWORD"
cmux browser surface:7 click "button[type='submit']" --snapshot-after
cmux browser surface:7 wait --text "Welcome" --timeout-ms 15000
cmux browser surface:7 is visible "#dashboard"

Debug Capture

调试捕获

bash

cmux browser surface:7 console list
cmux browser surface:7 errors list
cmux browser surface:7 screenshot --out "$BROWSER_ASSET_ROOT/cmux-failure.png"
cmux browser surface:7 snapshot --interactive --compact

bash

cmux browser surface:7 console list
cmux browser surface:7 errors list
cmux browser surface:7 screenshot --out "$BROWSER_ASSET_ROOT/cmux-failure.png"
cmux browser surface:7 snapshot --interactive --compact

Session Save and Restore

会话保存与恢复

bash

cmux browser surface:7 state save "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 state load "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 reload --snapshot-after

bash

cmux browser surface:7 state save "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 state load "$BROWSER_ASSET_ROOT/cmux-browser-session.json"
cmux browser surface:7 reload --snapshot-after

Remote Workspaces

远程工作区

In remote SSH workspaces, browser panes route HTTP and WebSocket traffic through the remote machine.

localhost:3000

means the remote host's localhost, and browser storage is isolated per remote workspace context.

在远程SSH工作区中，浏览器面板通过远程机器路由HTTP和WebSocket流量。

localhost:3000

指的是远程主机的localhost，且浏览器存储在每个远程工作区上下文间是隔离的。

Rebuild and Reload

重建与重载

If browser automation is validating a cmux app/runtime change, first build a tagged app from the active worktree:

bash

./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"

Never automate against an untagged debug socket for tests or dogfood builds.

如果浏览器自动化正在验证cmux应用/运行时的更改，请先从活动工作树构建一个带标签的应用：

bash

./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux browser open http://localhost:3000 --workspace "${CMUX_WORKSPACE_ID:-}"

测试或内部版本时，切勿针对未标记的调试套接字执行自动化操作。

Rules

规则

Scope browser opens and actions to the current caller workspace by default.
Pass
```
--workspace "${CMUX_WORKSPACE_ID:-}"
```
when creating a browser surface from a cmux terminal.
Use returned
```
surface:N
```
refs, and re-snapshot after any state-changing action.
Verify
```
get url
```
before waiting or diagnosing page state.
Use
```
--snapshot-after
```
on mutating actions when you need immediate verification.
Prefer
```
get
```
,
```
is
```
, and
```
find
```
for scripts. Use screenshots and snapshots for human review.
Do not close, move, or focus browser surfaces outside the caller workspace unless the user names that target.
Do not use unsupported standalone-browser assumptions. cmux uses WKWebView-backed browser surfaces.

默认将浏览器打开和操作的范围限定在当前调用者的工作区内。
从cmux终端创建浏览器界面时，传递
```
--workspace "${CMUX_WORKSPACE_ID:-}"
```
参数。
使用返回的
```
surface:N
```
引用，并在任何改变状态的操作后重新生成快照。
在等待或诊断页面状态之前，先验证
```
get url
```
的结果。
当需要立即验证时，在修改操作上使用
```
--snapshot-after
```
参数。
脚本中优先使用
```
get
```
、
```
is
```
和
```
find
```
命令。截图和快照用于人工审核。
除非用户指定目标，否则请勿关闭、移动或聚焦调用者工作区之外的浏览器界面。
不要使用不支持的独立浏览器假设。cmux使用基于WKWebView的浏览器界面。