orchestration

Orca Agent 间编排

🧭 调度后端 — 选择成本更低的 Agent/模型、并行运行多个 worker、使用 opencode/orchestration 语法 → 查看 orca-dispatch-reference（唯一事实来源，请勿在此重复语法）。

编排是 Orca 的结构化协调层，用于管理 Agent 消息、任务归属、调度状态和 worker 完成情况。

当协调状态很重要时，请使用此技能。对于轻量级终端提示词，或基本的 worktree/终端/内置浏览器控制，请使用 orca-cli。

适用场景

• 在 Agent 终端之间发送、回复和提问，并保留消息。
• 向 worker 分派结构化任务，并等待 worker_done 或 escalation。
• 跟踪具有依赖关系的任务 DAG。
• 运行协调器循环或决策关卡。

前提条件

• orca status --json 应显示运行中的 runtime。
• orca 必须在 PATH 中（Linux 上为 orca-ide）。
• 必须在 Settings > Experimental 中启用编排实验性功能。
• orca orchestration 命令是对运行中的 Orca runtime 发起的 RPC 调用。

归属

编排消息和任务是 runtime 全局的。完成权限由活动调度上下文决定：taskId + dispatchId + 受派者 handle。

发送生命周期消息前，先对继承的上下文进行分类：

• 协调中的子任务：有一个活动协调器负责 DAG，并等待此调度完成。严格遵循前置说明，包括 worker_done、心跳/状态、ask 和 escalation。
• 完整移交：原执行者已移交所有权，且不会进行监控。在当前会话中完成工作。只有在用户提出要求或你主动拆分出新的子任务时，才创建新的协调器；如果要启动 worker，请使用当前 worktree 的协调器 handle，并使用 --worktree active 之类的选择器。

如不确定，请先检查编排状态，再发送生命周期消息：

orca orchestration task-list --json
orca terminal list --json
# If inherited context includes a task id:
orca orchestration dispatch-show --task <task_id> --json

消息

orca orchestration send --to <handle|@group> --subject <text> [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]
orca orchestration check [--terminal <handle>] [--unread] [--types <type,...>] [--inject] [--wait] [--timeout-ms <n>] [--json]
orca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]
orca orchestration ask --to <handle> --question <text> [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]
orca orchestration inbox [--limit <n>] [--json]

规则：

• 除非要冒充其他终端，否则省略 --from；Orca 会根据当前终端自动解析。
• 手动监督 worker 时，请使用 check --wait --types worker_done,escalation,decision_gate --timeout-ms <n>，而不是循环休眠/轮询。使用 orca orchestration reply --id <msg_id> --body <answer> --json 回复 decision_gate 消息，然后继续等待。
• 当 worker 需要协调器提供阻塞式答复时，请使用 ask；它会等待回复并直接返回答案。
• check --wait 每次只返回一条消息。如果 N 个 worker 可能同时完成，请循环执行 N 次，并在每次完成后分派新就绪的任务。
• 群组地址包括 @all、@idle、@claude、@codex、@opencode、@gemini、@droid 和 @worktree:<id>。
• 消息类型包括 status、dispatch、worker_done、merge_ready、escalation、handoff、decision_gate 和 heartbeat。

任务与调度

任务是工作项，调度会将其分配给某个终端，而关卡会阻止流程继续，直到记录协调器或用户的决定。

orca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]
orca orchestration task-list [--status <status>] [--ready] [--json]
orca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]
orca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]
orca orchestration dispatch-show --task <task_id> [--json]

任务状态：pending、ready、dispatched、completed、failed、blocked。

调度规则：

• --inject 会将任务规格和前置说明发送到可识别的 Agent CLI，使其能够报告 worker_done。
• 如果目标是普通 shell，请省略 --inject；如有需要，可为跟踪目的进行调度，然后手动使用 orca terminal send --terminal <handle> --text <prompt> --enter --json 发送提示词。
• 单个任务连续失败 3 次后，调度上下文会触发熔断，该任务将被标记为失败。

门控与协调器

orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]
orca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]
orca orchestration gate-list [--task <task_id>] [--status <status>] [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]

run 会立即返回一个运行 ID。使用 task-list 查询进度。使用 ask 向协调器提问；它会创建一条 decision_gate 消息，由协调器通过 reply 回答。仅在协调器管理的任务 DAG 决策中使用 gate-create，不要用它回答工作者的 ask。

仅用于恢复：orca orchestration reset --tasks|--messages|--all --json 会清除运行时全局协调状态。除非明确要放弃该状态，否则不要在协调进行期间运行此命令。

工作者终端

对于受跟踪的协调工作，先创建不带提示词的工作者，等待其空闲，然后使用 --inject 分派任务：

orca worktree create --name <task-name> --agent codex --json
orca terminal list --worktree id:<newWorktreeId> --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json

从 worktree create 的输出中读取新的 worktree ID，然后使用 terminal list 获取 Agent 终端句柄。仅在 Orca 管理的 worktree 内运行时才省略 --repo；否则传入 --repo <selector>。--agent 会显示新的 worktree，并在其第一个终端中启动所选 Agent，因此不要另行创建启动终端。需要控制设置行为时使用 --setup run|skip|inherit，需要执行独立工作时使用 --no-parent。

仅将 orca worktree create --prompt ... 或 orca terminal send ... 用于未跟踪的轻量级提示词。这些路径不会附加 taskId/dispatchId；除非提示词提供了有效的协调前导信息，否则工作者不应发送生命周期消息。

协调器通常还需要使用的其他终端命令：

orca terminal list [--worktree <selector>] [--json]
orca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]
orca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json
orca terminal read --terminal <handle> --json
orca terminal send --terminal <handle> --text <text> --enter --json

如果较旧的 CLI 不接受 worktree create --agent，请正常创建 worktree，然后运行 orca terminal create --worktree <selector> --command "codex" --json 或 --command "claude"。

分派前等待 tui-idle。务必传入 --timeout-ms；实际编码任务可能需要 15-60 分钟。如果 check --wait 超时，且没有 worker_done 或 escalation，则改用 terminal wait --for tui-idle，然后运行 terminal read。

Agent 指引

• 带有有效实时前导信息的工作者必须恰好发送一次 worker_done，即使任务失败也不例外： orca orchestration send --to <coordinator_handle> --type worker_done --subject "<short status>" --body "<3-sentence summary: what you did, what you found, what's left>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["path/a"],"reportPath":"<optional>"}' --json
• 对于耗时较长的任务，仅在前导信息要求时发送心跳/状态，并包含两个 ID： orca orchestration send --to <coordinator_handle> --type heartbeat --subject "alive" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","phase":"implementing"}' --json
• 如果任务完成前受阻，请使用 ask；仅当职责归属明确且需要协调器介入时，才使用 escalation。
• 除非当前提示词明确要求协调器继续参与，否则应将从终端历史记录或完整交接中继承的前导信息视为过时信息。
• 协调器应将 task-list --ready 用作外部记忆，分批并行分派任务，并避免依赖链深度超过 3-4 步。
• 并行实施时优先使用不同 worktree 的工作者；仅当任务互补且不会编辑相同文件时，才在同一 worktree 中使用分屏。

示例

orca worktree create --name login-css-worker --agent claude --json
orca terminal list --worktree id:<newWorktreeId> --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration task-create --spec "Fix the login button CSS" --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json
orca orchestration check --wait --types worker_done,escalation,decision_gate --timeout-ms 300000 --json

下一步操作

协调器：确认 orca status --json，如果继承了状态，则检查 task-list/dispatch-show，然后选择手动循环（task-create -> worker -> dispatch --inject -> check --wait）或 orchestration run。

工作者：如果当前提示词包含有效的分派前导信息，请执行任务；遇到阻塞性问题时使用 ask，并使用所需负载恰好发送一次 worker_done。如果前导信息已过时或不存在，请勿发送生命周期消息；检查状态，或将提示词视为普通交接。