Back to Details

orchestration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Orca Inter-Agent Orchestration

Orca 智能体间编排

Use this skill when the task involves coordinating multiple coding agents through Orca's orchestration system. For basic terminal and worktree management, use the 
orca-cli
skill instead.
当任务需要通过Orca的编排系统协调多个编码Agent时，请使用本技能。如需基础终端和工作树管理，请改用
orca-cli
技能。

When To Use

适用场景

  • You need to send messages between agent terminals
  • You need to decompose a spec into parallel subtasks with dependencies
  • You need to dispatch tasks to worker agents with structured feedback
  • You need to act as a coordinator managing a multi-agent workflow
  • You need to create decision gates for human-in-the-loop checkpoints
  • 需要在Agent终端间发送消息
  • 需要将需求分解为带有依赖关系的并行子任务
  • 需要向Worker Agent调度任务并获取结构化反馈
  • 需要作为协调器管理多Agent工作流
  • 需要为人工介入检查点创建决策门

Preconditions

前提条件

  • Orca must be running (
    orca status --json
    should return 
    runtime: true
    ).
  • The 
    orca
    CLI must be on PATH (installed via Settings > Browser > Enable Orca CLI).
  • The orchestration experimental feature must be enabled in Settings > Experimental.
  • All 
    orca orchestration
    commands are RPC calls to the running Orca runtime — they require an active Orca session.
  • Orca必须处于运行状态（执行
    orca status --json
    应返回
    runtime: true
    ）。
  • orca
    CLI必须已添加至PATH（可通过Settings > Browser > Enable Orca CLI安装）。
  • 必须在Settings > Experimental中启用编排实验性功能。
  • 所有
    orca orchestration
    命令都是对运行中Orca runtime的RPC调用——需要活跃的Orca会话。

Command Surface

命令集

Messaging

消息传递

Inter-agent messaging via persistent SQLite-backed mail store. Messages are delivered automatically when the recipient agent goes idle (push-on-idle).
bash
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 inbox [--limit <n>] [--json]
Why: 
--from
auto-resolves via the 
ORCA_TERMINAL_HANDLE
environment variable injected into every Orca-managed terminal. Omit it unless impersonating another terminal.
Why: 
--inject
formats messages as readable banners with priority indicators (
[HIGH]
, 
[URGENT]
) for agent prompt injection. Use 
--json
for machine-readable output.
Why: 
--wait
blocks until a matching message arrives or the timeout expires (default 2 minutes). This replaces sleep+poll loops. If unread messages already exist, returns immediately. Combine with 
--types
to wait for specific message types (e.g. 
--wait --types worker_done --timeout-ms 120000
).
Message types: 
status
(general), 
dispatch
(assign work), 
worker_done
(signal completion), 
merge_ready
(branch ready for merge), 
escalation
(issue requiring attention), 
handoff
(pass work to another agent), 
decision_gate
(human-in-the-loop).
Priority levels: 
normal
, 
high
, 
urgent
.
Group addresses resolve to terminal handles:
GroupResolves To
@all
All terminal handles except sender
@idle
Handles where the agent is currently idle
@claude
Handles running Claude Code
@codex
Handles running Codex
@opencode
Handles running OpenCode
@gemini
Handles running Gemini
@worktree:<id>
All handles in a specific worktree
Group messages fan out: one message per recipient, shared 
thread_id
, independent read tracking.
基于持久化SQLite存储的智能体间消息传递。当接收方Agent处于空闲状态时，消息会自动投递（push-on-idle机制）。
bash
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 inbox [--limit <n>] [--json]
说明：
--from
会通过注入到每个Orca管理终端的
ORCA_TERMINAL_HANDLE
环境变量自动解析。除非需要模拟其他终端，否则无需指定该参数。
说明：
--inject
会将消息格式化为带有优先级标识（
[HIGH]
、
[URGENT]
）的可读横幅，用于Agent提示注入。使用
--json
可获取机器可读的输出。
说明：
--wait
会阻塞直到匹配的消息到达或超时（默认2分钟）。这替代了睡眠+轮询循环。如果已有未读消息，会立即返回。可搭配
--types
等待特定类型的消息（例如
--wait --types worker_done --timeout-ms 120000
）。
消息类型：
status
（通用状态）、
dispatch
（分配工作）、
worker_done
（任务完成信号）、
merge_ready
（分支可合并）、
escalation
（需关注的问题）、
handoff
（转交工作给其他Agent）、
decision_gate
（人工介入）。
优先级级别：
normal
、
high
、
urgent
。
群组地址会解析为终端句柄：
群组解析目标
@all
除发送方外的所有终端句柄
@idle
当前Agent处于空闲状态的句柄
@claude
运行Claude Code的句柄
@codex
运行Codex的句柄
@opencode
运行OpenCode的句柄
@gemini
运行Gemini的句柄
@worktree:<id>
指定工作树中的所有句柄
群组消息会扩散发送：每个接收方一条消息，共享
thread_id
，独立跟踪已读状态。

Tasks

任务管理

Task tracking with DAG dependencies. A task becomes 
ready
when all tasks in its 
deps
array are 
completed
.
bash
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]
Task statuses: 
pending
(waiting on deps), 
ready
(deps met, dispatchable), 
dispatched
(assigned to a terminal), 
completed
, 
failed
, 
blocked
(waiting on a decision gate).
Why: when a task is marked 
completed
, the runtime automatically promotes any pending tasks whose deps are now all satisfied to 
ready
. This is the DAG resolution step.
基于DAG依赖的任务跟踪。当任务的
deps
数组中所有任务都标记为
completed
时，该任务会变为
ready
状态。
bash
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]
任务状态：
pending
（等待依赖）、
ready
（依赖满足，可调度）、
dispatched
（已分配至终端）、
completed
、
failed
、
blocked
（等待决策门）。
说明：当任务标记为
completed
时，runtime会自动将所有依赖已满足的待处理任务升级为
ready
状态。这是DAG解析步骤。

Dispatch

任务调度

Dispatch assigns a ready task to a terminal. Optionally injects the task spec + preamble into the terminal so the agent knows how to communicate back.
bash
orca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]
orca orchestration dispatch-show --task <task_id> [--json]
Why: 
--inject
sends a preamble that teaches the agent how to use 
orca orchestration send --type worker_done
to report completion. All agents have 
orca
on PATH and can execute shell commands. The preamble maximizes structured feedback but the system works without it (coordinator falls back to idle detection + output reading).
Why: 
--inject
requires a recognized agent CLI (e.g. Claude Code) running in the target terminal. If the terminal is a bare shell, omit 
--inject
and send the prompt manually with 
terminal send
.
Why: dispatch contexts are separate from tasks (sling pattern). A task can be dispatched, fail, and be re-dispatched to a different terminal — the task stays clean while dispatch contexts track retry state.
Circuit breaker: After 3 consecutive failures on a task, the dispatch context is marked 
circuit_broken
. The task is marked 
failed
to prevent infinite retry loops.
调度会将就绪任务分配给终端。可选择将任务规格+前置内容注入终端，让Agent知晓如何反馈。
bash
orca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]
orca orchestration dispatch-show --task <task_id> [--json]
说明：
--inject
会发送一段前置内容，指导Agent使用
orca orchestration send --type worker_done
报告任务完成。所有Agent的PATH中都已配置
orca
，可执行shell命令。前置内容可最大化结构化反馈，但即使没有该内容系统也能正常工作（协调器会 fallback 到空闲检测+输出读取）。
说明：
--inject
要求目标终端运行可识别的Agent CLI（如Claude Code）。如果终端是裸shell，请省略
--inject
，改用
terminal send
手动发送提示。
说明：调度上下文与任务是分离的（sling模式）。一个任务可以被调度、失败，然后重新调度到不同的终端——任务保持干净，而调度上下文跟踪重试状态。
熔断机制：任务连续失败3次后，调度上下文会标记为
circuit_broken
。任务会标记为
failed
，以避免无限重试循环。

Decision Gates

决策门

Human-in-the-loop decision points that block a task until resolved.
bash
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]
Why: creating a gate blocks the task and completes its active dispatch. Resolving a gate sets the task back to 
ready
with the resolution context included in the next dispatch preamble.
Gate statuses: 
pending
, 
resolved
, 
timeout
.
人工介入的决策点，会阻塞任务直到问题解决。
bash
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]
说明：创建决策门会阻塞任务并完成其当前调度。解决决策门后，任务会回到
ready
状态，下次调度的前置内容会包含解决上下文。
决策门状态：
pending
、
resolved
、
timeout
。

Coordinator

协调器

Start an automated coordinator loop that dispatches ready tasks, processes 
worker_done
/
escalation
messages, and advances the task DAG.
bash
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]
Why: 
run
returns immediately with a run ID. The coordinator loop runs in the background inside the Orca runtime. Query progress via 
orca orchestration task-list
. Only one coordinator can run at a time.
Coordinator phases: 
decomposing
→ 
dispatching
→ 
monitoring
→ 
merging
→ 
done
.
启动自动化协调器循环，调度就绪任务、处理
worker_done
/
escalation
消息，并推进任务DAG。
bash
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]
说明：
run
命令会立即返回一个运行ID。协调器循环在Orca runtime后台运行。可通过
orca orchestration task-list
查询进度。同一时间只能运行一个协调器。
协调器阶段：
decomposing
→ 
dispatching
→ 
monitoring
→ 
merging
→ 
done
。

Lifecycle

生命周期

bash
orca orchestration reset [--all] [--tasks] [--messages] [--json]
Why: 
--all
is the default if no flags provided. 
--tasks
clears tasks, dispatch contexts, decision gates, and coordinator runs but preserves messages.
bash
orca orchestration reset [--all] [--tasks] [--messages] [--json]
说明：如果未指定任何标志，
--all
为默认选项。
--tasks
会清除任务、调度上下文、决策门和协调器运行记录，但保留消息。

Terminal Commands for Coordinators

协调器专用终端命令

Coordinators need these terminal commands to spawn agents, monitor progress, and read output. Full terminal documentation lives in the 
orca-cli
skill — this is the subset required for orchestration workflows.
bash
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 read [--terminal <handle>] [--json]
orca terminal send [--terminal <handle>] --text <text> [--enter] [--json]
orca terminal wait [--terminal <handle>] --for <exit|tui-idle> [--timeout-ms <n>] [--json]
orca terminal show --terminal <handle> [--json]
orca terminal stop [--terminal <handle>] [--json]
orca terminal close [--terminal <handle>] [--json]
Why: 
--terminal
is optional for most commands. When omitted, Orca auto-resolves to the active terminal in the current worktree.
Why: 
--command "claude"
launches Claude Code in the new terminal. After creating a 
--command
terminal, use 
terminal wait --for tui-idle
to wait for the agent to boot before dispatching.
Why: 
--for tui-idle
detects the working→idle OSC title transition for recognized agent CLIs (Claude Code, Gemini, Codex, etc.). Always pass 
--timeout-ms
— real coding tasks routinely take 15-60 minutes.
Why: 
--direction horizontal
splits left/right (new pane to the right). 
--direction vertical
splits top/bottom (new pane below). Default is horizontal.
Why: terminal handles are runtime-scoped. If Orca restarts, handles go stale. Re-acquire with 
terminal list
.
Why: the 120-line terminal output buffer (
terminal read
) is for status monitoring, not result extraction. Prefer structured 
worker_done
payloads over parsing terminal output.
协调器需要这些终端命令来生成Agent、监控进度和读取输出。完整的终端文档在
orca-cli
技能中——以下是编排工作流所需的子集。
bash
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 read [--terminal <handle>] [--json]
orca terminal send [--terminal <handle>] --text <text> [--enter] [--json]
orca terminal wait [--terminal <handle>] --for <exit|tui-idle> [--timeout-ms <n>] [--json]
orca terminal show --terminal <handle> [--json]
orca terminal stop [--terminal <handle>] [--json]
orca terminal close [--terminal <handle>] [--json]
说明：大多数命令中的
--terminal
是可选的。如果省略，Orca会自动解析为当前工作树中的活跃终端。
说明：
--command "claude"
会在新终端中启动Claude Code。创建
--command
终端后，使用
terminal wait --for tui-idle
等待Agent启动完成后再进行调度。
说明：
--for tui-idle
会检测可识别Agent CLI（Claude Code、Gemini、Codex等）的工作→空闲OSC标题转换。务必传入
--timeout-ms
——实际编码任务通常需要15-60分钟。
说明：
--direction horizontal
会左右拆分（新窗格在右侧）。
--direction vertical
会上下拆分（新窗格在下方）。默认方向为水平。
说明：终端句柄是runtime作用域的。如果Orca重启，句柄会失效。需使用
terminal list
重新获取。
说明：120行的终端输出缓冲区（
terminal read
）用于状态监控，而非结果提取。优先使用结构化的
worker_done
负载，而非解析终端输出。

Agent Guidance

Agent 操作指南

  • When dispatched with a preamble, always run the 
    worker_done
    command when done    . This is the primary feedback mechanism — it keeps the coordinator's context window clean.
  • If blocked or unable to complete a task, send an 
    escalation
    message to the coordinator instead of silently stalling.
  • Use 
    orca orchestration check
    to read incoming messages from the coordinator or other agents. Messages are delivered automatically when you go idle, but you can also poll explicitly.
  • Treat 
    orca orchestration
    commands the same way you treat 
    git
    or 
    npm
    — they are CLI tools available in your shell.
  • The coordinator uses 
    orca orchestration task-list --ready
    as its external memory. Prefer querying orchestration state over tracking it in your context window.
  • For multi-agent coordination, prefer the inter-worktree pattern (each agent in its own worktree) for parallel implementation tasks. Use intra-worktree (split panes, shared files) for complementary tasks where agents don't edit the same files.
  • When acting as coordinator: discover existing agents with 
    terminal list
    , create tasks with 
    task-create
    , dispatch with 
    dispatch --inject
    , and wait for 
    worker_done
    messages via 
    check --wait --types worker_done,escalation --timeout-ms 300000
    .
  • When acting as coordinator: prefer 
    check --wait
    over sleep+poll loops. 
    --wait
    blocks until a message arrives, eliminating wasted time. Always pass 
    --timeout-ms
    as a safety net. If the wait times out with no messages, fall back to 
    terminal wait --for tui-idle
    and then reading terminal output.
  • check --wait
    returns one message at a time. If N workers finish near-simultaneously, call 
    check --wait
    N times in a loop to collect all results. After each return, mark the task complete (which auto-promotes dependents) and dispatch the next wave before looping back to wait.
  • After receiving 
    worker_done
    from a terminal, that terminal is guaranteed idle — skip the 
    terminal wait --for tui-idle
    round-trip and dispatch the next task immediately.
  • Terminal handles are ephemeral and runtime-scoped. If Orca restarts mid-workflow, all handles go stale. Re-acquire them with 
    terminal list
    before continuing.
  • Keep dependency chains to 3-4 steps maximum. Prefer parallel waves of independent tasks over deep sequential chains.
  • Insert decision gates (
    gate-create
    ) between phases for human oversight on risky operations.
  • 当通过前置内容调度任务时，完成后务必运行
    worker_done
    命令    。这是主要的反馈机制——可保持协调器的上下文窗口整洁。
  • 如果遇到阻塞或无法完成任务，请向协调器发送
    escalation
    消息，而非静默停滞。
  • 使用
    orca orchestration check
    读取协调器或其他Agent的 incoming 消息。当你处于空闲状态时，消息会自动投递，但你也可以主动轮询。
  • 将
    orca orchestration
    命令视为与
    git
    或
    npm
    一样的工具——它们是你shell中可用的CLI工具。
  • 协调器使用
    orca orchestration task-list --ready
    作为外部记忆。优先查询编排状态，而非在上下文窗口中跟踪状态。
  • 对于多Agent协调，并行实现任务优先采用跨工作树模式（每个Agent在独立工作树中）。对于互补任务（Agent不会编辑相同文件），采用同工作树模式（拆分窗格，共享文件）。
  • 当作为协调器时：使用
    terminal list
    发现现有Agent，使用
    task-create
    创建任务，使用
    dispatch --inject
    进行调度，并通过
    check --wait --types worker_done,escalation --timeout-ms 300000
    等待
    worker_done
    消息。
  • 当作为协调器时：优先使用
    check --wait
    而非睡眠+轮询循环。
    --wait
    会阻塞直到消息到达，消除时间浪费。务必传入
    --timeout-ms
    作为安全保障。如果等待超时且无消息，fallback到
    terminal wait --for tui-idle
    然后读取终端输出。
  • check --wait
    一次返回一条消息。如果N个Worker几乎同时完成，请循环调用
    check --wait
    N次以收集所有结果。每次返回后，标记任务完成（这会自动升级依赖任务），然后调度下一波任务，再循环等待。
  • 从终端收到
    worker_done
    后，该终端必然处于空闲状态——跳过
    terminal wait --for tui-idle
    往返步骤，立即调度下一个任务。
  • 终端句柄是临时的且属于runtime作用域。如果Orca在工作流中途重启，所有句柄都会失效。继续之前需使用
    terminal list
    重新获取。
  • 保持依赖链最多3-4步。优先采用独立任务的并行波次，而非深度串行链。
  • 在各阶段之间插入决策门（
    gate-create
    ），以便对高风险操作进行人工监督。

