教程概述

Team Mode 是 oh-my-claudecode 的核心编排模式。它通过创建协调的多代理团队，将复杂任务分解为可并行执行的子任务，然后整合结果完成交付。

你将学到

• ✅ Team Mode 的核心架构与工作原理
• ✅ 流水线阶段详解（team-plan → team-prd → team-exec → team-verify → team-fix）
• ✅ 任务列表管理（创建、分配、依赖）
• ✅ 代理间通信机制
• ✅ 实战案例演示

为什么需要 Team Mode？

单代理的局限

flowchart LR
    A[复杂任务] --> B[单代理串行处理]
    B --> C[上下文膨胀]
    C --> D[效率下降]
    D --> E[质量不稳定]

    style B fill:#ffcccc
    style C fill:#ffcccc
    style D fill:#ffcccc

Team Mode 的解决方案

flowchart TD
    A[复杂任务] --> M[Team Lead - 协调器]
    M --> S1[Worker 1 - 数据库]
    M --> S2[Worker 2 - 后端 API]
    M --> S3[Worker 3 - 前端组件]

    S1 --> R[结果整合]
    S2 --> R
    S3 --> R
    R --> F[高质量交付]

    style M fill:#e1f5ff
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9
    style F fill:#fff3e0

效果对比

Team Mode 架构

核心流水线

flowchart LR
    A[team-plan] --> B[team-prd]
    B --> C[team-exec]
    C --> D[team-verify]
    D --> E{通过？}
    E -->|否| F[team-fix]
    F --> C
    E -->|是| G[完成]

    style A fill:#e1f5ff
    style B fill:#e3f2fd
    style C fill:#e8f5e9
    style D fill:#fff3e0
    style F fill:#ffebee

阶段详解

基本用法

语法格式

/team N:agent-type "task description"

快速示例

/team 3:executor "fix all TypeScript errors across the project"

执行流程：

1. 系统创建团队 fix-ts-errors
2. 分析代码库，分解为 3 个子任务
3. 启动 3 个 worker 并行执行
4. 验证修复结果
5. 报告完成状态

agent-type 选择

流水线深度解析

阶段 1：team-plan

目标：将复杂任务分解为可执行的子任务

flowchart TD
    A[接收任务] --> B[explore 分析代码库]
    B --> C[planner 创建任务图]
    C --> D[识别依赖关系]
    D --> E[输出任务列表]

    style A fill:#e1f5ff
    style E fill:#e8f5e9

输出示例：

# 任务分解

## Task #1: Fix auth module types
- File: src/auth/login.ts
- Priority: High
- Blocked by: None

