文档 / CLI / 编排

编排是 Orca 的结构化多智能体层：一个 Run（命名空间 + 协调器收件箱）、Tasks、Dispatches、受监督的 workers、消息以及决策门。

当你需要所有权、完成跟踪或 DAG 时使用它。对于一次性提示，使用 orca terminal send。对于无需监督的完整所有权交接，使用 orca-cli 技能中的 worktree/terminal 命令。

在使用这些命令之前，请在设置 → 实验下启用编排。CLI 会与正在运行的 Orca runtime 通信，因此 orca status --json 应首先成功。

orca orchestration run 和 run-stop（以及 coordinator-start / coordinator-stop）不产生任何效果。它们返回指向 orca skills get orchestration --full 的恢复文本。请使用下面的 Run + worker-start 流程。

核心模型¶

Run — 持久命名空间和主收件箱。从不调度或放置 workers。
Task — 带有规格、依赖项和状态的工作项：pending、ready、dispatched、completed、failed 或 blocked。
Dispatch — 任务在某个终端上的一次尝试；worker_done / 心跳的生命周期权限。
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 <taskId> --worktree current --agent codex --json
# or new worktree:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# optional per-worker model / effort (Claude, Codex, Cursor only; not with --terminal):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json

--model 接受 Claude、Codex 和 Cursor 的不透明提供商模型 ID。--effort 需要 --model，并且仅在该 agent/model 支持该级别时生效。这两个标志都不能与 --terminal（复用现有窗格）组合使用。覆盖仅适用于该次启动，并在启动回执的 launch.requested / launch.effective 下显示。联邦启动需要一个声明支持 launch-preference 的 worker 主机。

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

orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
orca orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

Worker 完成（来自 worker 窗格；包含注入的 ID）：

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

worker_done 需要 --outcome succeeded|failed。

检查 / 恢复：

orca orchestration worker-show --dispatch <dispatchId> --json
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
orca orchestration worker-stop --dispatch <dispatchId> --json
# After an accepted worker_done: reuse the same terminal for a follow-up Dispatch, or release it
# (archives inspectable output, then closes only that coordinator-owned agent terminal):
orca orchestration worker-release --dispatch <dispatchId> --json
# Keep a settled worker live for debugging when the user asked to retain it:
orca orchestration worker-retain --dispatch <dispatchId> --json
# retry placement is explicit — --retry-of does not inherit --on/worktree:
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json

不要仅仅为了重新读取输出而保持已完成 worker 终端打开——在 worker-release 之后使用 worker-read。当 release 返回 release_pending 或 release_unknown 时，不要用宽泛的 terminal close 替代；请遵循回执中的恢复操作。

联邦工作器（可选）¶

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

后续命令按 Dispatch ID 路由；不要重复 --on。

低级派发（自定义拓扑）¶

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

消息说明¶

默认 check 是绑定 Run 的最早未 ack Delivery（FIFO）。重放直到 --ack。
--peek / --all 不会消费邮件。
组地址：@all、@idle、@claude、@codex、@opencode、@gemini、@droid、@grok、@cursor、@worktree:<id> —— 绝不用于 worker_done / 心跳。
除 @worktree:<id> 外的每个组都表示发件人自身 Run 的活动 Dispatches，并投递到它们的 Dispatch 收件箱（对于嵌套协调器，则投递到子 Run 收件箱）。不在任何 Run 中的发件人会被拒绝；--run 必须与受众匹配，并且从不授予成员资格。
Run 组排除其所属协调器。提出阻塞项的 worker 发送到 run:<id>。@worktree:<id> 包括该工作区中的协调器。
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 workers in this Run only" --json

当等待处于活动状态时，CLI 每 15 秒向 stderr 输出小型 JSON 心跳行。Stdout 仍为最终命令结果。

工作者契约¶

被调度的工作者会收到一段前言，告知它们如何与协调器通信：

即使失败，也恰好发送一次 worker_done，并附带 --outcome。
包含简短的 --body 摘要：已完成什么、发现了什么，以及剩余什么。
同时包含任务 ID 和调度 ID，以便过期的重试无法完成错误的调度。
在长时间活跃工作期间发送 heartbeat 消息。
对于阻塞性问题，使用 orca orchestration ask，而不是本地 TUI 提示。

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

使用 --json 时，ask 会打印标准的 {id, ok, result, _meta} 信封，因此工作者可以使用 jq -r .result.answer 读取答案。

决策门¶

使用 ask 处理工作者到协调器的问题。当协调器已创建任务 DAG，并希望阻塞某个任务直到记录决策时，使用显式决策门：

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

orca orchestration gate-resolve --id <gateId> --resolution "yes" --json

恢复¶

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

仅当有意放弃编排状态时，才执行重置：

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

reset 会影响运行时全局编排状态。除非这是预期的清理操作，否则不要在另一个协调器处于活动状态时运行它。

选择正确的命令¶

使用 orca terminal send 向你正在监视的代理发送轻量级提示。

当工作者必须报告 worker_done、通过协调器提问，并按任务 ID 跟踪时，使用 orca orchestration worker-start（或 dispatch --inject）。

当你需要持久的 Run 命名空间和受监督的多代理循环时，使用 orca orchestration run-create + 任务 + 工作者——而不是已弃用的 orchestration run 命令。

完整指南¶

命令标志会随应用演进。安装后，代理应运行：

orca skills get orchestration --full

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca