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:

Group	Resolves 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

→ 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

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

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

→ 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