第27章 编排（Orchestration）

编排通过 Run、任务、受监督的 worker、消息和决策门来协调多个 agent。编排是 Orca 的结构化多 agent 层，包含 Run（命名空间 + 协调器收件箱）、任务（Task）、派发（Dispatch）、受监督的 worker、消息和决策门（decision gate）。

当你需要明确归属、完成状态跟踪或 DAG 时，使用编排。一次性提示用 orca terminal send。如果要完整移交所有权且无需监督，使用 orca-cli skill 中的 worktree/terminal 命令。

核心模型

Run —— 持久化的命名空间和主收件箱。从不负责调度或安置 worker。

Task —— 一项工作，包含 spec、依赖和状态：pending、ready、dispatched、completed、failed 或 blocked。

Dispatch —— 任务在某终端上的一次执行尝试，是 worker_done / heartbeat 的生命周期权威。

Message —— 收件箱里的邮件（status、dispatch、worker_done、escalation、question、heartbeat 等）。

Decision gate —— 由协调器持有的一道问题，在解决之前会阻塞对应任务。

完成状态的权威来源是当前活跃的 dispatch 上下文。worker 的完成和心跳消息必须同时携带 taskId 和 dispatchId。

终端里打印的任务 ID（如 task_...）是可点击的链接。点击后会向 Orca runtime 请求该任务当前的 dispatch 并聚焦到对应终端——即使任务运行在远程或 SSH runtime 上也一样。

首选的受监督循环

``` orca orchestration run-create --objective "Split checkout QA and summarize blockers" --json orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json orca orchestration worker-start --task --worktree current --agent codex --json # 或新建 worktree： orca orchestration worker-start --task --worktree new-child --name billing-audit --agent codex --setup run --json # 可选：为单个 worker 指定模型/投入度（支持 Claude、Codex、Muse、Cursor、Antigravity、OpenCode；不能与 --terminal 同用）： orca orchestration worker-start --task --worktree current --agent claude --model --effort high --json # 在本地子 worktree 中把 Antigravity 作为受监督 worker 运行： orca orchestration worker-start --task --worktree new-child --name research --agent antigravity --setup run --json ```

--model 接受 Claude、Codex、Muse、Cursor、Antigravity 和 OpenCode 的原生模型 ID。Muse 需传入你的 Muse 安装所接受的模型 id（例如 muse-spark-1.3）；Antigravity 使用 agy models 列出的模型 slug。OpenCode worker 的模型会在执行主机上验证，且只对该 worker 生效，不会改变其他启动的默认模型。--effort 必须搭配 --model，且只在对应 agent/模型支持该等级时生效。这两个参数都不能与 --terminal（复用已有 pane）同时使用。对于比 Orca 内置列表更新的 Codex 模型（例如 gpt-6.x），只要已安装的 Codex 支持，--effort 就接受完整的已知取值，包括 max 和 ultra；未知的 effort 名称仍会被拒绝。这些覆盖只对本次启动生效，并显示在启动回执的 launch.requested / launch.effective 中。联邦式启动需要 worker 主机声明支持 launch-preference。

开启 Chat UI 时，worker-start 会用与新 agent 标签页相同的方式启动受支持的 agent：agent 和主机支持时用结构化 chat，否则用终端。--terminal 仍然复用已有 pane。

Orca 会在启动 worker 之前，先为本地 Antigravity 子 worktree 准备好信任配置。通过 SSH 的 Antigravity 监督不支持此信任配置。其常规 agent 特性见 Supported agents。

等待完成（处理 Delivery 中的每条消息，然后 ack）：

``` orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json orca orchestration check --ack --wait --types worker_done,escalation,question --timeout-ms 900000 --json ```

Worker 完成上报（在 worker pane 中执行；带上注入的 ID）：

``` orca orchestration send \ --type worker_done \ --subject "Completed mobile audit" \ --body "Fixed footer overlap; no follow-ups." \ --task-id \ --dispatch-id \ --outcome succeeded \ --files-modified "src/app/settings/Billing.tsx" \ --json ```

worker_done 必须指定 --outcome succeeded|failed。

查看 / 恢复：

