OMC - 09 oh-my-claudecode 的多 Agent 编排实战

Pre

OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南

OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计

OMC - 03 从 0 到高效：Oh My ClaudeCode 安装与实践全指南

OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能：从“帮我写点代码”到端到端自动交付

OMC - 05 从单人到多 Agent：Oh-my-claudecode 的插件架构解析

OMC - 06 从“大模型管家”到“十九人专家团队”：oh-my-claudecode 的多 Agent 工程实践

OMC - 07 把「选模型」当成一门工程学：oh-my-claudecode 的三层模型路由实践

OMC - 08 在多 Agent 时代，如何优雅地「分工协作」：oh-my-claudecode 委托分类体系深度解读

在大多数人印象里，“让一个大模型干完所有事”似乎已经足够强大，但当任务变复杂——大型代码库改造、跨模块重构、安全审计、测试补全、多轮修复……单一 Agent 很快就会暴露出上下文碎片、质量不可控、难以追踪等问题。
oh-my-claudecode 给出的答案，是一套完整的 Team Pipeline Orchestration：把多个 AI Worker 组织成一个有阶段、有守门人、有监控、有伸缩的工程化流水线。本文尝试用工程视角拆解这套体系，帮助你在自己的 AI 开发工具链里复用这些思路。

一、问题背景：为什么需要“团队流水线编排”

如果把大模型当作“一个特别能干的开发同事”，一开始也许很顺利：写个功能、补个单元测试、修个 bug，都能搞定。但一旦进入真实生产环境，问题就来了：

• 任务跨度大：从需求澄清、方案设计，到编码、测试、Review、修复，阶段众多且相互影响。
• 上下文易丢失：对话历史有限，阶段切换频繁，关键决策与风险点容易被冲掉。
• 质量缺乏“闸门”：没有明确“通过/不通过”的关卡，容易在一堆“差不多”的结果里失控。
• 并行难以管理：多个 Agent 并行修改同一代码库，冲突、覆盖、风格不统一层出不穷。
• 外部工具混杂：既有原生 Agent，又有各种 CLI 工具（Codex、Gemini 等），接口和生命周期管理复杂。

oh-my-claudecode 的 Team Pipeline Orchestration 针对这些痛点，设计了一套分阶段流水线 + 动态任务路由 + 事件驱动运行时的协同系统，用一套统一的抽象把原生 Agent 和外部 CLI Worker 统筹起来。

二、总体架构：两条运行时、一个调度内核

2.1 双运行时：V1 Watchdog 与 V2 Event-Driven

在运行时层面，系统提供了两条互补路径：

• Runtime V2 — 事件驱动（默认主路径）

  • 通过monitorTeamV2()定期获取团队状态快照，使用快照 diff 推导任务、Worker、消息的增量事件。
  • Worker 通过omc team api ...这样的 CLI API 与 Leader 通信，背后是带原子文件锁的调度队列，避免并发写入损坏。
  • 引入分阶段流水线、任务版本控制的乐观并发、熔断器等机制，在连续监控失败时自动“拉闸”，避免无限错误循环。

• Runtime V1 — 看门狗（兼容与兜底）

  • 采用简单的轮询模型：监控 Worker 写出的done.json文件，判断任务完成情况。
  • 负责死窗格检测、自动任务重新入队、顺序生成下一个任务等基础能力。
  • 仍是/omc-teamsCLI Worker 能力背后的默认实现，在 V2 不可用或不适用时兜底。

运行时选择是自动的：

• 当设置环境变量OMC_RUNTIME_V2或启用相关特性开关时，系统启用 V2。
• /team技能始终映射到 Claude 原生团队编排，对应 V2 的分阶段流水线；/omc-teams则通过omc team ...命令启动 CLI Worker，由内部逻辑自动选择 V1 或 V2。

可以把它理解为：V2 负责“现代化、高并发、强治理”的主干，V1 做“兼容层 + 简单场景兜底”。

