教程概述

$team 是 oh-my-codex 的多代理协调系统，通过 tmux 实现并行团队执行，大幅提升大型任务的完成效率。

你将学到

• ✅ $team 系统的工作原理
• ✅ tmux 团队协调机制
• ✅ worktree 隔离技术
• ✅ 任务分配与监控
• ✅ 并行开发实战

触发方式标识

trigger_mode: "显式命令（$team 或 omx team）"
codex_native_alternative: "无（需手动管理多个会话）"
superpowers_equivalent: "子代理开发模式"
when_to_use_omx: "大型任务，可并行分解"
when_to_skip_omx: "小型、串行任务"

为什么需要 $team？

单代理的问题

flowchart TD
    A[大型任务] --> B[单代理串行执行]
    B --> C[任务 1]
    C --> D[任务 2]
    D --> E[任务 3]
    E --> F[任务 4]
    F --> G[耗时: 4T]

    style B fill:#ffcccc

多代理的优势

flowchart TD
    A[大型任务] --> B[$team 分解]
    B --> C[代理 1: 任务 1]
    B --> D[代理 2: 任务 2]
    B --> E[代理 3: 任务 3]
    B --> F[代理 4: 任务 4]
    C --> G[合并结果]
    D --> G
    E --> G
    F --> G
    G --> H[耗时: T]

    style B fill:#e1f5ff
    style G fill:#e8f5e9

$team 是什么？

$team 是 oh-my-codex 提供的多代理协调系统，核心特性：

1. 自动任务分解 - 将大型任务分解为可并行子任务
2. tmux 会话管理 - 每个代理运行在独立的 tmux pane
3. worktree 隔离 - 每个代理在独立的 Git worktree 工作
4. 实时监控 - 监控所有代理进度
5. 自动合并 - 完成后自动合并结果

架构图

flowchart TB
    subgraph Lead["团队协调器 (Lead)"]
        A[$team]
        B[任务分解]
        C[监控]
        D[合并]
    end

    subgraph Workers["代理团队"]
        E[Worker 1]
        F[Worker 2]
        G[Worker 3]
        H[Worker 4]
    end

    subgraph Worktrees["Git Worktrees"]
        I[worktree/1]
        J[worktree/2]
        K[worktree/3]
        L[worktree/4]
    end

    A --> B
    B --> E
    B --> F
    B --> G
    B --> H
    E --> I
    F --> J
    G --> K
    H --> L
    C --> Workers
    Workers --> D

    style Lead fill:#e3f2fd
    style Workers fill:#e8f5e9
    style Worktrees fill:#fff3e0

tmux 协调机制

tmux 会话结构

omc-team-session/
├── window 1: Coordinator (协调器)
├── window 2: Worker-1 (代理 1)
├── window 3: Worker-2 (代理 2)
├── window 4: Worker-3 (代理 3)
└── window 5: Worker-4 (代理 4)

启动命令

# 启动 4 个代理的 team
$team 4 "重构整个项目"

# 或使用 omx 命令
omx team 4 "实现大型功能"

实时监控

# 查看所有代理状态
omx team status

# 查看特定代理日志
omx team logs worker-1

# 向所有代理广播消息
omx team broadcast "注意：接口已更新"

worktree 隔离技术

为什么需要 worktree？

防止多个代理同时修改同一文件导致冲突。

worktree 结构

project/
├── .git/                 # 主仓库
├── src/                  # 主工作区
└── .omx/
    └── worktrees/
        └── team-feature/
            ├── worker-1/     # 代理 1 的工作区
            │   └── src/
            ├── worker-2/     # 代理 2 的工作区
            │   └── src/
            ├── worker-3/     # 代理 3 的工作区
            │   └── src/
            └── worker-4/     # 代理 4 的工作区
                └── src/

工作流程

