cmux-browser

使用 cmux 進行瀏覽器自動化

在 cmux 網頁檢視中執行瀏覽器任務時使用此技能。

核心工作流程

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，因為它們依賴於 WKWebView 未公開的 Chrome/CDP 專用 API：

• 離線模擬
• 追蹤/螢幕錄製
• 網路路由攔截/模擬
• 低階原始輸入注入

請改用支援的高階命令（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。
• 如果頁面仍然失敗，請導航到較簡單的中間頁面，然後從那裡重試任務。