在当前 cmux 工作区与终端内进行操作。适用于 cmux 工作区、当前工作区、调用方 surface、pane、surface、指定 socket 目标以及无干扰的 cmux 自动化任务。
cmux Workspace
将操作范围限定在触发 Agent 的 cmux 工作区内。
- Window：macOS cmux 窗口。
- Workspace：侧边栏条目。UI 界面称其为标签页（tab）；CLI / socket API 则称其为工作区（workspace）。
- Pane：工作区内的切分区域（分栏）。
- Surface：Pane 内部的标签页，可以是终端或浏览器。
- Panel：Surface 内部的底层内容类型。建议优先使用 CLI surface 命令，而不是 panel 内部指令。
默认规则
除非用户明确要求切换到其他工作区、窗口或全局状态，否则操作必须限定在当前的调用方工作区内。不要以为视觉上处于焦点状态的工作区就是目标工作区：Agent 完全可以在一个工作区运行，而用户正在查看另一个工作区。
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 是默认的调用方终端锚点。如果这些变量缺失，请回退使用 cmux identify --json，并明确提示当前正使用处于焦点状态的上下文。
无干扰自动化
请将布局调整与焦点切换视为两个独立的事项。select-workspace、focus-pane、focus-panel 以及会改变焦点的 tab-action 动词属于影响用户体验的操作（类似鼠标点击）。切勿盲目或推测性地调用它们——即使在调用方自身的工作区内也不行，因为用户此时可能正在关注别处。
应采用增量方式一步构建布局：使用能在创建 Pane 时直接填充正确 Surface 的命令：
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
避免采用“先创建、再移动、后聚焦”的链式调用。凡是支持该参数的动词，请务必传入 --focus false（例如 move-surface --focus false 可以避免打扰用户视线；后续会有更多命令支持该参数，详见 https://github.com/manaflow-ai/cmux/issues/1418 及 https://github.com/manaflow-ai/cmux/issues/2820）。如果布局命令拒绝了合法的 surface: 或 pane: 引用，请直接报告 Bug 并停止执行，切勿通过强制聚焦来绕过该问题。
右侧辅助 Pane
对于辅助输出（预览应用、TUI、日志、临时 Shell、浏览器检查），应复用调用方终端右侧的一个辅助 Pane。请先通过 cmux identify --json、cmux list-panes 和 cmux list-pane-surfaces 检查状态，然后：
- 辅助 Pane 已存在：直接向其中添加 Surface。
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:<helper> --type terminal --focus false - 不存在辅助 Pane：仅创建一个。
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false - 如果同自动化任务残留了多个明显的旧辅助 Pane，且用户要求清理：保留一个并清理其余重复项。绝不可关闭你无法确定是否为残留辅助输出的 Pane。
通过显式的 surface 引用将命令发送至新建或复用的 Surface。连续的“打开它”请求会在右侧已有的辅助 Pane 内新建标签页（Tab），而不是继续切分出更多 Pane。
调用方终端
发起 Agent 调用的 Surface 是进行相对操作最安全可靠的锚点。
cmux send "npm test\n" # 在调用方工作区处于焦点状态的终端执行
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n" # 在具体的调用方 surface 执行
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter
除非用户明确指定了目标，否则切勿向其他工作区发送按键、关闭 Surface 或切换焦点。
移动 Surface
cmux move-surface --surface "${CMUX_SURFACE_ID}" --before surface:3 # 也支持 --after, --index
cmux move-surface --surface surface:240 --pane pane:172 --focus false
cmux drag-surface-to-split --surface surface:240 down
已知痛点：drag-surface-to-split 会走 V1 路由并依赖 UI 焦点来解析工作区，因此当调用方工作区并非视觉焦点的那个工作区时，会失败并报错 ERROR: Surface not found（详见 https://github.com/manaflow-ai/cmux/issues/1901，相关问题见 https://github.com/manaflow-ai/cmux/issues/3189）。在该问题解决之前，请一律采用增量方式构建布局。绝不要通过调用 focus-pane 或 focus-panel 来修补移动失败的异常；直接报告失败并停止操作。
侧边栏状态
将状态、进度和日志附加到当前工作区，以便侧边栏及时反映该任务的进展。
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 源码工作树中对 cmux 应用/运行时进行修改后，请从当前 worktree 使用带有 tag 的重新加载。这会创建一个隔离的应用名称、bundle ID、调试 socket 以及 DerivedData 路径。切勿构建或启动未打 tag 的 cmux DEV。
./scripts/reload.sh --tag <short-tag>
CMUX_SOCKET_PATH=/tmp/cmux-debug-<short-tag>.sock cmux identify --json
Socket 访问
优先使用 cmux 提供的 socket 路径，不要直接回退到默认路径：SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"。Socket 访问模式可能处于关闭状态、仅限于 cmux 派生的进程访问，或者对所有本地进程开放。如果命令无法连接，请在修改设置前先检查 cmux capabilities --json 和 cmux ping 的输出。
规则
- 默认在调用方工作区中操作；对于任何变更类操作，即使已设置环境变量，也优先显式指定
--workspace和--surface参数，以确保自动化操作可审计。 - 除非用户明确要求，否则切勿调用
focus-pane、focus-panel、select-workspace或任何会改变焦点的tab-action动词。 - 在
move-surface以及任何支持该参数的创建类动词上传入--focus false。 - 使用
new-pane --type ... --url ...增量构建布局，而不是“先创建、再移动、后聚焦”。 - 如果 CLI 命令拒绝了有效的 surface 或 pane 引用，请如实上报，切勿通过抢占焦点来规避问题。
- 除非用户明确指定了目标，否则不要对其他工作区进行关闭、聚焦、移动或发送输入操作。
- 在对话和示例中使用短引用（short ref）；仅在日志记录、持久化或调试时使用 UUID。
参考资料
- references/commands.md：完整的工作区、pane、surface、通知和实用命令列表。
- ../cmux-browser/SKILL.md：遵守相同当前工作区规则的浏览器 surface。