flowchart TD
    A[主分支] --> B[创建 worktrees]
    B --> C1[worker-1 分支]
    B --> C2[worker-2 分支]
    B --> C3[worker-3 分支]
    B --> C4[worker-4 分支]
    C1 --> D1[独立开发]
    C2 --> D2[独立开发]
    C3 --> D3[独立开发]
    C4 --> D4[独立开发]
    D1 --> E[合并到主分支]
    D2 --> E
    D3 --> E
    D4 --> E

    style B fill:#e3f2fd
    style E fill:#e8f5e9

完整实战案例

场景：重构大型前端项目

任务：重构包含 50 个组件的 React 项目

步骤 1：启动 Team

$team 5 "重构 React 项目组件"

步骤 2：任务自动分解

Task 1: 重构 Button 组件 (Worker 1)
Task 2: 重构 Input 组件 (Worker 2)
Task 3: 重构 Form 组件 (Worker 3)
Task 4: 重构 Table 组件 (Worker 4)
Task 5: 重构 Modal 组件 (Worker 5)

步骤 3：并行执行

timeline
    title Team 执行时间线
    section Worker 1
        重构 Button : 0-10min
    section Worker 2
        重构 Input : 0-8min
    section Worker 3
        重构 Form : 0-15min
    section Worker 4
        重构 Table : 0-12min
    section Worker 5
        重构 Modal : 0-9min

步骤 4：监控进度

# 查看整体进度
$ omx team status
Team: react-refactor
Workers: 5
Completed: 3/5
In Progress: 2/5

# 查看详细状态
Worker 1: ✅ Button - Completed (10min)
Worker 2: ✅ Input - Completed (8min)
Worker 3: 🔄 Form - In Progress (12min/15min)
Worker 4: ✅ Table - Completed (12min)
Worker 5: ✅ Modal - Completed (9min)

步骤 5：合并结果

# 自动合并所有 worktree
$team merge

# 解决冲突（如有）
$team resolve

最终结果：

• 总耗时：15 分钟（最长任务）
• 串行预估：54 分钟
• 效率提升：3.6x

任务分配策略

策略 1：文件级分配

Worker 1: src/components/Button/
Worker 2: src/components/Input/
Worker 3: src/components/Form/

适用：组件化、模块化项目

策略 2：功能级分配

Worker 1: 用户认证功能
Worker 2: 订单管理功能
Worker 3: 支付功能

适用：微服务、功能独立

策略 3：层级级分配

Worker 1: API 层
Worker 2: 业务逻辑层
Worker 3: 数据访问层

适用：分层架构

核心原则

DO（推荐做法）

✅ 确保任务可并行分解
✅ 合理设置代理数量（通常 3-6 个）
✅ 监控进度，及时发现问题
✅ 验证合并后的结果

DON’T（避免做法）

❌ 将串行任务强制并行
❌ 创建过多代理（>10）
❌ 忽视代理间的依赖关系
❌ 不验证合并结果

反模式与常见错误

反模式 1：过度并行

❌ 错误：
为 5 个文件创建 10 个代理

✅ 正确：
根据 CPU 核心数和任务复杂度设置
通常 3-6 个代理最优

反模式 2：忽视依赖

❌ 错误：
Task B 依赖 Task A，但并行执行

✅ 正确：
使用任务依赖管理
$team --deps "task2:task1"

反模式 3：worktree 污染

❌ 错误：
代理修改共享配置文件

✅ 正确：
每个代理只修改分配的文件
共享配置由 Lead 管理

vs 原生 Codex

vs Superpowers

快速参考

命令速查

# 启动 team
$team N "任务描述"
omx team N "任务描述"

# 查看状态
omx team status

# 查看日志
omx team logs worker-N

# 广播消息
omx team broadcast "消息"

# 合并结果
$team merge

# 停止 team
$team stop

参数说明

小结

$team 通过并行执行大幅提升大型任务的效率，是 oh-my-codex 的效率倍增器。

核心要点：

1. 大型可分解任务用 $team
2. 合理设置代理数量
3. 使用 worktree 避免冲突
4. 监控进度，及时干预

上一篇：教程 5：$ralph 与执行模式

下一篇：教程 7：.omx/ 状态管理与 Hooks