2.2 上层抽象：Skill 层与统一接口

在运行时之上，系统通过 Skill 层暴露统一接口：

• TeamCreate / Task / SendMessage等面向 Claude 原生 Agent 的工具调用。
• omc team [N:agent]这样的 CLI 调用，用于 tmux 中的 CLI Worker 进程（claude/codex/gemini）。

最终，对使用者而言就是两个入口：

三、分阶段流水线：从“先干活”到“先规划、后执行、再验证”

3.1 六阶段生命周期与状态推断

团队流水线的核心是一个强约束的分阶段模型，将整个生命周期切成六个阶段：

• initializing：初始化，加载任务、扫描代码基线、建立初始状态。
• planning：规划阶段，梳理需求、分解任务、构建任务图。
• executing：执行阶段，将任务分发给 Worker 并并行推进。
• fixing：修复阶段，针对验证发现的问题生成修复任务并执行。
• completed：完成，所有任务达成预期，验证通过。
• failed：失败，达到重试上限或出现不可恢复错误。

当前所处阶段不是由“人为标记”得出，而是由inferPhase()函数根据聚合任务状态自动推导：当全部任务处于挂起状态时系统认为还在规划，一旦有任务进入执行状态，阶段就切到 executing，以此类推；completed和failed为终态，不会发生进一步转换。

这种“由事实推导阶段”的设计有两个好处：

• 避免了因标记错误导致阶段错乱。
• 便于监控与自动恢复——只要任务状态一致，阶段就可推回去。

3.2 阶段入口、出口与“验证/修复”闭环

每个阶段都有明确的进入/退出标准，由主编排器严格执行，例如：规划阶段必须产出明确的范围、验收标准和任务图，执行阶段必须在所有任务终态后交给验证阶段。

最关键的是验证/修复循环：

• 执行阶段结束后进入team-verify，由专用验证 Agent 检查结果。
• 若发现缺陷，进入team-fix，生成修复任务，再回到执行。
• 这一循环最多重复配置次数（默认 3 次），超过即标记失败，防止无限循环。

