orchestration

Orca 跨代理協調

Orchestration 是 Orca 的結構化協調層，用於管理代理訊息、任務所有權、分派狀態以及 worker 完成追蹤。

當協調狀態很重要時，請使用此技能。對於輕量級終端提示或基本的 worktree/terminal/內建瀏覽器控制，請使用 orca-cli。

工具邊界

如果任務要求使用 Orca orchestration，協調器必須透過 orca orchestration task-create 和 orca orchestration dispatch --inject 或 orca orchestration run 建立 Orca 執行時期狀態。

請勿使用非 Orca 的子代理工具、通用代理生成 API 或僅限聊天的平行 worker 功能來替代。這些工具可能建立有用的 worker，但不會建立 Orca 任務/分派的來源記錄、注入的生命週期前置內容、worker_done 權限或決策閘門。

在聲明 worker 已透過 orchestration 管理之前，請先驗證任務/分派是否存在：

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

如果工作意外地在 Orca orchestration 外部執行，請直接說明。若要修復來源記錄，請透過新的 Orca 終端加上注入的分派來重新執行或重新驗證所需工作；請勿事後將外部 worker 描述為已協調。

使用時機

• 在代理終端之間發送/回覆/詢問，並保留持久訊息。
• 將結構化任務分派給 worker，並等待 worker_done 或 escalation。
• 追蹤具有依賴關係的任務 DAG。
• 執行協調器迴圈或決策閘門。

請勿僅因為使用者說「hand off」、「handoff」、「handover」、「give this to another agent」或要求另一個 worktree/agent/model/effort 就使用 orchestration。這些是完整所有權轉移，除非使用者明確要求監督、監控、等待 worker 完成/結果、協調 DAG、使用決策閘門或保持阻塞式詢問/回覆迴圈。

前置條件

• orca status --json 應顯示執行中的 runtime。
• orca 必須在 PATH 中（Linux 上為 orca-ide）。
• 必須在「設定 > 實驗性功能」中啟用 orchestration 實驗性功能。
• orca orchestration 指令是對執行中 Orca runtime 的 RPC 呼叫。

所有權

Orchestration 訊息和任務是 runtime 全域的。完成權限來自於活躍的分派上下文：taskId + dispatchId + 受指派者 handle。

在發送生命週期訊息之前，請分類繼承的上下文：

• 協調子任務：活躍的協調器擁有 DAG 並等待此分派。請完全遵循前置內容，包括 worker_done、heartbeat/status、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、使用決策閘門或管理 ask/reply 流程時，才使用監督式 orchestration。
• 請勿對完整交接使用 orca orchestration dispatch --inject。它會注入一個協調器前置內容，告訴 worker 發送 worker_done、heartbeat 和 ask 訊息，然後在原始終端的分派生命週期下結束其回合。
• 請勿對完整交接執行 orca orchestration task-create、orca orchestration dispatch --inject 或 orca orchestration check --wait。在傳送提示後，請勿監看終端輸出以追蹤進度。
• 僅供審查的 worker_done 會回報發現結果；它不會授權協調器編輯檔案。在僅供審查的完成之後，請綜合發現結果，如果所有權不明確則詢問決策閘門，並分派或交接修復工作，除非使用者明確要求協調器負責修復。
• 如果使用者的計畫指定了下一個擁有者代理（例如「然後使用 opencode 建立 PR」），則審查後的修正和 PR 準備工作屬於該指定的擁有者。協調器負責路由、綜合、在必要時詢問決策閘門並進行監督；指定的擁有者負責編輯檔案和建立 PR。

如果不確定，請在發送生命週期訊息前檢查 orchestration 狀態：

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 會自動從目前終端解析。
• 在手動監督 worker 時，請使用 check --wait --types worker_done,escalation,decision_gate --timeout-ms <n> 而非 sleep/poll 迴圈。回覆 decision_gate 訊息時使用 orca orchestration reply --id <msg_id> --body <answer> --json，然後繼續等待。
• 將 check --wait 的超時或 {count:0} 視為檢查點，而非 worker 失敗。長時間的編碼任務通常需要 15-60 分鐘；請持續使用滾動等待，除非您收到 worker_done/escalation、終端退出或消失，或使用者明確要求您停止。
• Heartbeat 和可見的終端活動表示 worker 仍在運作，而非完成。請勿僅因為 worker 尚未產生完成訊息就停止、關閉、終止或重新啟動 worker。
• 當 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。
• 僅對真正對多個終端有用的訊息使用群組地址，例如 status 廣播或有意的扇出問題。請勿將分派生命週期訊息發送給群組。
• worker_done 必須針對活躍前置內容中的具體協調器 handle。它是單一分派的完成權限；群組扇出會在不相關的終端中產生虛假的生命週期郵件。
• heartbeat 也屬於分派範圍。僅將其發送給具體的協調器 handle，並同時包含 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 會立即回傳一個 run ID。使用 task-list 查詢進度。對於 worker 對協調器的問題，使用 ask；它會建立一個 decision_gate 訊息，協調器使用 reply 回覆。僅對協調器管理的任務 DAG 決策使用 gate-create，而非回覆 worker 的 ask。

