Orca 智能体间编排

当任务需要通过Orca的编排系统协调多个编码Agent时，请使用本技能。如需基础终端和工作树管理，请改用

orca-cli

技能。

适用场景

需要在Agent终端间发送消息
需要将需求分解为带有依赖关系的并行子任务
需要向Worker Agent调度任务并获取结构化反馈
需要作为协调器管理多Agent工作流
需要为人工介入检查点创建决策门

前提条件

Orca必须处于运行状态（执行
```
orca status --json
```
应返回
```
runtime: true
```
）。
```
orca
```
CLI必须已添加至PATH（可通过Settings > Browser > Enable Orca CLI安装）。
必须在Settings > Experimental中启用编排实验性功能。
所有
```
orca orchestration
```
命令都是对运行中Orca runtime的RPC调用——需要活跃的Orca会话。

命令集

消息传递

基于持久化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

，独立跟踪已读状态。

任务管理

基于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解析步骤。

任务调度

调度会将就绪任务分配给终端。可选择将任务规格+前置内容注入终端，让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

，以避免无限重试循环。

决策门

人工介入的决策点，会阻塞任务直到问题解决。

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

。

协调器

启动自动化协调器循环，调度就绪任务、处理

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

。

生命周期

bash

orca orchestration reset [--all] [--tasks] [--messages] [--json]

说明：如果未指定任何标志，

--all

为默认选项。

--tasks

会清除任务、调度上下文、决策门和协调器运行记录，但保留消息。

协调器专用终端命令

协调器需要这些终端命令来生成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 操作指南

当通过前置内容调度任务时，完成后务必运行
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
```
），以便对高风险操作进行人工监督。

协调器示例

将任务调度到新的Claude Code终端并等待完成：

bash

# 1. 创建运行Claude Code的终端
orca terminal create --worktree active --title "worker-1" --command "claude" --json
# → handle: term_abc123

# 2. 等待Claude Code启动完成（当提示符出现时触发tui-idle）
orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json

# 3. 创建并调度带前置注入的任务
orca orchestration task-create --spec "修复登录按钮的CSS" --json
# → id: task_def456
orca orchestration dispatch --task task_def456 --to term_abc123 --inject --json

# 4. 阻塞直到Worker反馈（无需睡眠循环）
orca orchestration check --wait --types worker_done,escalation --timeout-ms 300000 --json
# → 当Worker发送worker_done时立即返回

# 5. 如果--wait超时且无消息，fallback到空闲检测
orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json
orca terminal read --terminal term_abc123 --json

orchestration

NPX安装

标签

SKILL.md 内容（中文）

Orca 智能体间编排

适用场景

前提条件

命令集

消息传递

任务管理

任务调度

决策门

协调器

生命周期

协调器专用终端命令

Agent 操作指南

协调器示例