两个 Agent 并行，怎样安全收口

Pi 在一个 worktree 中写实现说明，OMP 在另一个 worktree 中做源码复核。两边都返回“完成”。

这时仍有四个问题：完成消息是否来自被派发的 Pane，改动是否只落在允许路径，两个提交是否可合并，最终选择由谁批准。

并行只解决同时工作，收口仍要串行完成。Orca 的 Orchestration Runtime 提供 Task、Dispatch、Message 和 Decision Gate，Git 保存最后可审查的改动。

Orca 记录五类对象

对象	它保存什么
Task	工作说明、依赖与状态
Dispatch	哪项任务被交给哪个 Pane
Message	worker_done、escalation、heartbeat 等回执
Decision Gate	等待用户或 Coordinator 明确选择
Coordinator Run	一次协调循环的运行状态

类型定义可以在 orchestration/types.ts 中看到。Coordinator 默认最大并发为 4，会处理 worker_done、escalation、decision_gate 与 heartbeat。查看 Coordinator 构造与并发设置。

固定审计版本中，这套功能仍需在 Settings 的 Experimental 区域启用。查看 Orchestration guide。

还有一项重要限制：Coordinator 不会把一段复杂 Prompt 自动拆成任务，运行前必须预先创建 Task。查看尚未实现的自动分解。

这里由人拆任务，Orca 负责保存、派发、等待和 Gate。

设计一组可合并任务

把两项工作拆成两条互不重叠的写路径：

portfolio/
├── pi/
│   └── implementation-note.md
├── omp/
│   └── review-checklist.md
├── decisions/
│   └── selection.md
└── evidence/
    ├── task-list.json
    ├── dispatches.json
    └── verification.txt

Task A 交给 Pi，只写 portfolio/pi/；Task B 交给 OMP，只写 portfolio/omp/。两项都要返回 commit SHA、修改文件和验证命令。

“研究员”和“审查员”只是角色名，不能形成隔离。明确 worktree、允许路径、输出格式与验收条件，才让任务具备可并行性。

Task 与 Dispatch 为什么要分开

Task 描述需要完成的工作，Dispatch 记录“这一次交给了谁”。同一 Task 可以因为超时或升级产生新的 Dispatch，历史记录仍保留。

派发给 Worker 时，生命周期 preamble 会带上 task id、dispatch id、Coordinator 与回执方式。收到 worker_done 后，要核对：

taskId
dispatchId
source pane
commit SHA
modified paths
verification

只收到一句自然语言“做完了”，无法证明回执属于当前 dispatch。

等待也应有上限。Orca guide 建议用有界 check --wait，超时只表示本次等待结束，不会把 Worker 自动判为失败。查看有界等待约定。

在 Orca 中派发两项真实任务

先在 Settings 的 Experimental 区域打开 Orchestration，并确认 CLI 连接到正在运行的 Orca：

orca status --json
orca terminal list --json

为两份互不重叠的文件各建一个 Task。每条命令都会返回 task id，下面分别记作 <PI_TASK> 与 <OMP_TASK>：

orca orchestration task-create \
  --spec "只写 portfolio/pi/implementation-note.md；提交改动，并在完成回执中给出 commit SHA、修改路径和验证命令。" \
  --json

orca orchestration task-create \
  --spec "只写 portfolio/omp/review-checklist.md；提交改动，并在完成回执中给出 commit SHA、修改路径和验证命令。" \
  --json

从 Orca 管理的仓库终端创建两个 worktree。读取返回 JSON 中的 startupTerminal.handle，分别记作 <PI_HANDLE> 与 <OMP_HANDLE>：

orca worktree create --name pi-note --agent pi --json
orca worktree create --name omp-review --agent omp --json

orca terminal wait --terminal <PI_HANDLE> --for tui-idle --timeout-ms 60000 --json
orca terminal wait --terminal <OMP_HANDLE> --for tui-idle --timeout-ms 60000 --json

终端 ready 后再派发。--inject 会把 task id、dispatch id、Coordinator 地址和 worker_done 回执要求一起送进目标 Agent：

orca orchestration dispatch --task <PI_TASK> --to <PI_HANDLE> --inject --json
orca orchestration dispatch --task <OMP_TASK> --to <OMP_HANDLE> --inject --json

