AI 助手团队协作怎么落地：OMX 用 5 个阶段把并行开发管住

AI 助手团队协作怎么落地：OMX 用 5 个阶段把并行开发管住

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

3 个 AI 同时改同一个仓库，最常见的结局是互相覆盖：这边刚写完鉴权，那边已经改了模块名，测试全挂。多人开发分工本身不难，难的是没人记下"谁在做什么、按什么顺序"。oh-my-codex（OMX）就是加在 Codex CLI 之上的一层 AI 助手团队协作机制，它把这类任务拆成阶段、面板和可恢复的磁盘状态。

🎵 一分钟定位：一场排练，不是一起即兴

把 OMX 想成乐队排练的指挥系统，而不是几个乐手各弹各的：

• 指挥是团队编排器，决定现在进入哪个乐章，谁先谁后
• 分声部乐手是 20 多个专业代理，executor 负责主旋律，verifier 负责听错音，architect 负责看总谱
• 五段流程是节拍器，没人能抢拍
• 磁盘状态是曲谱副本，中途走音或停场，回来能接着弹

Codex 仍然是实际"演奏"的引擎，OMX 负责排谱、分声部和控场。

核心机制拆解

五阶段流水线：任务不许跳拍

一句话定位：一个团队任务只能沿固定路线前进，想跳步会直接报错。

export type TeamPhase = 'team-plan' | 'team-prd' | 'team-exec' | 'team-verify' | 'team-fix'; const TRANSITIONS: Record<TeamPhase, Array<TeamPhase | TerminalPhase>> = { 'team-plan': ['team-prd'], 'team-exec': ['team-verify'], 'team-verify': ['team-fix', 'complete', 'failed'], // ... };

为什么这么设计：验证不过时，任务可以退回 fix 再回 exec，但 fix 循环默认最多 3 次（max_fix_attempts），超了就标记 failed。与其让一群代理互相修到天亮，不如让它停下来交还给人。规则写死在 src/team/orchestrator.ts 里，每次转场都会带时间戳记入phase_transitions，出问题能回放。

角色花名册：什么人上什么台

一句话定位：代理不是"一个模型套 N 份提示词"，而是按职责分了工具权限和推理档位。

export interface AgentDefinition { name: string; // 如 executor、verifier、architect reasoningEffort: 'low' | 'medium' | 'high' | 'xhigh'; modelClass: 'frontier' | 'standard' | 'fast'; tools: 'read-only' | 'analysis' | 'execution' | 'data'; }

为什么这么设计：explore 只读、低开销，适合快速扫代码库；architect 用 xhigh 档位但同样只读，保证设计阶段不动手。角色定义集中在 src/agents/definitions.ts，提示词本体放在prompts/目录，改行为不用动代码。

状态落在磁盘：断线能续场

一句话定位：代理之间不靠聊天同步，靠共享的状态文件同步。

• 团队配置、任务清单、每个 worker 的状态都写在.omx/state/team/下
• mailbox.ts管代理间留言，dispatch.ts管任务分派，locks.ts防止两个 worker 同时写同一份状态
• 配置结构见 src/team/state/types.ts，worker_count和max_workers直接控制并行度

为什么这么设计：tmux 面板随时可能挂掉，但文件还在，canResumeTeamState能判断一个团队是否值得恢复。状态共享不依赖任何进程活着，这是它敢让多个长任务并行执行的底氣。

三种配置，按任务重量选

轻任务：单角色并行就够

omx team 2:executor "fix all endpoint docs and report gaps"

适用边界：任务之间互不依赖，比如逐文件修文档、批量改错字。2 个 worker 起步，再多只会互相排队等状态。

中任务：先对齐，再并行

$deep-interview "clarify the authentication change" $ralplan "approve the auth plan and review tradeoffs" $team 3:executor "execute the approved plan in parallel"

适用边界：有依赖关系但范围清楚的改动。前两步花的时间买的是后面 3 个 executor 不跑偏，需求没对齐就并行，等于让乐队没看谱就开演。

重任务：混声部大编制

omx team 2:architect,1:planner,3:executor "redesign the payment system"

适用边界：跨模块的大改动，架构和排期需要专人把关。涉及安全或合规时，把 1 个 executor 换成 quality-reviewer 或 security-reviewer，让评审和实现同时走。

最小上手路径：5 步跑通

1. 确认引擎可用：codex --version，且已登录
2. 安装 OMX：npm install -g oh-my-codex
3. 在项目根目录做项目级配置：omx setup --scope project
4. 先进 tmux 再干活，用tmux -V确认已安装
5. 启动首个团队：omx team 2:executor "task description"，随后观察分屏面板，状态文件都在.omx/state/team/里可查

🧰 先解争用，再谈上限

• 最最常见的瓶颈是共享文件争用。多个 worker 改同一片代码时，用 worktree 模式给每个 worker 独立工作区，TeamConfig里的workspace_mode: 'single' | 'worktree'就是控制这个的
• worker 数量不合适再谈扩缩：scaling 支持会话中增删 worker，scale_up加人、scale_down让空闲 worker 排空后离场，由OMX_TEAM_SCALING_ENABLED开关控制
• 想混用不同 CLI：OMX_TEAM_WORKER_CLI_MAP=codex,claude可以让 2 个 worker 分别跑 Codex 和 Claude，注意N:agent-type选的是角色提示词，不是 CLI
• 看性能参照：仓库自带的基准测试对比了单线程与团队协作路径的耗时差异

方向上，后续的重心是自动按任务特征推荐角色、按团队表现自适应调整流程，现在这些还靠人判断。

🧯 踩坑后如何处理

面板没起来，命令直接报错→ 根因：当前会话不在 tmux 里（$TMUX未设置），或根本没装 tmux。处理：先进 tmux 再执行omx team；Codex App 内也起不了$team，回到 shell 终端操作。

HUD 面板混进了 worker 栈→ 根因：分屏前已有重复的hud --watch面板。处理：tmux list-panes -F '#{pane_id} #{pane_start_command}'查出重复项，删掉再启动团队。

两个 worker 互相覆盖同一文件→ 根因：任务之间没有依赖边界，也没启用协调协议。处理：换成 worktree 模式隔离工作区，或者在任务描述里明确"各 worker 负责独立文件集"。

团队跑了一会儿直接变 failed→ 根因：fix 阶段超过 3 次上限，编排器按规则终止。处理：别硬扛，把任务拆小后重新组队，一次只让团队修一个问题。

收尾

OMX 的价值不是"多雇几个 AI"，而是给 AI 助手团队协作一套曲谱：阶段固定、角色分权、状态落盘。下一步就从最轻的omx team 2:executor起步，跑顺后再按任务重量加人。

延伸阅读：Getting Started · Agents

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex