编排（Orchestration）

用 Run、task、受监督的 worker、消息和决策门（decision gate）来协调 agent。

Orchestration 是 DevAgent 的结构化多 agent 层：一个 Run（命名空间 + coordinator 收件箱）、Task、Dispatch、受监督的 worker、消息以及决策门。

当你需要归属权、完成度跟踪或一个 DAG 时使用它。对于一次性的 prompt，使用 devcore terminal send。对于无监督的完全归属权交接，使用 orca-cli skill 中的 worktree/terminal 命令。

Experimental

在使用这些命令前，请在 设置 → 实验 下启用 orchestration。该 CLI 会与正在运行的 DevAgent 运行时通信，因此应先确保 devcore status --json 成功。

Legacy commands retired

devcore orchestration run 和 run-stop（以及 coordinator-start / coordinator-stop）不产生任何效果。它们会返回指向 devcore skills get orchestration --full 的恢复提示文本。请使用下面的 Run + worker-start 流程。

核心模型

• Run — 持久化的命名空间和主收件箱。从不调度或放置 worker。
• Task — 一个工作项，包含 spec、依赖关系和状态：pending、ready、dispatched、completed、failed 或 blocked。
• Dispatch — 某个 task 在某个终端上的一次尝试；对 worker_done / heartbeat 拥有生命周期权威。
• Message — 收件箱邮件（status、dispatch、worker_done、escalation、question、heartbeat……）。
• Decision gate — 由 coordinator 所有的一个问题，会阻塞某个 task 直到它被解决。

完成权威来自活动的 dispatch 上下文。worker 的完成和 heartbeat 消息应同时包含 taskId 和 dispatchId。

终端中打印的 task ID（例如 task_...）是可点击的链接。点击其中一个会向 DevAgent 运行时请求该 task 当前的 dispatch，并聚焦到分配的终端，即使该 task 位于远程或 SSH 运行时中也是如此。

推荐的受监督循环

devcore orchestration run-create --objective "拆分 checkout QA and summarize blockers" --json
devcore orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
devcore orchestration worker-start --task <taskId> --worktree current --agent codex --json
# 或者新建 worktree：
devcore orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# 可选的每个 worker 的 model / effort（仅 Claude、Codex、Cursor；不能与 --terminal 一起使用）：
devcore orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json

--model 接受 Claude、Codex 和 Cursor 的不透明 provider model ID。--effort 需要配合 --model，且仅在该 agent/model 支持相应级别时才生效。这两个 flag 都不能与 --terminal（复用已有 窗格）组合使用。这些覆盖仅对该次启动生效，并会在启动回执中的 launch.requested / launch.effective 下显示。联邦式启动需要一个宣告支持启动偏好的 worker host。

等待完成（处理完某个 Delivery 中的每条消息后，再 ack）：

devcore orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
devcore orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

worker 完成（从 worker 窗格 发出；包含注入的 ID）：

devcore orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx" \
  --json

worker_done 需要 --outcome succeeded|failed。

检查 / 恢复：

devcore orchestration worker-show --dispatch <dispatchId> --json
devcore orchestration worker-read --dispatch <dispatchId> --limit 50 --json
devcore orchestration worker-stop --dispatch <dispatchId> --json
# 在一个已被接受的 worker_done 之后：复用同一个终端进行后续 Dispatch，或者释放它
# （归档可检查的输出，然后仅关闭那个由 coordinator 所有的 agent 终端）：
devcore orchestration worker-release --dispatch <dispatchId> --json
# 当用户要求保留时，让一个已结束的 worker 保持存活以便调试：
devcore orchestration worker-retain --dispatch <dispatchId> --json
# 重试的放置是显式的 —— --retry-of 不会继承 --on/worktree：
devcore orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json

不要仅仅为了重新读取输出而让已完成的 worker 终端一直开着——在 worker-release 之后使用 worker-read。当 release 返回 release_pending 或 release_unknown 时，不要用宽泛的 terminal close 来替代；请遵循回执中的恢复操作。

联邦式 worker（可选）

devcore orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
devcore orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json

后续命令按 Dispatch ID 路由；不要重复 --on。

底层 dispatch（自定义拓扑）

devcore worktree create --name billing-audit --agent codex --json
devcore terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
devcore orchestration dispatch --task <taskId> --to <workerHandle> --inject --json

消息传递说明

• 默认的 check 是所绑定 Run 中最早的未 ack Delivery（FIFO）。重放直到 --ack。
• --peek / --all 不会消费邮件。
• 组地址：@all、@idle、@claude、@codex、@opencode、@gemini、@droid、@grok、@cursor、@worktree:<id> —— 绝不用于 worker_done / heartbeat。
• 在 PowerShell 中给组地址加引号：--to "@all"。

devcore orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
devcore orchestration send --to @idle --subject "Anyone free?" --json
devcore orchestration send --to @codex --subject "Codex agents only" --json

当有一个 wait 处于活动状态时，CLI 每 15 秒会向 stderr 输出一小行 JSON heartbeat。stdout 仍然保留最终的命令结果。

Worker 约定

被 dispatch 的 worker 会收到一段前言，告诉它们如何与 coordinator 通信：

• 即使失败也要恰好发送一次 worker_done，并带上 --outcome。
• 包含一段简短的 --body 摘要：做了什么、发现了什么、还剩下什么。
• 同时包含 task 和 dispatch ID，这样过期的重试就无法完成错误的 dispatch。
• 在长时间的活动工作期间发送 heartbeat 消息。
• 对于阻塞式的问题，使用 devcore orchestration ask 而非本地的 TUI 提示。

devcore orchestration ask \
  --to <coordinatorHandle> \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

使用 --json 时，ask 会打印单个 JSON 对象，因此 worker 可以将其管道输入到 jq -r .answer。

决策门

对于 worker 向 coordinator 提出的问题，使用 ask。当 coordinator 已创建 task DAG，并希望阻塞某个 task 直到记录下一个决策时，使用显式的 gate：

devcore orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]' \
  --json

devcore orchestration gate-resolve --id <gateId> --resolution "yes" --json

恢复

devcore orchestration dispatch-show --task <taskId> --json
devcore orchestration dispatch-show --task <taskId> --preamble --json
devcore orchestration task-list --json
devcore orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json

只有在你有意放弃 orchestration 状态时才重置：

devcore orchestration reset --tasks --json
devcore orchestration reset --messages --json
devcore orchestration reset --all --json

reset 会影响运行时全局的 orchestration 状态。除非那正是预期的清理操作，否则不要在另一个 coordinator 处于活动状态时运行它。

选择正确的命令

当你要向一个正在观察的 agent 发送一个轻量 prompt 时，使用 devcore terminal send。

当一个 worker 必须报告 worker_done、通过 coordinator 提问，并被 task ID 跟踪时，使用 devcore orchestration worker-start（或 dispatch --inject）。

当你想要一个持久的 Run 命名空间和受监督的多 agent 循环时，使用 devcore orchestration run-create + task + worker——而不是已退役的 orchestration run 命令。

完整指南

命令 flag 会随应用演进。安装后，agent 应运行：

devcore skills get orchestration --full