在 cmux 工作区中安全自动化操作且不干扰用户当前焦点

当需要在调用代理的 cmux 工作区内创建面板、发送命令、预览产物或重载应用时，按调用者上下文操作并避免改变用户可见焦点。

适用场景

解决思路

1. 默认将操作限定在调用者所在的工作区，除非用户明确要求其他工作区、窗口或全局状态。
2. 不要假设视觉上聚焦的 cmux 工作区就是目标；先读取调用者环境：printf 'workspace=%s\nsurface=%s\nsocket=%s\n' "${CMUX_WORKSPACE_ID:-}" "${CMUX_SURFACE_ID:-}" "${CMUX_SOCKET_PATH:-}" 并运行 cmux identify --json。
3. 以 CMUX_WORKSPACE_ID 作为默认工作区锚点，以 CMUX_SURFACE_ID 作为默认调用者终端/表面锚点；若缺失则用 cmux identify --json 并明确说明使用的是当前聚焦的 cmux 上下文。
4. 将布局与焦点视为两件独立的事，绝不推测性地调用改变焦点的动词。
5. 未经用户明确要求，绝不调用 select-workspace、focus-pane、focus-panel 或带焦点改变动作的 tab-action。
6. 以一次性、增量方式构建布局，优先使用能同时创建面板并填充正确表面的命令，例如 cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765" 或 cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type terminal --direction down。
7. 避免先创建再移动再聚焦的链式操作；若布局命令拒绝了有效的 surface: 或 pane: 引用，不要通过聚焦来绕过，向用户报告该 bug 并停止。
8. 在支持 --focus false 的动词上始终传入该参数，例如 move-surface --focus false 可保留用户当前注意力。
9. 为当前任务的辅助输出（预览应用、TUI、日志、一次性 shell、浏览器检查）复用调用者终端右侧的 helper 面板；先运行 cmux identify --json、cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json、cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json 检查上下文。
10. 若调用者工作区已有非调用者的 helper 面板，则向该面板添加新表面：cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false。
11. 若没有 helper 面板，则只创建一个右侧面板：cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false。
12. 若存在多个明显来自同一自动化的陈旧 helper 面板且用户要求整理或复用，保留一个右侧 helper 面板并清理重复项；不要关闭无法确信是陈旧 helper 输出的面板。
13. 通过显式 surface 引用向新建或复用的 helper 表面发送命令，除非用户要求否则不要聚焦它。
14. 创建 helper 终端后，在声称工作可见之前验证其可用性：cmux surface-health --workspace "${CMUX_WORKSPACE_ID:-}"、cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:<helper> --lines 20、cmux top --workspace "${CMUX_WORKSPACE_ID:-}" --processes --format tsv。
15. 若 read-screen 报告 Terminal surface not found，或 surface-health 显示 helper 终端未附加且 top 无进程，则视为 cmux CLI/运行时 bug；不要声称命令正在工作区中运行，清理创建的空 helper 表面后报告 bug 或使用已实体化的 cmux 终端表面。
16. 除非用户明确要求，不要为可见的 dogfood 交接使用隐藏的 tmux、nohup 或分离后台回退方案。
17. 当任务产生视频、图片、已检查帧、截图、PDF 等面向用户的产物时，在交接前于 cmux 中打开最终产物，放入调用者工作区右侧 helper 面板作为文件预览标签，并使用 --no-focus 保持用户当前终端选中。
18. 最终面向用户的产物应持久保存在 /cmux-assets/<branch>/... 下；若根卷只读导致无法创建 /cmux-assets，则使用当前仓库检出下的 cmux-assets/<branch>/... 并说明该回退。
19. 仅将 /tmp 用于临时文件，在打开或报告前将接受的产物复制到持久树中。
20. 使用绝对持久路径或相对于当前仓库检出的路径；若产物位于 worktree 中，在最终交接前复制到持久的按分支划分的资产树中，不要报告仅在 worktree 内有效的路径。
21. 按以下顺序解析工作区和面板：优先 CMUX_WORKSPACE_ID 和 CMUX_SURFACE_ID；若缺失或被 cmux 拒绝，检查 cmux identify --json 并说明回退到当前聚焦的 cmux 上下文；明显时复用已有的非调用者 helper 面板；若不存在则用 --focus false 在右侧创建一个，然后重新列出面板以获取 pane 引用。
22. 使用模板打开产物：定义 ARTIFACTS 数组、WORKSPACE 和 SURFACE 变量，运行 cmux identify --json、cmux list-panes、cmux list-pane-surfaces，选择已有非调用者 helper 面板或创建右侧面板，然后运行 cmux open "${ARTIFACTS[@]}" --workspace "$WORKSPACE" --pane pane:<right-helper> --no-focus，最后再次 cmux list-pane-surfaces 确认。
23. 若 cmux open 因调用者环境指向陈旧工作区而失败，用 cmux identify --json 的引用重试一次；不要在其他工作区之间反复猜测；若仍失败，报告失败并包含确切的产物路径。
24. 理解层级：Window 是 macOS cmux 窗口；Workspace 是侧边栏条目（UI 可能称 tab，但 CLI/socket API 称 workspace）；Pane 是工作区内的分割区域；Surface 是面板内的标签，可为终端或浏览器面板；Panel 是表面内部的内部内容类型，优先使用 CLI surface 命令而非 panel 内部。
25. 检查当前上下文：cmux identify --json、cmux current-workspace --json、cmux list-workspaces --json、cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json、cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json、cmux list-panels --workspace "${CMUX_WORKSPACE_ID:-}" --json。
26. 当日志或交接需要稳定 UUID 加人类可读引用时，使用 --id-format both：cmux --json --id-format both identify。
27. 即使设置了环境变量，也优先使用显式工作区标志，使自动化可审计并避免影响其他窗口中聚焦的工作区。
28. 工作区范围操作示例：用户要求新任务区域时 cmux new-workspace --name "debug auth" --cwd "$PWD"；仅在明确要求时 cmux rename-workspace --workspace "${CMUX_WORKSPACE_ID:-}" -- "build fix"、cmux close-workspace --workspace workspace:4、cmux close-surface --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:3；增量布局 cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right、cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal；改变焦点的操作仅在明确要求时使用 cmux select-workspace --workspace workspace:2、cmux focus-pane --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2、cmux focus-panel --workspace "${CMUX_WORKSPACE_ID:-}" --panel surface:3。
29. 将当前终端视为调用代理的表面，作为相对操作最安全的锚点：cmux send "npm test\n" 发送到调用者工作区中聚焦的终端；cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n" 和 cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter 发送到确切的调用者表面。
30. 除非用户要求该目标，不要向其他工作区发送按键、关闭表面或改变焦点。
31. 在面板内重排表面：cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3、--after surface:3 或 --index 0。
32. 将表面移动到另一个已有面板，传入 --focus false 保持用户当前注意力：cmux move-surface --surface surface:240 --pane pane:172 --focus false。
33. 将表面拆分为新面板：cmux drag-surface-to-split --surface surface:240 down；注意已知问题：该命令当前走 V1 并通过 UI 焦点解析工作区，当调用者工作区不是视觉聚焦时会失败并报 ERROR: Surface not found（见 issue 1901、3189），在修复前优先增量构建布局而非先创建再拆分。
34. 不要调用 focus-pane 或 focus-panel 来从失败的移动中恢复；报告失败并停止。
35. 将状态、进度和日志附加到当前工作区，使侧边栏反映此任务：cmux set-status build "running" --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"、cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"、cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"、cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json、cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"、cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"。
36. 对于 cmux 应用/运行时更改，从活动 worktree 使用带标签的重载：./scripts/reload.sh --tag <short-tag>；带标签重载会创建隔离的应用名、bundle ID、调试 socket 和 DerivedData 路径。
37. 若重载输出包含 Dev web origin，在交接前从同一 worktree 启动匹配的开发服务器并证明其响应：cd web 后 CMUX_PORT=<printed-port> CMUX_PORT_RANGE=<range> CMUX_PORT_END=<end> bun dev，再 curl -fsS "http://127.0.0.1:<printed-port>"。
38. 在右侧 helper 终端中运行该服务器，并用 read-screen 或 top 验证终端存在；若 helper 终端无法实例化，报告 cmux CLI/运行时 bug 而非使用隐藏后台回退。
39. 绝不构建或启动未加标签的 cmux DEV；若测试或工具需要 socket，使用标签专属 socket：CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json。
40. 当任务涉及共享 iOS/运行时代码时，也从 worktree 运行 iOS 重载流程：ios/scripts/reload.sh --tag <ios-tag>。
41. 在回退到默认值之前使用 cmux 提供的 socket 路径：SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"。
42. socket 访问可能关闭、限制为 cmux 生成的进程或允许所有本地进程；若命令无法连接，在更改设置前检查能力：cmux capabilities --json、cmux ping。
43. 参考 references/commands.md 了解工作区、面板、表面、通知和实用命令；参考 ../cmux-browser/SKILL.md 了解遵循相同当前工作区规则的浏览器表面。
44. 规则：默认在调用者当前工作区工作；优先使用 CMUX_WORKSPACE_ID、CMUX_SURFACE_ID 和 CMUX_SOCKET_PATH 而非聚焦窗口回退；对变更操作优先显式 --workspace 和 --surface 标志；除非用户明确要求，绝不调用 focus-pane、focus-panel、select-workspace 或改变焦点的 tab-action；在 move-surface 及任何支持 --focus false 的创建动词上传入该参数；辅助输出复用右侧 helper 面板，仅在不存在时创建一个；将最终视频、图片、已检查帧等面向用户的产物持久保存在 /cmux-assets/<branch>/... 或显式回退 cmux-assets/<branch>/...，然后在交接前用 cmux open ... --no-focus 在右侧 helper 面板中打开；用 new-pane --type ... --url ... 增量构建布局而非先创建再移动再聚焦；若 CLI 命令拒绝有效的 surface 或 pane 引用，向用户报告，不要通过聚焦绕过；除非用户指定目标，不要关闭、聚焦、移动或向其他工作区发送输入；聊天和命令示例使用短引用，UUID 仅用于日志、持久化或调试；对于应用/运行时更改，在 dogfood 交接前始终从 worktree 运行 ./scripts/reload.sh --tag <tag>；若带标签重载打印 Dev web origin，则在同一 worktree 的开发服务器运行且 curl -fsS <Dev web origin> 通过之前，交接不完整。

适用边界 · 注意事项

• 用户未明确要求时，不要切换到其他工作区、窗口或全局状态，也不要改变焦点。
• 不要假设视觉上聚焦的工作区就是调用者工作区，用户可能正在看别处。
• 不要使用隐藏的 tmux、nohup 或分离后台回退方案来替代可见的 cmux 终端交接，除非用户明确要求。