## Task #2: Fix API module types
- File: src/api/*.ts
- Priority: Medium
- Blocked by: Task #1

## Task #3: Fix utils types
- File: src/utils/*.ts
- Priority: Low
- Blocked by: None

阶段 2：team-prd

目标：明确需求边界和验收标准

触发条件：

• 需求模糊
• 缺少验收标准
• 范围不清晰

输出：PRD 文档

# 需求文档

## 功能描述
修复项目中所有 TypeScript 类型错误

## 验收标准
- [ ] `tsc --noEmit` 无错误输出
- [ ] 所有新增类型都有 JSDoc 注释
- [ ] 不引入 `any` 类型

## 边界
- 仅修复类型错误，不重构代码逻辑
- 不处理第三方库类型定义问题

阶段 3：team-exec

目标：并行执行子任务

flowchart TD
    subgraph "Worker Pool"
        W1[Worker 1]
        W2[Worker 2]
        W3[Worker 3]
    end

    L[Team Lead] -->|Task #1| W1
    L -->|Task #2| W2
    L -->|Task #3| W3

    W1 --> R1[结果 1]
    W2 --> R2[结果 2]
    W3 --> R3[结果 3]

    R1 --> I[整合]
    R2 --> I
    R3 --> I

    style L fill:#e1f5ff
    style W1 fill:#e8f5e9
    style W2 fill:#e8f5e9
    style W3 fill:#e8f5e9

Worker 工作协议：

1. CLAIM: 从任务列表领取任务
2. WORK: 执行任务（Read, Write, Edit, Bash）
3. COMPLETE: 标记任务完成
4. REPORT: 向 Lead 报告进度
5. NEXT: 检查是否有更多任务

阶段 4：team-verify

目标：验证任务完成度

验证内容：

flowchart TD
    A[team-verify] --> B[功能验证]
    A --> C[代码审查]
    A --> D[测试验证]
    A --> E[安全检查]

    B --> F{通过？}
    C --> F
    D --> F
    E --> F

    F -->|是| G[阶段完成]
    F -->|否| H[生成修复任务]

    style A fill:#fff3e0
    style G fill:#e8f5e9
    style H fill:#ffebee

阶段 5：team-fix

目标：修复验证发现的问题

循环限制：最多 3 次修复迭代

flowchart TD
    A[验证失败] --> B[分析问题]
    B --> C[创建修复任务]
    C --> D[executor 执行修复]
    D --> E[重新验证]
    E --> F{通过？}
    F -->|否| G{迭代次数？}
    G -->|< 3| B
    G -->|>= 3| H[标记失败]
    F -->|是| I[完成]

    style H fill:#ffebee
    style I fill:#e8f5e9

任务列表管理

创建任务

使用 TaskCreate 工具：

{
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts and src/auth/session.ts",
  "activeForm": "Fixing auth type errors"
}

设置依赖

使用 TaskUpdate 设置依赖关系：

// Task #3 依赖 Task #1
{
  "taskId": "3",
  "addBlockedBy": ["1"]
}

分配任务

{
  "taskId": "1",
  "owner": "worker-1"
}

查看状态

使用 TaskList 查看所有任务：

#1 [completed] Fix type errors in src/auth/ (worker-1)
#2 [in_progress] Fix type errors in src/api/ (worker-2)
#3 [pending] Fix type errors in src/utils/ (worker-3)

代理通信机制

消息类型

通信示例

Worker → Lead（任务完成）：

{
  "type": "message",
  "recipient": "team-lead",
  "content": "Completed task #1: Fixed 3 type errors in src/auth/login.ts",
  "summary": "Task #1 complete"
}

Lead → Worker（重新分配）：

{
  "type": "message",
  "recipient": "worker-2",
  "content": "Task #3 is now unblocked. Please pick it up.",
  "summary": "New task available"
}

广播（紧急暂停）：

{
  "type": "broadcast",
  "content": "STOP: Shared types changed, pull latest before continuing",
  "summary": "Shared types updated"
}

消息交付机制

flowchart LR
    A[Worker 发送] --> B[消息队列]
    B --> C[Lead 接收]
    C --> D[处理消息]
    D --> E[更新状态]

    style B fill:#e3f2fd
    style C fill:#e8f5e9

重要：消息自动交付，无需轮询。当 Lead 正在处理时，消息会排队等待。

实战案例：修复 TypeScript 错误

任务

/team 3:executor "fix all TypeScript errors across the project"

执行过程

Step 1：分析分解

Team Lead 分析代码库：
- 发现 15 个 TypeScript 错误
- 分布在 3 个模块
- 创建 3 个子任务

Step 2：任务分发

Task #1 → Worker 1: src/auth/ (5 errors)
Task #2 → Worker 2: src/api/ (6 errors)
Task #3 → Worker 3: src/utils/ (4 errors)

Step 3：并行执行

gantt
    title 并行执行时间线
    dateFormat mm:ss

    section Worker 1
    Fix auth errors     :a1, 00:00, 3m

    section Worker 2
    Fix API errors      :a2, 00:00, 4m

    section Worker 3
    Fix utils errors    :a3, 00:00, 2m

    section Verification
    Run tsc --noEmit    :a4, after a2, 1m

Step 4：验证

$ tsc --noEmit
✓ No errors found

验证通过！

Step 5：完成

Team解散，报告结果：
- 修复 15 个 TypeScript 错误
- 修改 8 个文件
- 耗时 5 分钟

最佳实践

1. 合理设置 Worker 数量

推荐配置：
- 简单任务：1-2 workers
- 中等任务：3-5 workers
- 复杂任务：5-10 workers

避免过多 workers 导致资源竞争

2. 任务独立性

✅ 好：任务间无共享状态
   Task 1: 修复 auth 模块
   Task 2: 修复 API 模块

❌ 坏：任务会修改同一文件
   Task 1: 修改 file.ts 第 1-10 行
   Task 2: 修改 file.ts 第 11-20 行

3. 验收标准明确

✅ 好：具体可测试
   - tsc --noEmit 无错误
   - 测试覆盖率 >= 80%
   - API 响应时间 < 100ms

❌ 坏：模糊无法验证
   - 代码质量良好
   - 性能优化

4. 监控与干预

Team Lead 应该：
- 监控 TaskList 进度
- 及时响应 Worker 消息
- 处理阻塞任务
- 必要时重新分配

常见问题

Q1：任务卡住怎么办？

检查 TaskList，如果任务长时间 in_progress：

1. 发送消息询问状态
2. 如无响应，重新分配任务

Q2：Worker 失败怎么处理？

1. Worker 报告失败
2. Lead 决定：重试或跳过
3. 如重试，分配给其他 Worker

Q3：如何取消正在进行的 Team？

/oh-my-claudecode:cancel

这会发送 shutdown 请求给所有 Worker 并清理资源。

小结

Team Mode 通过多代理协作大幅提升复杂任务处理效率：

1. 流水线架构 - 规划 → 执行 → 验证 → 修复
2. 并行执行 - 多 Worker 同时工作
3. 任务管理 - 创建、分配、依赖、追踪
4. 自动协调 - Lead 自动编排，无需手动干预

关键要点

• ✅ Worker 数量根据任务复杂度调整
• ✅ 任务应保持独立性避免冲突
• ✅ 验收标准要具体可测试
• ✅ 监控进度并及时干预

系列导航：

• ← 上一篇：教程 1：入门与安装配置完全指南
• → 下一篇：教程 3：tmux CLI Workers 多 AI 协作
• 返回：教程系列索引