orchestration

Orca 智能体间编排

编排是Orca用于智能体消息、任务所有权、分发状态和工作者完成跟踪的结构化协调层。

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

工具边界

如果任务要求使用Orca编排，协调器必须使用orca orchestration task-create和orca orchestration dispatch --inject或orca orchestration run创建Orca运行时状态。

不要用非Orca子智能体工具、通用智能体生成API或仅聊天的并行工作者功能来替代。这些工具可能创建有用的工作者，但不会创建Orca任务/分发溯源、注入的生命周期前言、worker_done权限或决策门。

在声称工作者已编排之前，验证任务/分发是否存在：

orca orchestration task-list --json
orca orchestration dispatch-show --task <task_id> --json

如果工作意外地在Orca编排之外运行，请如实说明。要修复溯源，通过新的Orca终端加上注入的分发重新运行或重新验证所需工作；不要事后将外部工作者描述为已编排。

何时使用

• 在智能体终端之间发送/回复/询问，带有持久消息。
• 向工作者分发结构化任务并等待worker_done或escalation。
• 跟踪具有依赖关系的任务DAG。
• 运行协调器循环或决策门。

不要仅仅因为用户说“hand off”、“handoff”、“handover”、“give this to another agent”或要求另一个工作树/智能体/模型/努力程度就使用编排。这些是完全所有权转移，除非用户明确要求监督、监控、等待工作者完成/结果、协调DAG、使用决策门或保持阻塞式询问/回复循环。

前置条件

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

所有权

编排消息和任务是运行时全局的。完成权限来自活动的分发上下文：taskId + dispatchId + 受让人句柄。

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

• 协调子任务：活动协调器拥有DAG并等待此分发。严格遵循前言，包括worker_done、心跳/状态、ask和escalation。
• 完全交接意味着所有权转移，而非监督分发。原始参与者不监控DAG，因此除非用户明确要求监督，否则不要创建生命周期义务。
• 默认将包含“hand off”、“handoff”、“handover”、“give this to another agent”、“give this to another worktree”、“another agent”或“another worktree”的请求归类为完全交接，即使用户指定了自定义模型或推理努力程度。
• 仅当用户明确要求“supervise”、“monitor”、“wait”、“track completion”、“wait for worker_done”、返回结果、协调DAG、使用决策门或管理询问/回复流程时，才使用监督编排。
• 不要对完全交接使用orca orchestration dispatch --inject。它会注入一个协调器前言，告诉工作者发送worker_done、心跳和ask消息，然后在原始终端的分发生命周期下结束其轮次。
• 不要对完全交接运行orca orchestration task-create、orca orchestration dispatch --inject或orca orchestration check --wait。在传递提示后不要窥视终端输出来监控进度。
• 仅审查的worker_done报告发现；它不授权协调器编辑文件。在仅审查完成后，综合发现，如果所有权不明确则询问决策门，并分发或交接修复，除非用户明确要求协调器拥有修复。
• 如果用户的计划指定了下一个所有者智能体（例如，“然后使用opencode创建PR”），则审查后的更正和PR准备工作属于该指定所有者。协调器负责路由、综合、在需要时询问决策门并监督；指定所有者编辑文件并创建PR。

如果不清楚，在发送生命周期消息之前检查编排状态：

orca orchestration task-list --json
orca terminal list --json
# 如果继承的上下文包含任务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会自动从当前终端解析。
• 在手动监督工作者时，使用check --wait --types worker_done,escalation,decision_gate --timeout-ms <n>而不是睡眠/轮询循环。对decision_gate消息使用orca orchestration reply --id <msg_id> --body <answer> --json回复，然后继续等待。
• 将check --wait超时或{count:0}视为检查点，而非工作者失败。长时间的编码任务通常运行15-60分钟；继续使用滚动等待，除非收到worker_done/escalation、终端退出或消失，或用户明确要求停止。
• 心跳和可见的终端活动意味着工作者存活，而非完成。不要仅仅因为工作者尚未产生完成消息就停止、关闭、杀死或重启工作者。
• 当工作者需要来自协调器的阻塞式答案时使用ask；它会等待回复并直接返回答案。
• check --wait一次返回一条消息。如果N个工作者可能同时完成，则循环N次，并在每次完成后分发新就绪的任务。
• 组地址包括@all、@idle、@claude、@codex、@opencode、@gemini、@droid和@worktree:<id>。
• 消息类型包括status、dispatch、worker_done、merge_ready、escalation、handoff、decision_gate和heartbeat。
• 仅对真正对多个终端有用的消息使用组地址，例如status广播或有意的扇出问题。不要向组发送分发生命周期消息。
• worker_done必须针对活动前言中的具体协调器句柄。它是一个分发的完成权限；组扇出会在不相关的终端中创建虚假的生命周期邮件。
• heartbeat也是分发范围的。仅向具体的协调器句柄发送，并同时包含taskId和dispatchId；对于广泛的进度更新，使用status。

任务与分发

任务是工作项，分发将其分配给终端，门则阻止进度，直到协调器或用户决策被记录。

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将任务规范加上前言发送到已识别的智能体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清除运行时全局的编排状态。在活动协调期间不要运行它，除非明确放弃该状态。

完全交接

对于完全所有权转移，使用非生命周期的终端/工作树命令，然后停止监控，除非用户要求监督。

默认将这些视为完全交接请求：“hand off”、“handoff”、“handover”、“give this to another agent”、“give this to another worktree”、“send this to another agent”、“another agent”、“another worktree”或“launch another agent to own this.”自定义模型或推理努力程度词如gpt-5.5、high或xhigh不会使交接变为监督。