在阶段切换时，Leader 会生成阶段交接文档，写入.omc/handoffs/*.md，内容包括：关键决策、被否决的方案、风险点、修改文件列表、剩余工作等。
后续阶段的 Agent 在构建提示时会注入这些交接文档，即便对话历史被截断，也能保持上下文连贯。

3.3 阶段感知的 Agent 路由

一个重要设计是：每个阶段不是调用“万能 Agent”，而是配置一组专门角色 + 模型层级。

路由解析遵循一条固定优先级链：

1. 用户在团队配置中的显式路由。
2. 插件配置提供的tierModels[tier]。
3. 环境派生的默认模型（getDefaultTierModels()）。

解析出的结果在团队创建时计算一次，存入TeamConfig.resolved_routing，在整个生命周期中保持不变，即使中途修改全局配置也不会影响当前团队的模型分配。
这看起来有点“固执”，但它换来的是稳定与可重现：相同的任务和配置不会因为环境的波动而引入隐含变量。

四、任务路由：把正确的活交给正确的 Worker

当流水线进入team-exec阶段，一个新的问题出现了：哪些任务由哪些 Worker 执行？

系统采用了“两层路由”的方式拆解这个问题。

4.1 第一层：角色路由器（意图分类）

角色路由器负责从任务文本里挖掘“意图”，抽象成统一的角色标签：

• 通过一组正则表达式直接识别典型模式，比如修 CI / lint 的任务被识别为build-fix。
• 匹配失败时，退回到关键字计分：统计任务文本中与各角色相关的关键字出现情况，与ROLE_KEYWORDS对照，选出得分最高的角色。

角色标签大致包括：

• implementation：实现功能。
• verification：验证行为和结果。
• review：代码 Review。
• debug：调试、排查错误。
• design：UI/UX 或架构设计。
• docs：文档工作。
• build-fix：构建/CI 修复。
• unknown：无法归类，需要后续补充信息或人工干预。

这一步的价值在于把自由文本压缩成统一的工作语义通道，后续的 Worker 分配可以只针对有限角色做优化。

4.2 第二层：任务路由器（Worker 匹配）

任务路由器负责把“角色”匹配到具体 Worker：

• 每个 Worker（UnifiedTeamMember）挂有一组能力标签（WorkerCapability），如code-edit、code-review、security-review、architecture、testing等。
• scoreWorkerFitness()函数基于任务意图与 Worker 能力的重叠度打分（0~1）。
• routeTasks()返回一个带置信度的排序列表TaskRoutingDecision，用于决策分配。

对于 V2 运行时，还有一层分配策略：启动时对一批任务做整体分配：

• 如果所有 Worker 角色相同，采用简单的“最低负载优先”。
• 如果 Worker 角色多样，则综合“角色匹配度 + 当前负载”做决策，平衡工作量与专业度。

这一套下来，系统实现了一个软约束 + 评分驱动的任务分配机制，既不会僵化到只能走配置，又能在复杂团队结构下自动漂移到相对合理的平衡点。

五、调度与通信：基于文件的消息队列与多通道传输

5.1 调度队列：文件系统上的消息代理

在 V2 运行时，所有 Worker 通信都经由一个基于文件的调度队列完成，可以把它看作一个轻量级消息代理：

支持三种调度类型：

• inbox：Leader 到具体 Worker 的单播任务指令。
• mailbox：Worker 之间的直接消息，比如任务交接。
• nudge：Leader 对疑似停滞 Worker 的心跳检查。

每条调度请求会经历pending → notified → delivered → failed四个状态，并通过带超时时间的文件锁保证并发安全，默认锁超时 15 秒，可配置范围 1–120 秒。
队列还实现了去重逻辑：等效的挂起调度在入队前会被合并，避免“放大噪音”。

5.2 MCP 通信层：抽象传输通道

调度队列更偏向“队列管理”，真正把消息送到 Worker 手中的，是上方的 MCP 通信层。

它提供四种传输机制：

• hook：基于 hook 的直接调用，一般用于集成自定义服务。
• prompt_stdin：向进程的 stdin 写入指令。
• tmux_send_keys：通过 tmux 注入命令。
• mailbox：基于文件的 Worker 间消息。

transport_preference字段决定优先的传输方式，而系统默认采用hook_preferred_with_fallback策略：优先尝试 hook，如失败则回退到tmux_send_keys或prompt_stdin。

5.3 混合团队的消息路由

在一个同时包含 Claude 原生 Agent 和 CLI Worker 的团队中，消息后端并不统一。为此系统引入了消息路由器：

• 对原生 Agent：通过SendMessage工具指令传输。
• 对 CLI Worker：写入 inbox JSONL 文件，由工作进程轮询读取。
• broadcastToTeam()会根据后端类型将收件人分组，分别通过不同传输路径广播。

这层抽象屏蔽了底层差异，让上层编排只需要关心“发给谁”和“发什么”，而无需关心“怎么发”。

六、治理与生命周期控制：把“能做什么”写死在清单里

对于一个能自动生成子团队、扩容、多轮修复的系统，如果没有治理，迟早会演变成“AI 风暴”。oh-my-claudecode 在这方面下了不少功夫。

6.1 五个治理开关

治理层通过一组治理标志来约束团队行为：

这些标志可以在团队清单或TeamCreate参数中覆盖，但一旦创建，治理配置会被标准化并不可变地写入清单，在整个生命周期内不再变化。
这让治理变成“合同”，而不是“建议”。

6.2 Ralph 持久化循环：为失败预留弹性

系统还支持一种名为linked_ralph的生命周期配置，可以把团队流水线挂在 Ralph 的持久化循环下：

• 每次失败时，由架构师角色协助判断是否重试、是否调整任务或范围。
• 直到达到“真正的完成”或确认无法推进为止。

激活方式很自然：在调用/team技能时加上ralph修饰符即可，把“流水线 + 持久化循环 + 架构师监督”组合起来。

七、动态弹性伸缩：会话级自动扩缩容

7.1 scaleUp：在线加人

弹性伸缩子系统允许在会话过程中增加或减少 Worker 数量，而不需要停掉整个团队。

scaleUp()的过程大致如下：

1. 获取基于文件的伸缩锁，防止多个伸缩操作互相踩踏。
2. 读取当前团队配置，校验 Worker 数量上限（最多 20 个）。
3. 创建新的 tmux 窗格，启动新 Worker 进程。
4. 使用 inbox 指令初始化 Worker，注入必要的上下文。
5. 按照已有的路由快照为 Worker 分配模型与 Agent 类型，保持风格和能力一致。
6. 持久化更新后的团队配置。

7.2 scaleDown：平滑缩容

scaleDown()负责从团队中安全移除 Worker：

1. 将待移除 Worker 标记为draining状态，不再接收新任务。
2. 等待其完成当前任务，或在配置超时（默认 30 秒）后强制终止。
3. 关闭对应 tmux 窗格，更新配置并释放资源。

可以指定具体 Worker 名称，也可以只给一个数量，让系统自动挑选最合适的空闲 Worker 移除。

伸缩能力以环境变量开关控制：必须设置OMC_TEAM_SCALING_ENABLED=true，否则scaleUp()和scaleDown()会直接返回错误；伸缩锁的超时时间默认 10 秒，可通过监控器配置调整。

八、监控与事件：让团队状态“看得见、可追溯”

8.1 事件系统与快照 diff

在 V2 中，监控器通过周期性快照 + diff 推导出团队事件：

• diffSnapshots()函数对比前后两次快照，在任务状态、Worker 存活、Worker 状态变更三个维度做 O(N) 检测。
• 检测出的变化经由事件总线写入 JSONL 日志，采用原子写确保日志不被竞争写入破坏。

事件类型涵盖整个生命周期，比如task_completed、task_failed、worker_idle、worker_stopped、message_received、shutdown_ack、approval_decision、team_leader_nudge等。
这些信息可以直接拿来做外部监控、Dashboard、报警等系统集成。

8.2 熔断器：给监控也上保险丝

监控循环本身也有出错的可能，比如文件系统异常、磁盘空间不足、极端 IO 错误等。为此系统在monitorTeamV2()外又包了一层熔断器：

• 如果连续三次监控失败，熔断器触发，写出watchdog-failed.json标记。
• 后续循环不再继续，避免形成“监控失败 → 重试 → 再失败”的死循环，占满资源。
• 同时保留足够状态以便人工恢复或上层逻辑接管。

8.3 Worker 存活与自我隔离

Worker 的存活状态通过心跳文件追踪，其中记录了：进程 PID、上次轮询时间、当前任务、连续错误次数、运行状态（ready、polling、executing、shutdown、quarantined）。

当连续错误数超过maxConsecutiveErrors（默认 3）时，Worker 会进入隔离状态：不再接收新任务，同时监控器会把其未完成任务重新排队给健康 Worker。
这相当于在 Worker 层面实现了“自动熔断 + 自动降级”。

九、并行工作区与 Git Worktree：避免互相踩脚

多个 Worker 并行修改同一仓库，是团队协作中最容易踩坑的地方。oh-my-claudecode 的解决方案，是让每个 Worker 拥有一块隔离的 git worktree。

9.1 worktree 模式：物理隔离

当workspace_mode=worktree时，系统会为每个 Worker 创建独立的 worktree：

• 每个 worktree 对应一个专用分支和工作目录，仅供该 Worker 使用。
• Worktree 管理模块负责创建、列出、清理全部同名团队的 worktree，避免遗留。

这样做的好处非常直接：并行写入冲突从“文件系统级别”降到“合并阶段”，大幅减少开发中的随机冲突。

9.2 合并协调器：安全合并回主线

当所有 Worker 完成工作后，合并协调器负责把各自分支合并回基础分支：

• 使用--no-ff策略合并，保留完整的提交历史，让每个 Worker 的工作块可追踪。
• 合并前先检查是否存在冲突，如有冲突则在结果中报告，并中止合并，避免把主分支弄脏。
• 即便合并失败，也保证仓库仍处于干净状态，可重复尝试或人工处理。

这种模式很适合需要大规模自动修改代码的场景，比如批量插入日志、统一风格改造、大规模重构等。

十、实践建议：如何在自己的系统里借鉴这套设计

如果你正在搭一套自己的 AI 开发工具或多 Agent 编排系统，可以参考下面几个关键设计点，把 oh-my-claudecode 的经验落到自己的架构里。

1. 先划阶段，再谈智能
   不要一上来就考虑模型怎么调用，先按工程秩序划分阶段：需求澄清、方案设计、执行、验证、修复，每个阶段明确输入输出，再决定需要哪些 Agent。

2. 给每个阶段配专用 Agent，而不是“万能助手”
   用角色来建模能力，比如planner、analyst、executor、verifier、debugger等，并且为不同阶段选择不同的模型层级：规划和评审用高阶模型，执行用中阶模型，批量操作可以用低阶模型。解析出的路由在一次团队任务中保持不变，防止结果飘忽。

3. 任务路由要先抽象“角色”，再分配 Worker
   对输入任务先做意图分类（角色路由），再基于 Worker 能力打分（任务路由）。这样可以把“自然语言任务”转换成有限语义空间，使整个系统更容易调优和分析。

4. 不要怕“重”，要有严格的验证/修复闭环
   在执行后强制进入验证阶段，发现问题就生成修复任务，再回到执行，整个闭环最多重试若干次。多走几步流程，换来的是可控的结果质量和可解释的失败原因。

5. 治理配置写死在清单里，而不是在代码里到处 if
   把关键行为限制（是否允许嵌套团队、是否需要计划审批、是否清理前强制 Worker 下线）做成显式的治理标志，在团队创建时定稿，后续生命周期内保持不变。这比在各个模块 scattered 的开关要可维护得多。

6. 伸缩能力与工作区隔离，应该从一开始就设计
   即便一开始 Worker 只有两个，也尽量把伸缩逻辑和多工作区模型抽象出来。后续要扩展到更多 Worker、更多任务类型时，可以无缝升级，而不是推倒重来。

7. 监控与事件是第一公民，而不是“上线后再补”
   在设计之初就确定监控的快照结构、事件类型、熔断策略。项目早期哪怕只记录到本地 JSONL，也比没有要好得多，未来接入监控平台时就有天然的数据基础。

十一、结束语：从“一个模型”到“一个团队”

单体 Agent 足够应付很多个人效率场景，但要把大模型真正嵌入团队开发流程，就必须引入工程视角：阶段划分、角色分工、任务路由、质量关卡、伸缩、监控、治理，这些过去在微服务和 CI/CD 领域反复验证过的理念，在多 Agent 协同里同样适用。

oh-my-claudecode 的 Team Pipeline Orchestration 展示了一条清晰路线：用分阶段流水线保证秩序，用事件驱动运行时和调度队列承载并发，用角色化 Agent 和任务路由保证“人岗匹配”，用治理、伸缩和监控把系统从“能跑”推向“敢用”。

如果你正在思考“怎么把多个模型组织起来解决真实工程问题”，这套设计值得细读，也值得在自己的系统中做一次小规模试验，从一个简单的两阶段流水线开始，然后逐步引入验证、修复、扩缩容和工作区隔离，亲手搭建属于自己的 AI 团队流水线。