cmux-browser

使用 cmux 进行浏览器自动化

在 cmux webview 中执行浏览器任务时使用此技能。

核心工作流

1. 打开或定位一个浏览器表面。
2. 在等待或截图前，使用 get url 验证导航。
3. 使用 snapshot --interactive 获取最新的元素引用。
4. 使用引用执行操作（click、fill、type、select、press）。
5. 等待状态变化。
6. 在 DOM/导航变化后重新截图。

cmux --json browser open https://example.com
# 使用返回的表面引用，例如：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
cmux browser surface:7 fill e1 "hello"
cmux --json browser surface:7 click e2 --snapshot-after
cmux browser surface:7 snapshot --interactive

表面定位

# 识别当前上下文
cmux identify --json

# 打开并路由到特定的拓扑目标
cmux browser open https://example.com --workspace workspace:2 --window window:1 --json

注意：

• CLI 输出默认使用短引用（surface:N、pane:N、workspace:N、window:N）。
• 输入时仍接受 UUID；仅在需要时请求 UUID 输出（--id-format uuids|both）。
• 除非有意切换，否则每个任务保持使用一个 surface:N。

等待支持

cmux 支持类似于 agent-browser 的等待模式：

cmux browser <surface> wait --selector "#ready" --timeout-ms 10000
cmux browser <surface> wait --text "Success" --timeout-ms 10000
cmux browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000

常见流程

表单提交

cmux --json browser open https://example.com/signup
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e1 "Jane Doe"
cmux browser surface:7 fill e2 "jane@example.com"
cmux --json browser surface:7 click e3 --snapshot-after
cmux browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
cmux browser surface:7 snapshot --interactive

清空输入框

cmux browser surface:7 fill e11 "" --snapshot-after --json
cmux browser surface:7 get value e11 --json

稳定的代理循环（推荐）

# 导航 -> 验证 -> 等待 -> 截图 -> 操作 -> 截图
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux --json browser surface:7 click e5 --snapshot-after
cmux browser surface:7 snapshot --interactive

如果 get url 为空或为 about:blank，则先导航，而不是等待加载状态。

深入参考

参考	使用场景
references/commands.md	完整的浏览器命令映射和快速语法
references/snapshot-refs.md	引用生命周期和过期引用故障排除
references/authentication.md	登录/OAuth/2FA 模式及状态保存/加载
references/authentication.md#saving-authentication-state	登录后立即保存认证状态
references/session-management.md	多表面隔离和状态持久化模式
references/video-recording.md	当前录制状态和实用替代方案
references/proxy-support.md	WKWebView 中的代理行为及解决方法

即用模板

模板	描述
templates/form-automation.sh	截图/引用表单填充循环
templates/authenticated-session.sh	登录一次，保存/加载状态
templates/capture-workflow.sh	导航 + 捕获截图/屏幕截图

视口大小（WKWebView）

使用 cmux browser <surface> viewport <width> <height> 设置精确的逻辑视口，范围为 1...4096 CSS 像素。页面会在其现有窗格内按比例适配，因此窗格布局和焦点保持不变；截图使用请求的逻辑尺寸。运行 cmux browser <surface> viewport reset 以恢复为原生窗格大小。请先关闭或分离浏览器检查器，因为其检查器管理的分割布局无法与视口模拟结合使用。大视口和页面缩放组合存在限制；当组合超过 WKWebView 渲染限制时，视口命令会返回结构化的 maximum_page_zoom 详细信息，而不更改当前视口。打开或重新附加已连接的浏览器检查器会将模拟重置为原生大小，因为 WebKit 拥有附加的分割几何体。

限制（WKWebView）

以下命令当前返回 not_supported，因为它们依赖于 Chrome/CDP 独有的 API，WKWebView 未暴露：

• 离线模拟
• 跟踪/屏幕录制
• 网络路由拦截/模拟
• 低级原始输入注入

请使用支持的高级命令（click、fill、press、scroll、wait、snapshot）代替。

故障排除

snapshot --interactive 或 eval 返回 js_error

某些复杂页面可能会拒绝或破坏用于丰富截图和临时评估的 JavaScript。

恢复步骤：

cmux browser surface:7 get url
cmux browser surface:7 get text body
cmux browser surface:7 get html body

• 首先使用 get url，以便了解页面是否实际导航。
• 当 snapshot --interactive 或 eval 返回 js_error 时，回退到 get text body 或 get html body。
• 如果页面仍然失败，导航到一个更简单的中间页面，然后从那里重试任务。