监督编排仅在用户明确要求监督或协调时可用：“supervise”、“monitor”、“wait for worker_done”、“wait for results”、“track completion”、“DAG”、“decision gate”、“ask/reply”或“coordinate workers.”

不要对完全交接运行orca orchestration task-create、orca orchestration dispatch --inject或orca orchestration check --wait。task-create也被禁止，因为它记录协调器拥有的跟踪状态；如果需要任务行，则用户要求了监督编排。不要创建taskId/dispatchId、注入生命周期前言、等待完成或在提示传递后读取工作者终端，除非是为了避免丢失初始提示。

新的顶级工作树交接：

orca worktree create --name <task-name> --no-parent --agent codex --prompt "<task brief>" --json

在从活动特性分支创建新工作树之前，决定并说明所需的Orca谱系是子级还是顶级。仅当新工作在概念上堆叠在活动工作树之下或依赖于活动工作树时，才使用子工作树谱系。对于独立的仓库范围修复、独立特性工作或不相关的后续任务，使用--no-parent创建顶级工作树。

现有终端交接：

orca terminal send --terminal <handle> --text "<task brief>" --enter --json

自定义Codex模型/努力程度交接：

orca worktree create --agent codex --prompt ...启动已知的Codex智能体，但不接受Codex特定的--model或-c model_reasoning_effort=...参数。当用户要求特定的Codex模型或努力程度时，首先创建独立的工作树，在该工作树中使用请求的命令启动Codex，仅在提示传递可能竞争启动时等待TUI就绪，发送提示，然后停止：

orca worktree create --name <task-name> --no-parent --json
orca terminal create --worktree id:<newWorktreeId> --title <task-name> --command 'codex --model gpt-5.5 -c model_reasoning_effort="xhigh"' --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca terminal send --terminal <handle> --text "<task brief>" --enter --json

仅在需要避免丢失提示时等待tui-idle。不要监控任务完成。

--no-parent仅控制Orca谱系；它不选择Git基础。如果工作应从仓库默认基础开始，省略--base-branch以便Orca使用该默认值，或显式传递仓库默认基础（origin/main、origin/master或orca repo show --repo <selector> --json值）；除非用户明确要求堆叠工作或“从当前分支”，否则永远不要基于当前特性分支。将当前分支上下文放在提示中。

工作者终端

在创建终端之前选择工作者位置。Fresh worker意味着新的智能体会话，而不是新的git工作树。如果任务仅限当前工作树、依赖于未提交的文件/工件，或必须验证/PR当前分支，则在活动工作树中创建工作者：

orca terminal create --worktree active --title <task-name> --command "codex" --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json

仅在提示允许重用的情况下重用所需工作树中的空闲智能体；否则在那里创建新终端。仅当明确请求或意图使用独立的隔离检出状态时，才使用新工作树。对于监督的新工作树工作者，在创建之前决定所需的Orca谱系：仅当工作在概念上堆叠在活动工作树之下或依赖于活动工作树时使用子谱系，对于独立的仓库范围修复、独立特性工作或不相关的后续任务使用--no-parent。独立于谱系决定Git基础：--no-parent使工作树在Orca中成为顶级，而省略--base-branch则使用仓库默认基础。

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读取ID，然后使用terminal list获取智能体句柄。仅在Orca管理工作树内部省略--repo；否则传递--repo <selector>。--agent会揭示新工作树并在其第一个终端中启动所选智能体，因此不要创建单独的启动终端。当任务必须留在当前工作树中时，不要运行worktree create。

对于完全交接或未跟踪/轻量级提示，使用orca worktree create --prompt ...或orca terminal send ...。这些路径不附加taskId/dispatchId；工作者不应发送生命周期消息，除非提示提供了活动编排前言。

侧边栏谱系和编排生命周期相关但不相同。使用orca terminal create --worktree active创建的同一工作树工作者可能在侧边栏中显示为同一工作树下的对等终端/智能体，即使它在Orca编排状态中是子分发。可见的父/子工作树关系需要创建子工作树，但仅当任务可以安全地从隔离检出运行且不需要当前工作树中未提交的工件时才这样做。

协调器经常需要的其他终端命令：

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，则正常创建工作树，然后运行orca terminal create --worktree <selector> --command "codex" --json或--command "claude"。

在分发之前等待tui-idle。始终传递--timeout-ms；实际的编码任务可能需要15-60分钟。在监督期间，使用滚动check --wait窗口。如果窗口没有返回匹配消息，检查task-list、terminal read或terminal wait --for tui-idle作为存活检查点；如果终端仍在工作或产生活动，则继续等待，而不是重试任务。

智能体指南

• 具有有效活动前言的工作者必须恰好发送一次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
• 发送worker_done后，结束轮次并在智能体提示处空闲。不要轮询或继续调用orca orchestration check；协调器会通过新的终端输入传递新的前言+TASK块来重新接洽你。
• 对于长时间任务，仅当前言要求时发送心跳/状态，包括两个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步的依赖链。
• 优先选择工作树间工作者仅用于不需要当前未提交状态的独立工作。当需要同一工作树工作时，在该工作树中创建新终端并保持编辑所有权清晰。

示例

orca terminal create --worktree active --title login-css-worker --command "claude" --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 900000 --json

下一步行动

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

工作者：如果当前提示包含活动分发前言，执行任务，对阻塞问题使用ask，并使用所需负载发送一次worker_done。如果前言过时或缺失，不要发送生命周期消息；检查状态或将提示视为普通交接。