僅用於復原：orca orchestration reset --tasks|--messages|--all --json 會清除 runtime 全域的 orchestration 狀態。請勿在活躍協調期間執行此指令，除非明確要放棄該狀態。

完整交接

對於完整所有權轉移，請使用非生命週期的 terminal/worktree 指令，然後停止監控，除非使用者要求監督。

預設將以下請求視為完整交接：「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）不會使交接變成監督式。

監督式 orchestration 僅在使用者明確要求監督或協調時才可用：「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 也被禁止，因為它會記錄協調器擁有的追蹤狀態；如果需要任務行，表示使用者要求監督式 orchestration。請勿建立 taskId/dispatchId、注入生命週期前置內容、等待完成，或在傳送提示後讀取 worker 終端，除非是為了避免遺失初始提示。

新的頂層 worktree 交接：

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

在從活躍功能分支建立新的 worktree 之前，請決定並說明所需的 Orca 譜系是子層還是頂層。僅在新工作概念上堆疊在活躍 worktree 之下或依賴於活躍 worktree 時，才使用子 worktree 譜系。對於獨立的倉庫範圍修復、獨立功能工作或不相關的後續任務，請使用 --no-parent 建立頂層 worktree。

現有終端交接：

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 模型或努力時，請先建立獨立的 worktree，然後在該 worktree 中使用要求的指令啟動 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 的值）；除非使用者明確要求堆疊工作或「從目前分支建立分支」，否則永遠不要以目前功能分支為基礎。請將目前分支的上下文放在提示中。

Worker 終端

在建立終端之前選擇 worker 位置。「Fresh worker」表示全新的代理工作階段，而非新的 git worktree。如果任務僅限於目前 worktree、依賴未提交的檔案/成品，或必須驗證/PR 目前分支，請在活躍 worktree 中建立 worker：

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

僅在提示允許重複使用時，才在所需 worktree 中重複使用閒置的代理；否則請在該處建立新的終端。僅在明確要求或需要獨立的隔離檢出狀態時，才使用新的 worktree。對於監督式的新 worktree worker，請在建立前決定所需的 Orca 譜系：僅在新工作概念上堆疊在活躍 worktree 之下或依賴於活躍 worktree 時使用子譜系，對於獨立的倉庫範圍修復、獨立功能工作或不相關的後續任務則使用 --no-parent。請分別決定 Git 基礎分支和譜系：--no-parent 使 worktree 在 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 的 worker，請從 worktree create 讀取 id，然後使用 terminal list 取得代理 handle。僅在 Orca 管理的 worktree 內部省略 --repo；否則請傳遞 --repo <selector>。--agent 會顯示新的 worktree 並在其第一個終端中啟動選定的代理，因此請勿另外建立啟動終端。當任務必須保留在目前 worktree 時，請勿執行 worktree create。

對於完整交接或未追蹤/輕量級提示，請使用 orca worktree create --prompt ... 或 orca terminal send ...。這些路徑不會附加 taskId/dispatchId；除非提示提供了活躍的 orchestration 前置內容，否則 worker 不應發送生命週期訊息。

側邊欄譜系和 orchestration 生命週期相關但不完全相同。使用 orca terminal create --worktree active 建立的相同 worktree worker 在側邊欄中可能顯示為相同 worktree 下的對等終端/代理，儘管它在 Orca orchestration 狀態中是子分派。可見的父/子 worktree 關係需要建立子 worktree，但僅在任務可以安全地從隔離檢出執行且不需要目前工作樹中的未提交成品時才這樣做。

協調器經常需要的其他終端指令：

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 視窗。如果視窗未回傳匹配的訊息，請檢查 task-list、terminal read 或 terminal wait --for tui-idle 作為存活檢查點；如果終端仍在工作或產生活動，請繼續等待，而不是重試任務。

代理指引

• 具有有效活躍前置內容的 worker 必須恰好發送一次 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 區塊）重新與您互動。
• 對於長時間任務，僅在前置內容要求時發送 heartbeat/status，並包含兩個 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 的 worker 僅用於不需要目前未提交狀態的獨立工作。當需要相同 worktree 的工作時，請在該 worktree 中建立新的終端，並保持編輯所有權清晰。

範例

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 -> worker -> dispatch --inject -> check --wait）或 orchestration run。

Worker：如果目前提示包含活躍的分派前置內容，請執行任務，對阻塞式問題使用 ask，並發送一次 worker_done 及所需的 payload。如果前置內容已過期或不存在，請勿發送生命週期訊息；檢查狀態或將提示視為一般交接。