用途:通过 cmux CLI 管理 cmux 的工作区、面板、终端输入、通知和侧边栏状态。默认以 CLI 为接口,每条命令都作用于具体的工作区、面板或表面(surface),并以可观察行为作为验证依据。
主要能力:
- 上下文确认:cmux ping 检查可用性;cmux identify --json 获取当前聚焦的窗口、工作区、面板与表面;cmux current-workspace --json 或 cmux list-workspaces --json 查询工作区。非聚焦目标需从 JSON 输出解析标识符,并用 --window、--workspace 或 --surface 指定范围,必要时用 --id-format both 区分引用 ID 与 UUID。
- 工作区与面板:cmux new-workspace、cmux select-workspace --workspace <workspace-id>、cmux new-split right(支持 left/right/up/down)、cmux list-panels --json、cmux focus-panel --panel <surface-id>。仅在用户要求时创建或关闭,关闭前需确认目标并获得明确意图。
- 终端输入:cmux send --surface <surface-id> "npm test" 发送文本,cmux send-key --surface <surface-id> enter 单独发送回车执行;send-key 支持 enter、tab、escape、backspace、delete 及方向键。不要仅为查看状态而向终端发送命令。
- 状态、进度、日志与通知:cmux set-status、cmux set-progress、cmux log、cmux notify 等,使用任务专属唯一键,只清理自己拥有的状态;clear-notifications 与 clear-log 仅在明确要求时执行;cmux sidebar-state 可查看结果状态。
使用方式:每次 shell 调用只执行一条 cmux 命令,解析 ID 或报告状态时优先使用 JSON 输出。不常见操作或需确认具体参数时,查阅技能目录中的 references/cli-reference.md。
验证与限制:验收标准是命令成功后再用独立的 cmux 查询确认结果,例如工作区选择用 current-workspace --json,面板变化用 list-panels --json 与 identify --json,状态用 sidebar-state,通知用 list-notifications --json。终端输入需报告目标与发送内容,不能声称终端命令本身成功,除非能观察到其输出。若 cmux 返回错误,应停止操作并附上错误文本。除非用户明确要求 socket 自动化,否则使用 CLI;socket 请求仅用含 id、method、params 的 JSON,未经明确批准不得启用 CMUX_SOCKET_MODE=allowAll 或修改 CMUX_SOCKET_PATH。