Orca 多 Agent 编排完全指南：任务 DAG、决策门与 worker

Orca 多 Agent 编排完全指南：任务 DAG、决策门与 worker_done 机制

【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca

Orca 是一款面向并行 Agent 的 AI 开发环境（ADE），支持多 Agent 编排：你可以用一套完整的协调机制管理多个编码 Agent——通过任务 DAG定义依赖关系并行调度工作，用决策门（Decision Gate）在关键节点暂停等待审批，并依靠worker_done机制获得可靠的完成信号。本指南带你从零理解这套编排体系的三大核心机制，并给出可直接上手的操作路径。

一、为什么需要多 Agent 编排？

单个 Agent 一次只能做一件事。当你想同时"修复登录页 CSS、重构 API 层、补充单元测试"时，就需要多个 Agent 并行工作。但并行带来的问题是：

谁先做、谁后做？有依赖关系的任务不能同时开工
谁来判断该不该继续？涉及架构选择时需要人做决定
怎么知道做完了？Agent 说"快好了"不等于真的完成了

Orca 的编排层（orchestration）正是为这三个问题设计的，其完整说明见 skills/orchestration/SKILL.md。

二、三大核心概念：Run、Task 与 Dispatch

理解编排之前，先认识三个角色（对应源码中的 Run / Task / Dispatch 模型）：

概念	类比	职责
Run	项目	命名空间 + 协调者收件箱，不亲自调度任何 Agent
Task	任务卡	一件具体的工作，可声明依赖（即 DAG 的边）
Dispatch	派工单	把某个 Task 指派给某个终端里的 Agent，是"生命周期权威"所在

一句话记住所有权规则：新的消息和任务只属于一个明确绑定的 Run；worker_done和心跳从 worker 自己的终端发出，Orca 负责路由回它所属的 Dispatch 和 Run。

三、任务 DAG：用依赖关系驱动并行执行

创建任务时可以用--deps声明前置依赖，所有任务就构成一张有向无环图（DAG）：

orca orchestration run-create --objective "重构登录模块" --json orca orchestration task-create --spec "修复登录按钮 CSS" --json orca orchestration task-create --spec "补充单元测试" --deps '["<task_a_id>"]' --json

任务状态流转共六种：pending → ready → dispatched → completed，另有failed和blocked。推荐的做法是：

先创建 Run 和所有独立任务，再逐个启动 worker；
用task-list --ready查看当前可执行任务，把无依赖的任务组成"并行波次"一次全部worker-start；
官方建议依赖链不要超过3~4 层，否则调试成本会急剧上升。

Orca 会持续判断 DAG 的收敛状态。源码 coordinator-dag-convergence.ts 中的逻辑很直白：

全部任务completed/failed→ 收敛完成
没有任何活跃任务、却仍有blocked任务 →卡死（Stuck），日志会提示"Resolve decision gates to continue"

这正是决策门与 DAG 的联动点。

四、决策门：关键节点的人工审批点

决策门（Decision Gate）是 DAG 中的"审批关卡"：当某个任务需要人来拍板（例如"选方案 A 还是方案 B"），协调者可以为它创建一个门，该任务随即被置为blocked，直到有人给出决议。

orca orchestration gate-create --task <task_id> --question "API 用 REST 还是 gRPC？" --options '["REST","gRPC"]' --json orca orchestration gate-resolve --id <gate_id> --resolution "REST" --json

两个设计细节值得新手注意（源码见 coordinator-decision-gates.ts）：

协调者绝不会自动决议门——门就是给人用的审批点，自动通过等于失去意义；
门与任务状态互为约束：只要存在 pending 的门，任务就必须保持blocked，如果状态不一致会被自动"再封锁"修复。

注意区分两个容易混淆的命令：

ask/reply：worker 问、协调者答（Agent 之间的阻塞式问答）
gate-create/gate-resolve：协调者管的 DAG 级决策，通常由人最终拍板

门的持久化存储在 decision-gate-store.ts 中，即使应用重启，未决议的门依然有效。

五、worker_done 机制：一次、可信的完成信号

并行编排最怕"假完成"。Orca 用worker_done把它变成一条严格契约：

只发一次：worker 完成任务后，从自己的终端发出唯一一条worker_done；
必须显式声明结果：--outcome succeeded或--outcome failed，失败绝不能只写在文字描述里；
自动结算：携带正确taskId + dispatchId的worker_done会自动把任务和 Dispatch 标记为完成，无需再手动task-update；
发完即停：worker 发送后必须结束当前回合、停在提示符处，不得自行开新活或关终端。

# worker 端（Orca 注入的前言中已带好正确参数） orca orchestration send --type worker_done \ --subject "CSS 已修复" --body "改了什么 / 发现了什么 / 还剩什么" \ --task-id <task_id> --dispatch-id <dispatch_id> \ --outcome succeeded --files-modified "src/login.css" --json

协调者这边则用滚动等待代替轮询：

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

新手常见误区：

等待超时 ≠ worker 失败。长任务动辄 15~60 分钟，超时应视为"检查点"，继续下一轮等待；
心跳（heartbeat）只证明存活，不证明完成；
每个被接受的worker_done处理后，要么复用该终端跑下一个任务（worker-start --terminal <handle>），要么用worker-release释放，不要让完成的 worker 一直挂着。

六、快速上手：一个最小编排循环

把上面的机制串起来，一个完整的最小循环是（完整命令规范见 src/cli/specs/orchestration.ts）：

准备：orca status --json确认运行中；在设置 → Experimental 中开启编排功能；
建 Run：run-create --objective "..."；
建任务：对每个独立工作task-create，用--deps声明依赖；
启动 worker：对每个独立任务worker-start --task <id> --worktree current --agent codex --json；
滚动等待：check --wait --types worker_done,escalation,question，逐条处理消息后--ack确认；
收口：处理每个worker_done→worker-release释放终端 → 等待下一批；
需要人拍板时：gate-create开闸、人审后gate-resolve放行，被blocked的下游任务随之解冻。

进阶能力（按需了解）：

嵌套深度：默认 worker 不能再派 worker，Settings → Orchestration → Nested worker depth可设为 2；
跨机器联邦：worker-start --on <环境名>可把 worker 放到另一台已连接的 Orca 上，Run 与任务仍在原机权威，后续按 Dispatch ID 路由；
旧版兼容：升级后旧的编排状态会被"收养"进普通 Run，消息上的[LEGACY ...]标签是权威依据，照着提示操作即可。

七、总结：三个机制各管一件事

机制	解决的问题	一句话记忆
任务 DAG	谁先做、谁并行	`--deps`连边，`task-list --ready`取波次
决策门	该不该继续	开了门任务就`blocked`，只有人能解锁
worker_done	是否真完成	一次、显式 outcome、发完即停