``` orca orchestration worker-show --dispatch --json orca orchestration worker-read --dispatch --limit 50 --json orca orchestration worker-stop --dispatch --json # worker_done 被接受后：复用同一终端进行后续 Dispatch，或释放它 # （先归档可查看的输出，然后只关闭那个由协调器持有的 agent 终端）： orca orchestration worker-release --dispatch --json # 用户要求保留时，让已结算的 worker 保持存活以便调试： orca orchestration worker-retain --dispatch --json # 重试的放置是显式的 —— --retry-of 不会继承 --on/worktree： orca orchestration worker-start --task --retry-of --worktree current --agent codex --json ```

不要为了回看输出而让已完成的 worker 终端一直开着——worker-release 之后用 worker-read 即可。release 返回 release_pending 或 release_unknown 时，不要图省事粗暴地关闭终端；按回执给出的恢复操作执行。

联邦式 worker（可选）

``` orca orchestration worker-start \ --task \ --on windows \ --worktree new-top-level \ --repo \ --name remote-worker \ --agent codex \ --setup run \ --json orca orchestration send --to dispatch: --subject "Follow-up" --body "…" --json ```

后续命令通过 Dispatch ID 路由，不要重复 --on。

低层派发（自定义拓扑）

``` orca worktree create --name billing-audit --agent codex --json orca terminal wait --terminal --for tui-idle --timeout-ms 60000 --json orca orchestration dispatch --task --to --inject --json ```

消息机制要点

默认 check 读取所绑定 Run 中最旧的未 ack Delivery（FIFO），在 --ack 之前会反复读取。

--peek / --all 不会消费消息。

组地址：@all、@idle、@claude、@codex、@opencode、@gemini、@droid、@grok、@cursor、@worktree: —— 不得用于 worker_done / heartbeat。

在 PowerShell 中组地址要加引号：--to "@all"。

``` orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json orca orchestration send --to @idle --subject "Anyone free?" --json orca orchestration send --to @codex --subject "Codex agents only" --json ```

wait 期间，CLI 每 15 秒向 stderr 输出一行小型 JSON 心跳。stdout 始终只输出最终命令结果。

Worker 契约

被派发的 worker 会收到一段 preamble，告知它们如何与协调器通信：

发送 worker_done 有且仅有一次——即使失败也要发——并带 --outcome。

附带简短的 --body 摘要：做了什么、发现了什么、还剩什么。

同时携带 task ID 和 dispatch ID，防止过期的重试错误地完成错误的 dispatch。

长时间活跃工作期间发送 heartbeat 消息。

有阻塞性问题就用 orca orchestration ask，不要用本地 TUI 提示。

``` orca orchestration ask \ --to \ --question "Should I update the shared component or only this page?" \ --options "shared,page-only" \ --timeout-ms 600000 \ --json ```

使用 --json 时，ask 输出单个 JSON 对象，方便 worker 用管道接 jq -r .answer。

决策门

worker 向协调器提问用 ask。当协调器已建好任务 DAG、并希望在某项决策落定前阻塞任务时，用显式的 gate：

``` orca orchestration gate-create \ --task \ --question "Merge the shared button change into the task branch?" \ --options '["yes","no"]' \ --json

orca orchestration gate-resolve --id --resolution "yes" --json ```

恢复

``` orca orchestration dispatch-show --task --json orca orchestration dispatch-show --task --preamble --json orca orchestration task-list --json orca orchestration task-update --id --status blocked --result '{"reason":"waiting on credentials"}' --json ```

只有当你明确打算放弃编排状态时才执行重置：

``` orca orchestration reset --tasks --json orca orchestration reset --messages --json orca orchestration reset --all --json ```

reset 影响的是 runtime 级全局编排状态。有其他协调器在运行时不要执行，除非那正是你想要的清理操作。

选择合适的命令

对你正在监视的 agent 发轻量提示，用 orca terminal send。

需要 worker 上报 worker_done、通过协调器提问、并按任务 ID 跟踪时，用 orca orchestration worker-start（或 dispatch --inject）。

想要持久化的 Run 命名空间和受监督的多 agent 循环时，用 orca orchestration run-create + 任务 + worker——而不是已废弃的 orchestration run 命令。

完整指南

命令参数随应用版本演进。安装后，agent 应执行：

``` orca skills get orchestration --full ```