多智能体如何并行干活还不打架:oh-my-agent编排机制与故障恢复实战
多智能体如何并行干活还不打架:oh-my-agent编排机制与故障恢复实战
在 AI 编程时代,让多个 Agent 同时开工已经不是难事,难的是它们并行干活不打架、失败了还能自动恢复。oh-my-agent 是一个多智能体编排与机械校验框架(Multi-Agent Harness):它负责把复杂任务拆成可验证的子任务,调度多个专业 Agent 并行执行,用独立校验和 QA 交叉评审把关,并在 Agent 崩溃或校验失败时按预算自动重试与断点续跑。本文将讲清楚它的编排机制与故障恢复实战逻辑。
一、为什么多智能体一上并行就容易"打架"
先看看裸奔的多智能体方案常见翻车现场:
- 抢文件:两个 Agent 同时改同一批文件,diff 互相覆盖;
- 口头汇报:Agent 声称"测试全部通过",但实际没跑过——同一个会话里的任何声音都无法反驳它;
- 一挂就全挂:一个子 Agent 崩溃,整条流水线状态丢失,无法从断点恢复;
- 无限重试:失败的 Agent 反复重启,成本失控。
oh-my-agent 的思路是:不要相信 Agent 的叙述,只相信它留下的产物(artifacts)和可执行的检查结果。这正是它的核心口号——"Agents narrate success. oh-my-agent checks the artifacts."
二、oh-my-agent 的编排机制:五阶段流水线
oh-my-agent 的自动化编排定义在 skills/oma-orchestration/SKILL.md 中,整体是一条五阶段流水线:
| 阶段 | 动作 | 解决什么问题 |
|---|---|---|
| PREPARE | 生成会话 ID、初始化任务看板与记忆文件 | 状态持久化,崩溃后可恢复 |
| ACT | 按优先级分层派生 Agent,受并发上限约束 | 并行不打架 |
| VERIFY | 机械自检 + oma verify + QA 交叉评审 |
结果可信 |
| RECOVER | 对失败的 Agent 按预算重试 | 故障恢复 |
| FINALIZE | 收集已验证的结论、生成汇总 | 交付留痕 |
1. 任务拆解:先有冻结的计划,再派活
编排的第一步是把需求拆解成带优先级、依赖关系和验收标准的任务图,并写入任务看板(task board)。计划一旦被派发就被冻结——任务 ID、提示词、依赖和重试上限都不可再改,想改范围必须开新会话。这条规则看似死板,却是防止"计划漂移"导致各 Agent 互相踩脚的关键,详见 com.firstfluke.oma/workflows/orchestrate.md。
怎么判断该拆成几块?项目给了一个很实用的经验表:按行为边界拆,让测试和错误处理跟着它验证的行为走。参考 skills/_shared/core/difficulty-guide.md。
2. 按优先级分层派活,并发上限默认 3
派活不是一股脑全部放出,而是从 tier 1 到 tier 2 逐层推进,同层内的独立任务才允许并行。默认配置 MAX_PARALLEL = 3,即最多 3 个子 Agent 同时运行;配合 30 秒一次的轮询间隔检查进度文件。
派发路径分两级(这是"不依赖单一运行时"的关键设计):
- 原生派发:如果当前运行时(Claude Code、Codex、OpenCode 等)暴露了原生子 Agent 工具,优先使用——例如 Claude Code 在一条消息里发起多个 Agent 调用即天然并行,结果同步返回;
- 兜底派发:跨运行时或无原生路径时,回落到统一命令
oma agent spawn <agent-type> <prompt-file> <session-id> --task-id <task.id> -w <workspace>,由 cli/commands/agent/ 下的调度器拉起子进程。
也就是说,同一套编排逻辑可以跑在十几种 Agent 运行时上,而调度细节对上层完全透明。
3. 文件化状态:每个 Agent 只写自己的文件
"不打架"的第二个保障是文件所有权隔离。所有协调状态都是纯 Markdown 文件,存放在 .agents/state/memories/ 下,命名规则写死在 skills/_shared/runtime/memory-protocol.md:
| 文件 | 归属 | 其他 Agent |
|---|---|---|
orchestrator-session-{sessionId}.md |
编排器 | 只读 |
task-board-{sessionId}.md |
编排器 | 只读 |
progress-{agentId}-{taskId}-{runId}-{sessionId}.md |
该次运行 | 编排器只读 |
result-{agentId}-{taskId}-{runId}-{sessionId}.md |
该次运行 | 编排器只读 |
每个 Agent 开工前先读任务板确认自己的任务,每 3-5 轮追加一条进度,结束时写入带 completed / partial / blocked / failed 状态的结果文件。注意:失败时也要写结果文件——这是故障恢复能"接得上"的前提。
三、结果可信:完成之后的三道质量闸门
Agent 干完活不能直接算数,oh-my-agent 为每个完成的任务跑一个迭代式评审环(定义在 skills/oma-orchestration/SKILL.md 的 PHASE 4.5):
第一道:机械自检 — 实现 Agent 先自己跑 lint、typecheck、测试,并做 diff 范围检查(确认只改了计划内文件)。此步不做质量判断,因为研究反复表明 Agent 会系统性高估自己的产出。
第二道:自动化 verify — 对 backend/frontend/mobile/qa/debug/pm 类型执行 oma verify agent <agent-type> --workspace <workspace> --json,退出码 0 才算过;失败则把输出作为修正反馈打回给 Agent。
第三道:QA 交叉评审 — 另起一个独立的 QA Agent 读 diff、跑检查、对照验收标准给出 PASS/FAIL 裁决。FAIL 时问题清单(含文件与行号)直接喂回实现 Agent 修复,重新进入第一道。
评审环有明确的熔断上限:自检修复最多 3 轮、交叉评审驳回最多 2 次、总循环不超过 5 次——超限就停止恢复,保留全部证据,返回 partial 或 failed,绝不硬凑一个"完成"。
四、故障恢复实战:重试预算 + 断点续跑
这是很多编排方案最薄弱、oh-my-agent 做得最细的部分,核心契约在 skills/_shared/runtime/result-contract.md 中。
1. 先分类,再恢复
失败不是无差别重试,先分两类:
- PRODUCT_FAILURE(产品本身没过检查):按剩余产品恢复预算重试;
- WORKFLOW_EVIDENCE_FAILURE(代码其实过了,但结果声明/产物绑定坏了):禁止重放产品工作,只允许一次元数据级修复,修不好就以
partial收尾并给出精确诊断。
2. 恢复预算:默认 3 次,谁也不能重置
每个逻辑目标共享一份预算(默认 MAX_RECOVERY_ATTEMPTS = 3,含首次尝试)。关键防作弊设计:
- 预算按计划血缘(lineage_id)+ 目标(goal_id)记账,换新 session ID、换任务 ID 都不会重置计数;
- 首次剩余尝试:带着完整评审历史重新派生(Agent 能看到上一轮为什么被驳回);
- 后续尝试:要么换一种方式重试,要么做 2-3 个假设轮次探索——前提是预算和成本都还够;
- 预算耗尽:保留所有检查记录、评审发现与未完成项,任务状态只能是
partial或failed。
3. oma agent resume:断点续跑
真正断线重连的能力在 cli/commands/agent/resume.ts:
oma agent resume SESSION_ID --dry-run先做干跑,报告哪些任务可复用、哪些就绪、哪些还在跑、哪些被阻塞;- 正式执行时按依赖顺序重试就绪任务,并重新验证证据后才算成功——依赖变了会使下游复用全部失效;
- 会话租约(session lease)防止两个协调器同时恢复同一个会话,本地进程死了也能安全接管。
配合结果文件中的 run 快照(命令、退出码、工作树哈希、产物哈希),resume 能精确区分"真做完了"和"只是说过做完了",从机制上杜绝了用旧证据冒充新结果。
五、实战效果:基准测试中的成绩
项目内置了一组五方案对照基准:同一条"儿童 3D 创作学习平台 MVP"提示词,分别在裸 Claude Code 和四种增强 Harness 下运行,按功能、规格、视觉、工程、效率五个维度打分。结果见 benchmarks/README.md 与 benchmarks/results/report.md:
| 排名 | 方案 | 总分 |
|---|---|---|
| 1 | oma(oh-my-agent) | 80.6 |
| 2 | omc | 74.1 |
| 3 | superpowers | 72.9 |
| 4 | vanilla(裸跑基线) | 70.7 |
| 5 | ecc | 70.2 |
编排与校验机制带来的不是玄学提升,而是"规格符合度 + 工程质量"上的稳定差距——多个 Agent 并行产出仍然彼此自洽,且每项声称都有产物背书。
六、快速上手:三步接入多智能体编排
- 安装(脚本会自动补齐 bun、uv、serena 等依赖):
git clone https://gitcode.com/gh_mirrors/oh/oh-my-agent
bunx oh-my-agent@latest
- 选择技能预设:安装器会列出 All / Backend / Frontend / Fullstack 等预设,Fullstack 预设默认包含 architecture、backend、frontend、qa、orchestration 等 13 个技能;
- 发起编排:对 Agent 说一句"run in parallel"或"自动执行"即可触发 com.firstfluke.oma/workflows/orchestrate.md 编排流程;想手动逐步指挥则使用 skills/oma-coordination/SKILL.md 中的协调技能。
配套脚本都开箱即用:spawn-agent.sh 派生单个 Agent、parallel-run.sh 并行执行、verify.sh 按 Agent 类型跑校验。
写在最后
多智能体并行的本质矛盾是:产出是并行的,责任是单点的。oh-my-agent 给出的答案是——用冻结计划划清边界、用文件所有权隔离状态、用三道闸门替代口头汇报、用带血缘记账的恢复预算替代无限重试。理解了这套"先立契约、再谈协作"的思路,无论是接入 oh-my-agent 还是自研编排系统,都少走很多弯路。