Coordinator Worked Example

协调器示例

Dispatch a task to a fresh Claude Code terminal and wait for completion:
bash
undefined
将任务调度到新的Claude Code终端并等待完成：
bash
undefined

1. Create a terminal running Claude Code

1. 创建运行Claude Code的终端

orca terminal create --worktree active --title "worker-1" --command "claude" --json
orca terminal create --worktree active --title "worker-1" --command "claude" --json

→ handle: term_abc123

→ handle: term_abc123

2. Wait for Claude Code to boot (tui-idle fires when the prompt appears)

2. 等待Claude Code启动完成（当提示符出现时触发tui-idle）

orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json
orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json

3. Create and dispatch a task with preamble injection

3. 创建并调度带前置注入的任务

orca orchestration task-create --spec "Fix the login button CSS" --json
orca orchestration task-create --spec "修复登录按钮的CSS" --json

→ id: task_def456

→ id: task_def456

orca orchestration dispatch --task task_def456 --to term_abc123 --inject --json
orca orchestration dispatch --task task_def456 --to term_abc123 --inject --json

4. Block until the worker reports back (no sleep loops needed)

4. 阻塞直到Worker反馈（无需睡眠循环）

orca orchestration check --wait --types worker_done,escalation --timeout-ms 300000 --json
orca orchestration check --wait --types worker_done,escalation --timeout-ms 300000 --json

→ returns immediately when worker sends worker_done

→ 当Worker发送worker_done时立即返回

5. If --wait timed out with no messages, fall back to idle detection

5. 如果--wait超时且无消息，fallback到空闲检测

orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json orca terminal read --terminal term_abc123 --json
undefined
orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json orca terminal read --terminal term_abc123 --json
undefined