cmux-orchestration

cmux 编排

顶层 Agent 是 控制器（Codex、Claude、Fable 或其他工具）；它会将任务委派给 工作者 TUI，由工作者收集证据、起草范围明确的补丁、运行测试并汇报。控制器负责分配任务、管理状态、控制冲突、验证、集成以及撰写最终面向用户的答复。

每次运行还会加载：

• cmux — 窗格、界面、路由、健康检查。
• cmux-workspace — 限定调用方工作区范围、复用辅助窗格、指定套接字目标、执行非干扰式自动化。

不变量

• 除非用户指定其他目标，否则所有操作都限定在调用方工作区内。
• 优先指定 CMUX_WORKSPACE_ID、CMUX_SURFACE_ID 和 CMUX_SOCKET_PATH，之后才回退到当前聚焦窗口。
• 通过明确的 surface:N 引用驱动工作者。
• 保持焦点不变 — 只有用户提出要求时，才使用 focus-pane、focus-panel、select-workspace 以及会改变焦点的标签页操作。
• 保持工作者界面打开；只有在明确要求清理或任务约定包含清理时才关闭。

预检

检查调用方上下文和当前布局：

rtk cmux identify --json
rtk cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
rtk cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json

优先使用右侧的一个辅助窗格。如果存在明显不属于调用方的辅助窗格，就在其中添加工作者界面；否则，恰好创建一个右侧终端窗格：

rtk cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<helper> --type terminal --focus false

rtk cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" \
  --type terminal --direction right --focus false

发送提示词前，先将返回的每个 surface:N 记录到状态注册表中。

启动工作者

两个默认配置 — 使用 opus 的 Claude Code（claude-opus）和使用 gpt-5.5 的 Codex（codex-gpt-5.5）— 通过明确指定的界面启动：

rtk cmux send --surface surface:<claude> \
  "rtk claude --dangerously-skip-permissions --model opus --name cmux-claude-opus\n"
rtk cmux send --surface surface:<codex> \
  "rtk codex --yolo -m gpt-5.5 -C \"$PWD\"\n"

Claude 始终使用 --dangerously-skip-permissions 启动，Codex 始终使用 --yolo 启动 — 工作者会在无人值守的情况下运行，不得因权限提示而停滞。先规划再执行的运行会添加 Claude 的 --permission-mode plan — 这些标志可以组合使用（参见先规划再委派）。

向正在运行的 TUI 发送提示词

cmux send "...\n" 只会在普通 shell 中（即上方的启动命令）提交输入。在正在运行的 TUI（Claude Code、Codex）中，末尾的 \n 会被粘贴成软换行 — 提示词不会提交，工作者会悄无声息地停滞。

• 优先将初始提示词作为启动 CLI 参数传入 （rtk claude --dangerously-skip-permissions "…提示词…"、 rtk codex "…提示词…"）— 这可避免 TUI 就绪时序问题和提交问题。例外情况：先规划再执行的 Codex 启动时不带参数（参见先规划再委派）。

• 向正在运行的 TUI 发送任何后续提示词时，先发送文本，再显式按 Enter 提交：

  rtk cmux send --surface surface:<worker> "…follow-up prompt…"
  rtk cmux send-key --surface surface:<worker> enter
  

• 使用 rtk cmux read-screen --surface surface:<worker> 确认：输入行为空，且旋转指示器／工作指示器处于活动状态。未经确认的发送不算送达。

先规划再委派

对于需要先调查再编辑的任务切片 — 根因修复、多文件或跨包改动、不熟悉的代码 — 让工作者先规划：它制定计划，你审核并接受，然后它再自动执行。启动标志、Shift+Tab 序列、状态行检查和接受菜单都必须严格遵循，且因 TUI 而异。进行先规划再委派时，启动工作者前请完整阅读 references/plan-mode.md。

委派任务包

将每个工作者提示词作为独立的任务约定发送。包含：

• 仓库路径和明确目标
• 工作者角色和模型
• 执行模式：先规划再执行，或直接执行
• 范围内的文件、软件包或界面
• 明确排除在范围外的文件和行为
• 声明认领的文件或工作切片，以避免冲突
• 预期证据：文件、行号引用、命令、差异、失败、截图以及明确说明的不确定性
• 要运行的验证命令或浏览器操作流程
• 停止条件：代码结构异常、命令反复失败、身份验证／模型阻塞，或需要修改范围外内容

优先选择小型、相互独立的工作切片。只有在控制器会立即集成并解决冲突时，才允许分配相互重叠的文件。

状态登记表

在任务日志或交接记录中维护一份精简的登记表：

• 控制器身份
• 工作器角色和模型
• workspace:N、pane:N、surface:N
• 已发送的提示词／目标和开始时间
• 状态：启动中、规划中、计划审核中、计划已接受、运行中、等待中、受阻、已报告、已验证
• 声明负责的文件或工作范围
• 工作器报告的命令和结果
• 控制器执行的验证
• 最终处置：已接受、已拒绝、已被取代或受阻

对于长时间运行的任务，请使用 cmux 侧边栏状态将进度附加到调用方工作区，并在编排完成或放弃时清除：

rtk cmux set-status orchestration "running" \
  --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
rtk cmux set-progress 0.4 --label "Workers running" \
  --workspace "${CMUX_WORKSPACE_ID:-}"
rtk cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- \
  "Started cmux orchestration"

验证工作器输出

在验证之前，应将工作器输出视为不可信内容。监控和验证时不要切换焦点：

• 以只读方式轮询或检查工作器界面；如果输出不清楚，请工作器简要汇报状态。
• 在本地重新打开引用的文件，验证影响较大的发现。
• 如果声称的测试结果关系到任务能否完成，请使用新的控制器命令重新运行测试。
• 接受任何工作器补丁前，先检查最终差异。
• 如果工作器修改了其声明范围之外的内容，请暂停集成并决定：接受、请求用户批准清理，或通过控制器修改取而代之。

停止条件

遇到以下情况时，应停止并报告，不要自行变通：

• cmux 拒绝有效的工作区、窗格或界面引用。
• 工作器 TUI 拒绝模型别名、身份验证状态、工作目录或启动标志——请准确报告阻碍，并在降级模型或切换工具前征得用户批准。
• 身份验证阻止了 TUI 运行。
• 无法可靠地观察或控制工作器输出。
• 无法通过 read-screen 确认计划模式状态行或接受菜单，或者重新规划一轮后，工作器的计划仍然超出范围。
• 多个工作器需要进行相互重叠的编辑，而控制器无法安全整合。
• 任务需要使用用户尚未批准的、会切换焦点的 cmux 命令。

图示

当视觉说明有帮助时，assets/fable-orchestrator.excalidraw（或其 PNG 变体）会展示控制器／工作器拓扑。