cmux-browser

cmux 浏览器

此技能用于在 cmux Web 视图表面内进行浏览器自动化。它不同于独立的浏览器自动化工具，因为每个浏览器表面都位于 cmux 工作区、窗格和表面拓扑结构中。

默认规则

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

更改浏览器状态前，先识别调用方：

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 确定调用自动化的终端。若当前视觉焦点所在的工作区与调用方工作区不同，请勿在该工作区中打开浏览器。

核心工作流

# 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.
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

循环执行：导航、验证 URL、等待、创建快照、操作，然后重新创建快照。快照引用是临时的。导航、模态框变化、标签页变化或 DOM 更新后，都要重新创建快照。

目标定位

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

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

打开命令可以新建或复用浏览器分屏：

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

每项任务保持一个浏览器表面，除非用户要求打开多个标签页或页面。

命令组

完整命令列表请参阅 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。

常见模式

持久化捕获

在向用户报告之前，将浏览器截图、跟踪文件、下载的诊断信息和可复用的会话状态保存到 /cmux-assets/<branch>/browser/...，而不是 /tmp。

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 中。

导航、等待和检查

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

填写表单

cmux browser surface:7 fill "#email" --text "[email protected]"
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"

调试捕获

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

保存和恢复会话

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

远程工作区

在远程 SSH 工作区中，浏览器窗格会通过远程机器转发 HTTP 和 WebSocket 流量。localhost:3000 指远程主机的 localhost，浏览器存储按远程工作区上下文隔离。

重建和重新加载

如果浏览器自动化用于验证 cmux 应用或运行时变更，请先从当前工作树构建带标签的应用：

./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:-}"

测试或内部试用构建中，绝不要针对未标记的调试套接字运行自动化。

规则

• 默认将浏览器打开操作和其他操作限定在当前调用方工作区内。
• 从 cmux 终端创建浏览器表面时，传入 --workspace "${CMUX_WORKSPACE_ID:-}"。
• 使用返回的 surface:N 引用，并在任何会改变状态的操作后重新创建快照。
• 等待或诊断页面状态前，先验证 get url。
• 需要立即验证时，在会改变状态的操作中使用 --snapshot-after。
• 脚本优先使用 get、is 和 find。供人工检查时使用截图和快照。
• 除非用户指定目标，否则不要关闭、移动或聚焦调用方工作区之外的浏览器表面。
• 不要依赖不受支持的独立浏览器假设。cmux 使用由 WKWebView 驱动的浏览器表面。