等待窗口要有明确上限。两个 Worker 可能几乎同时完成，因此最多重复运行两次；超时是一次观察窗口结束，不代表 Worker 失败：

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

收到回执后复核 provenance：

orca orchestration task-list --json
orca orchestration dispatch-show --task <PI_TASK> --json
orca orchestration dispatch-show --task <OMP_TASK> --json

只有 taskId + dispatchId + source pane 都与活动派发一致，回执里的 commit SHA 才进入下一步验收。完整命令语义以 审计 HEAD 的 Orchestration guide 为准。

Decision Gate 处理不可自动化的选择

两个 Worker 都完成后，创建一个依赖 A 与 B 的交付 Task，再放置 Gate：

问题：两份成果是否都满足交付标准？

选项：
1. 两份都收录
2. 只收录通过验收者
3. 退回修订

Decision Gate 不会自动决策。它暂停推进，等待人记录 resolution。Coordinator 的 Gate 处理同样保留这条约束，查看源码。

如果一份提交没有通过，就创建新修订任务。不要修改旧的 completed 记录来伪装第一次已经成功。

实际命令先创建一个依赖前两项 Task 的交付任务，再为它建立 Gate：

orca orchestration task-create \
  --spec "验收并整合 Pi 与 OMP 两份作品" \
  --deps '["<PI_TASK>","<OMP_TASK>"]' \
  --json

orca orchestration gate-create \
  --task <DELIVERY_TASK> \
  --question "两份成果是否都满足交付标准？" \
  --options '["两份都收录","只收录通过验收者","退回修订"]' \
  --json

orca orchestration gate-resolve \
  --id <GATE_ID> \
  --resolution "两份都收录" \
  --json

最终收口仍然回到 Git

交付 worktree 依次 cherry-pick 两个通过验收的提交，再创建 selection 与 evidence：

git cherry-pick <PI_COMMIT>
git cherry-pick <OMP_COMMIT>
git status --short
git log --oneline --decorate -5
git show --stat --oneline HEAD

最终通过条件：

• 工作树干净；
• 两个来源提交都可追溯；
• 修改路径没有越界；
• Gate resolution 与实际选择一致；
• 验证命令和结果保存在非敏感 evidence 中；
• 环境变量、令牌、完整私密转录与个人绝对路径没有进入提交。

Orca 的通知可以提示用户返回工作台，不能代替 Task、Dispatch、Gate 和 Git 验收。通知实现带 worktree 级去重与前台抑制，查看 notifications 实现。

运行课程最后一个离线实验

第 12 个 Lab 不依赖 Orca。它让 my-pi-agent 依次读、写、测，再由环境 Verifier 决定终态：

cd agent-harness-lab
npm run lab -- 12

预期看到：

{
  "terminal": "completed",
  "turns": 4,
  "toolCalls": 3,
  "finalFile": "version=2\nREADY\n"
}

事件序列中还应同时出现 tool start、tool end、verification 与 run end。它把前八章的控制面收进一条可重复 Trace。

Lab 12 只验证单进程的读、写、测试与终态判定；它不验证 Orca 的并发、Dispatch、Message 或 Decision Gate。Orca 部分要用本章前面的真实 Orca 操作验收。

随后运行总验收：

npm test
npm run labs
npm run validate

这份作品如何证明能力

一个第一次打开仓库的人，应该能在十五分钟内找到：

README.md              最短运行路径
book.yaml              十二章顺序与路由
src/my-pi-agent/       教学内核
labs/                  每章可观察场景
tests/                 正常、失败、审批与恢复用例
research/source-lock.json
                       Pi、OMP、Orca 固定版本
CLAIMS.md              观察与命令的映射

这比简历上的“熟悉 Agent、Memory、多 Agent”多了可检查的含义。读者可以看见工具结果怎样回填、权限何时生效、Context 怎样投影、恢复为什么会停、OMP 何时该 Fork、Orca 怎样隔离并收口。

如果使用 Orca Experimental Orchestration 记录任务，需要保留一句准确说明：

固定审计版本已经实现 Task、Dispatch、Message、Gate 与 Coordinator 运行原语；任务由人预先定义，Coordinator 尚未自动拆解复杂需求，最终整合由人工验收。

课程最终交付是一份可运行、可质疑、可继续修改的 Agent 工程样本。