用 cmux 终端复用器为 AI 代理提供可见分屏…

当需要让 AI 编码代理在可见的终端分屏中并行执行命令、进行 Playwright 级浏览器自动化，或协调多个子代理各自拥有独立工作区时使用。

适用场景

解决思路

1. 用 `cmux identify --json` 查看当前 window/workspace/pane/surface 上下文，用 `cmux list-panes`、`cmux list-pane-surfaces --pane pane:1`、`cmux list-workspaces` 列出结构；环境变量 `$CMUX_SURFACE_ID` 和 `$CMUX_WORKSPACE_ID` 会自动设置，句柄使用短引用如 `surface:N`、`pane:N`、`workspace:N`、`window:N`。
2. 创建分屏：`cmux --json new-split right`（并排，适合并行工作）或 `cmux --json new-split down`（堆叠，适合日志），并始终用 `WORKER=$(cmux --json new-split right | python3 -c "import sys,json; print(json.load(sys.stdin)['surface_ref'])")` 捕获返回的 `surface_ref`。
3. 向分屏发送命令并读取输出：`cmux send-surface --surface surface:22 "npm run build\n"`、`cmux capture-pane --surface surface:22`（当前屏幕）、`cmux capture-pane --surface surface:22 --scrollback`（含完整历史）；用 `cmux send-key-surface --surface surface:22 ctrl-c` 或 `enter` 发送按键。
4. 黄金法则：绝不抢占焦点，始终使用 `--surface` 定向操作。
5. Worker 分屏模式：创建分屏并捕获 `$WORKER`，用 `cmux send-surface --surface "$WORKER" "make test 2>&1; echo EXIT_CODE=\$?\n"` 执行，`sleep 3` 后用 `cmux capture-pane --surface "$WORKER"` 读取，完成后用 `cmux close-surface --surface "$WORKER"` 清理。
6. Pane 管理：`cmux focus-pane --pane pane:2`、`cmux close-surface --surface surface:22`、`cmux swap-pane --pane pane:1 --target-pane pane:2`、`cmux move-surface --surface surface:7 --pane pane:2 --focus true`、`cmux reorder-surface --surface surface:7 --before surface:3`。
7. 浏览器自动化工作流：navigate → wait for load → snapshot --interactive → act with refs → re-snapshot。用 `cmux --json browser open https://example.com` 打开并捕获 surface ref；用 `cmux browser surface:23 goto/back/forward/reload/get url/get title` 导航。
8. 用快照获取稳定元素引用（e1、e2…）而非 CSS 选择器：`cmux browser surface:23 snapshot --interactive`、`--interactive --compact`、`--selector "form#login" --interactive`；DOM 变更后引用会失效，导航或点击后必须重新快照，或用 `--snapshot-after` 自动获取新快照：`cmux --json browser surface:23 click e1 --snapshot-after`。
9. 交互元素：`click e1`、`dblclick e2`、`hover e3`、`focus e4`；文本输入 `fill e5 "hello@example.com"`（清空并输入）、`fill e5 ""`（清空）、`type e6 "search query"`（不清空直接输入）；按键 `press Enter`、`press Tab`、`keydown Shift`；表单 `check e7`、`uncheck e7`、`select e8 "option-value"`；滚动 `scroll --dy 500`、`scroll --selector ".container" --dy 300`、`scroll-into-view e9`。
10. 等待状态：`wait --load-state complete --timeout-ms 15000`、`wait --selector "#ready" --timeout-ms 10000`、`wait --text "Success" --timeout-ms 10000`、`wait --url-contains "/dashboard" --timeout-ms 10000`、`wait --function "document.readyState === 'complete'" --timeout-ms 10000`。
11. 读取页面内容：`get text body`、`get html body`、`get value "#email"`、`get attr "#link" --attr href`、`get count ".items"`、`get box "#button"`、`get styles "#el" --property color`；状态检查 `is visible "#modal"`、`is enabled "#submit"`、`is checked "#agree"`。
12. Playwright 风格定位器：`find role button`、`find text "Sign In"`、`find label "Email"`、`find placeholder "Enter email"`、`find testid "submit-btn"`、`find first ".item"`、`find last ".item"`、`find nth ".item" 3`。
13. JavaScript 求值：`cmux browser surface:23 eval "document.title"`、`eval "document.querySelectorAll('.item').length"`、`eval "window.scrollTo(0, document.body.scrollHeight)"`。
14. Frame 与对话框：`frame "#iframe-selector"` 切换到 iframe、`frame main` 回到主框架；`dialog accept`、`dialog dismiss`、`dialog accept "prompt text"`。
15. Cookie、存储与状态：`cookies get`、`cookies set session_token "abc123"`、`cookies clear`；`storage local get`、`storage local set myKey "myValue"`、`storage session clear`；`state save ./auth-state.json` 与 `state load ./auth-state.json` 保存/恢复完整浏览器状态（cookies + storage + tabs）。
16. 认证流程：打开登录页 → `wait --load-state complete --timeout-ms 15000` → `snapshot --interactive` → `fill e1 "user@example.com"` → `fill e2 "my-password"` → `click e3` → `wait --url-contains "/dashboard" --timeout-ms 20000` → `state save ./auth-state.json`；在新 surface 中用 `state load ./auth-state.json` 复用后 `goto` 目标页。
17. 诊断：`console list`、`console clear`、`errors list`、`errors clear`、`highlight "#el"`、`screenshot`。
18. 脚本与样式注入：`addscript "console.log('injected')"`、`addstyle "body { background: red; }"`、`addinitscript "window.__injected = true"`（每次导航都运行）。
19. 侧边栏状态与进度：`cmux set-status agent "working" --icon hammer --color "#ff9500"`、`cmux set-status agent "done" --icon checkmark --color "#34c759"`、`cmux clear-status agent`；`cmux set-progress 0.3 --label "Running tests..."`、`cmux set-progress 1.0 --label "Complete"`、`cmux clear-progress`；`cmux log "Starting build"`、`cmux log --level success "All tests passed"`、`cmux log --level error --source build "Compilation failed"`。
20. 通知：`cmux notify --title "Task Complete" --body "All tests passing"`、`cmux notify --title "Need Input" --subtitle "Permission" --body "Approve deployment?"`。
21. 代理团队模式：1) 为每个队友创建分屏；2) 通过 Agent 工具生成队友并传入各自的 cmux surface ref；3) 队友用 `cmux send-surface` 在自己的分屏中运行命令；4) 队友用 `cmux set-status` 和 `cmux log` 报告状态；5) 用户可并排看到所有工作。
22. 3 代理团队示例：用 `SPLIT_1=$(cmux --json new-split right | ...)`、`SPLIT_2=$(cmux --json new-split down | ...)`、`SPLIT_3=$(cmux --json new-split down | ...)` 创建可见分屏，然后在每个队友的提示中说明：分屏 ref、用 `cmux send-surface --surface surface:42 "command\n"` 运行命令、用 `cmux capture-pane --surface surface:42` 读取输出、用 `cmux set-status myagent "working" --icon hammer` 设置状态、用 `cmux log "message"` 记录进度、绝不抢占焦点始终用 `--surface` 定向。
23. 混合布局（终端 + 浏览器）：`BUILD=$(cmux --json new-split right | ...)`、`DOCS=$(cmux --json browser open https://docs.example.com | ...)`、`TEST=$(cmux --json new-split down | ...)`。
24. 团队关键规则：绝不在分屏中启动 `claude -p`，改用带 `team_name` 的 Agent 工具；生成队友前先创建分屏并在提示中传入 ref；每个队友一个分屏；通过 SendMessage 协调而非读取彼此终端输出；完成后用 `cmux close-surface --surface <ref>` 清理。
25. 常用模式——后台构建并跟踪日志：用 `LOG=$(cmux --json new-split down | ...)` 创建分屏，`cmux send-surface --surface "$LOG" "cargo build --release 2>&1 | tee /tmp/build.log\n"`，做其他工作后用 `cmux capture-pane --surface "$LOG" --scrollback | tail -20` 查看。
26. 常用模式——QA 测试流程：`BROWSER=$(cmux --json browser open https://myapp.vercel.app | ...)` → `wait --load-state complete --timeout-ms 15000` → `snapshot --interactive` → 用 e1/e2/e3 交互 → `screenshot` → `errors list` → `cmux close-surface --surface $BROWSER`。
27. 常用模式——状态驱动的长任务：`cmux set-status task "starting" --icon clock --color "#ff9500"` 和 `cmux set-progress 0.0 --label "Initializing..."`，各步骤更新 `set-progress 0.33/0.66/1.0`，完成后 `set-status task "complete" --icon checkmark --color "#34c759"`、`clear-progress`、`notify --title "Task complete" --body "All steps passed"`。

适用边界 · 注意事项

• 未安装 cmux 或不在 cmux 终端会话中时无法使用（依赖其 socket API 与 CLI）。
• 需要非 Chromium 浏览器引擎或已有外部 Playwright/Chrome 工作流时，不必改用 cmux 浏览器自动化。
• 简单的单进程命令执行或无需可见分屏/团队协作的场景，直接用普通终端更轻量。