Task Dispatch

---
name: task-dispatch
description: 将编码/开发任务拆分为多个独立子任务，并行分配给子agent执行，主agent负责合并集成。适用场景："并行开发"、"拆分子任务并行执行"、"多个子agent同时做"，或需并行实现多模块功能、修复多个独立bug、重构多个独立模块时。
---

# Task Dispatch（任务并行调度）

## 概述

**目的**：将一个编码/开发任务拆分为多个独立子任务，并行分配给子 agent 执行，加速交付。

**核心问题**：单个 agent 顺序完成多文件/多模块任务时，耗时长且长上下文下易遗漏细节。

**解决方案**：主 agent 拆分任务 → 子 agent 并行执行并产出到独立目录 → 主 agent 合并集成并校验一致性。

## 定位

```
[需求/设计/任务描述] → task-dispatch → 集成后的代码交付物
                        ├─ 拆分（内建）
                        ├─ 并行执行（子 agent）
                        └─ 合并集成（主 agent）
```

- **输入**：任务描述（需求文档、设计文档、bug 列表、重构目标等）
- **输出**：集成后的代码交付物（已合并到项目源码目录）
- **边界**：只管"可并行任务的拆分+调度+合并"，不管"任务本身的设计"（设计由 design-craft 负责）。与 work-breakdown 区别：work-breakdown 输出工作项清单（不执行），task-dispatch 输出已集成的代码（执行+合并）

## 核心原则

1. **真正独立才并行**：子任务间无文件冲突、无接口强依赖、无共享资源竞争，才能并行。否则合并或分批
2. **文件落盘式协作**：子 agent 产出写入独立目录，主 agent 读取合并，避免 prompt 膨胀
3. **主 agent 负责合并**：子 agent 不直接修改项目源码，产出到隔离目录，由主 agent 统一合并集成
4. **批次按依赖划分**：无依赖同层并行，有依赖分批执行，前置批次完成才启动后续
5. **冲突显式处理**：合并时检测冲突，分档处理（文件冲突/接口冲突/逻辑冲突），不静默覆盖
6. **不适合则不拆**：强耦合单文件任务、需全局视角的架构改动、依赖密集型重构 → 走快速通道直接执行

## 工作流总览

```
阶段 0：任务分析      → 理解任务，判断是否适合并行拆分
阶段 1：子任务拆分    → 拆分为独立子任务 + 三维度独立性校验
阶段 2：批次划分      → 按依赖关系划分并行批次
阶段 3：并行执行      → 启动子 agent 并行执行，产出到独立目录
阶段 4：合并集成      → 主 agent 合并产出，处理冲突
阶段 5：一致性校验    → 验证集成结果，输出最终交付
```

**未得到用户对当前阶段的确认前，不进入下一阶段。**

### 快速通道

当任务满足以下任一条件时，不启用并行拆分，直接单 agent 执行：

- 只涉及 1 个文件
- 强依赖单一路径（A 步骤的输出是 B 步骤的输入，无法分离）
- 需要全局视角的架构级改动（如跨模块接口统一调整）
- 子任务间存在 ❌ 强依赖且无法消除

触发快速通道时输出判定理由，由主 agent 自行顺序编码，不走阶段 1-5。

---

## 阶段 0：任务分析

读取任务来源，判断是否适合并行拆分。

### 输入来源

- 需求文档 / 设计文档（design-craft 产出）
- bug 列表 / 重构目标
- 用户直接描述的任务

### 适合并行的判定信号

| 信号 | 说明 |
|------|------|
| 多文件/多模块 | 任务天然涉及多个独立文件或模块 |
| 多独立操作 | 任务包含多个互不依赖的操作（如修多个独立 bug） |
| 端到端切片可分 | 任务可按垂直切片分离（参考 work-breakdown 思路） |
| 有独立验证点 | 每个子任务完成后可独立验证 |

### 不适合并行的判定信号

| 信号 | 说明 |
|------|------|
| 单文件强耦合 | 所有改动集中在 1 个文件，无法拆分 |
| 串行依赖链 | A→B→C 严格串行，无法并行 |
| 全局视角需求 | 需要统一调整跨模块接口、全局命名等 |
| 共享核心数据结构 | 多个子任务都要修改同一核心数据结构 |

### 输出格式

```text
📥 任务分析
━━━━━━━━━━━━━━━━

任务来源：[需求文档 / 设计文档 / bug列表 / 用户描述]
核心目标：<一句话概括> ｜ 涉及范围：<文件/模块/操作列表>

并行可行性：✅ 适合并行 / ⚠️ 边界情况 / ❌ 不适合并行
判定理由：<说明>
[若 ⚠️] 需协调点：<列出> ｜ [若 ❌] 走快速通道，直接单 agent 执行

请确认，是否进入拆分阶段？[Y/n]
```

---

## 阶段 1：子任务拆分

将任务拆分为独立子任务，并做三维度独立性校验。

### 拆分维度

| 维度 | 适用场景 | 示例 |
|------|----------|------|
| **按文件/模块拆** | 任务涉及多个独立文件/模块 | 用户模块、订单模块、支付模块 → 三个子任务 |
| **按独立操作拆** | 任务包含多个互不依赖的操作 | 修 bug A、修 bug B、修 bug C → 三个子任务 |
| **按垂直切片拆** | 任务可端到端分离 | 注册流程、登录流程 → 两个子任务 |
| **按职责层拆** | 任务跨多层且层间接口稳定 | 数据层、业务层、接口层 → 三个子任务（需接口契约先定） |

### 子任务描述规范

每个子任务必须包含：

```markdown
### S-{NN}：{子任务名称}

- **目标**：<一句话说明做什么>
- **涉及文件**：<列出将创建/修改的文件路径>
- **输入依赖**：<需要哪些前置产出/接口契约/数据定义>
- **输出契约**：<将产出什么接口/数据/文件，供其他子任务或主 agent 使用>
- **验收标准**：<完成后如何验证>
- **独立性说明**：<为什么这个子任务可以独立执行>
```

### 三维度独立性校验

对每对子任务做检查：

| 维度 | 判定标准 | 处理 |
|------|----------|------|
| **文件级** | 是否修改同一文件 | ✅ 无交集可并行 / ❌ 有交集必须合并或重排 |
| **接口级** | 是否依赖彼此的接口产出 | ✅ 无依赖可并行 / ⚠️ 弱依赖需先定契约 / ❌ 强依赖分批 |
| **共享资源** | 是否操作同一共享资源（配置表、核心数据结构、公共工具类） | ✅ 只读可并行 / ⚠️ 有默认值可兜底 / ❌ 写竞争必须合并 |
| **隐式 import** | 一个子任务的产出可能被另一个子任务 import | ✅ 无 import 关系可并行 / ⚠️ 有隐式 import 需先定契约 |

**隐式 import 扫描**：拆分前扫描现有代码 import 关系图，若子任务 A 创建的模块可能被子任务 B import，标记为⚠️弱依赖并先定契约，避免到阶段 5 才发现返工。

### 独立性等级

| 等级 | 条件 | 处理 |
|------|------|------|
| ✅ 完全独立 | 三维度均无冲突 | 可同批并行 |
| ⚠️ 弱依赖 | 接口弱依赖（可先定契约）或共享资源有兜底 | 同批并行但需先定契约/兜底 |
| ❌ 强依赖 | 文件冲突或接口强依赖或写竞争 | 合并子任务，或分批执行 |

### 输出格式

```text
🔀 子任务拆分
━━━━━━━━━━━━━━━━

共拆出 N 个子任务：

| 编号 | 子任务 | 涉及文件 | 输出契约 | 独立性 |
|------|--------|----------|----------|--------|
| S-01 | ... | file_a.py | UserService 类 | ✅ |
| S-02 | ... | file_c.py | OrderService 类 | ✅ |
| S-03 | ... | file_d.py | 依赖 S-01 UserService | ⚠️ |

独立性校验：S-01↔S-02 ✅ ｜ S-01↔S-03 ⚠️弱依赖（需先定契约）｜ S-02↔S-03 ✅
需先定的契约：UserService 接口签名 <列出>
处理建议：S-01,S-02 同批并行 ｜ S-03 分第 2 批 或 先定契约后 S-01/S-03 同批

请确认拆分方案，或选择处理方式。
```

---

## 阶段 2：批次划分

按依赖关系划分并行批次。

### 批次划分规则

1. **无依赖的子任务** → 同一批，并行执行
2. **有强依赖的子任务** → 分批，前置批次完成才启动后续
3. **弱依赖（需契约）** → 优先"先定契约再并行"，契约由主 agent 在批次启动前确定
4. **同批次上限**：建议 ≤ 5 个子 agent，避免资源竞争过大

### 顺序无关批次识别

同一依赖层级中无交叉依赖的子任务，标记为顺序无关（可按任意顺序执行）。

### 排序校验

- 每个子任务的所有前提条件是否已在之前批次完成
- 是否有循环依赖（如有，标记并提示用户）
- 顺序无关批次之间是否存在隐式共享资源（如修改同一文件的不同部分），若有则标注警告

### 输出格式

```text
🔗 批次划分
━━━━━━━━━━━━━━━━

执行批次：
  第 1 批 [并行]（无依赖）：S-01（X 文件）、S-02（Y 文件）
  第 2 批 [依赖前批]（依赖 S-01）：S-03（Z 文件）

批次说明：第 1 批 S-01/S-02 完全独立并行 ｜ 第 2 批 S-03 依赖 S-01，需等第 1 批完成
[若有弱依赖] 批次前需定契约：UserService 接口签名 <列出>，主 agent 启动前写入 contracts/

确认批次划分，是否开始并行执行？[Y/n]
```

---

## 阶段 3：并行执行

启动子 agent 并行执行，每个子 agent 产出到独立目录。

### 目录结构

```
.codebuddy/task-dispatch/{task-name}/
├── plan.md              # 拆分方案 + 批次划分（主 agent 写入）
├── contracts/           # 接口契约（弱依赖场景，主 agent 写入）
│   └── user-service.md
├── subtasks/
│   ├── S-01/
│   │   ├── code/        # 代码产出，按项目相对路径摆放
│   │   │   └── src/services/user_service.py
│   │   └── report.md    # 子 agent 执行报告
│   ├── S-02/
│   │   ├── code/
│   │   │   └── src/services/order_service.py
│   │   └── report.md
│   └── ...
├── merge-log.md         # 合并过程记录（主 agent 写入）
└── final-report.md      # 最终交付报告
```

### task-name 命名规则

- 英文小写 + 短横线，从任务描述提取 2-4 个关键词
- 示例：`user-order-impl`、`multi-bugfix`、`refactor-auth`
- 总长度 ≤ 64 字符
- 如遇同名目录，追加 `-v2` 后缀

### 子 agent 启动流程

#### 步骤 1：主 agent 准备

1. 写入 `plan.md`（拆分方案 + 批次划分）
2. 若有弱依赖需先定契约，写入 `contracts/*.md`
3. 用 `team_create` 创建调度团队

#### 步骤 2：并行启动子 agent

对当前批次的每个子任务，用 `Task`（team 模式）启动子 agent。

**子 agent prompt 要点**（详细模板见 [reference.md](reference.md)）：

```
你是子 agent，负责执行子任务 S-{NN}：{名称}
任务目标：{目标} ｜ 涉及文件：{文件列表}
输入依赖/契约：{契约文件路径或说明}
输出目录：.codebuddy/task-dispatch/{task-name}/subtasks/S-{NN}/code/（按项目相对路径摆放）
输出报告：.codebuddy/task-dispatch/{task-name}/subtasks/S-{NN}/report.md

要求：
1. 只在输出目录内工作，不修改项目源码
2. 代码按项目实际相对路径摆放，便于主 agent 合并
3. 完成后写 report.md（做了什么、产出清单、接口约定、注意事项、阻塞点）
4. 如需确认接口，通过 send_message 沟通（仅限契约确认，不传大段代码）
5. 遇到无法独立完成的问题写入 report.md"阻塞点"，不自行扩大范围
```

#### 步骤 3：批次内协调

子 agent 间可通过 `send_message` 沟通接口契约（仅限确认，不传代码）；主 agent 监控进度，子 agent 完成后回报。

#### 步骤 4：批次完成确认

```text
🔨 批次 {N}/{总计}：{批次名称}
  - S-01：✅ 完成（产出 X 文件）
  - S-02：✅ 完成（产出 Y 文件）
  - S-03：⚠️ 部分完成（阻塞点：{说明}，建议：{处理方式}）
是否继续下一批次 / 处理阻塞？[Y/n]
```

### 子 agent 产出规范

#### 代码文件

- 按项目实际相对路径摆放，例如项目结构是 `src/services/user_service.py`，则子 agent 写入 `subtasks/S-01/code/src/services/user_service.py`
- 对于"修改现有文件"的子任务：子 agent 先读取项目中的原文件，在输出目录中产出修改后的完整文件（不产出 diff），并在 report.md 中说明修改点

#### report.md 格式

子 agent 完成后必须写 report.md，包含：任务目标、产出文件清单（路径+类型+说明）、接口约定（供其他子任务/主 agent 参考）、修改点说明（针对修改现有文件）、注意事项、阻塞点（如有）。详细格式见 [reference.md](reference.md)。

---

## 阶段 4：合并集成

主 agent 收集所有子 agent 产出，合并到项目源码目录，处理冲突。

### 合并流程

收集 `subtasks/*/code/` 产出 → 按相对路径映射到项目位置 → 检测冲突 → 分档处理 → 写入项目源码 → 记录 `merge-log.md`。

### 冲突检测与处理

| 冲突类型 | 检测方式 | 处理方式 |
|----------|----------|----------|
| **文件冲突** | 两个子任务产出修改了同一文件 | 主 agent 三方合并（两份产出+原文件）；无法合并则标记给用户决策 |
| **接口冲突** | 不同子任务对同一接口的签名定义不一致 | 以契约文件为准，让偏离方修复；无契约时以先完成者为基准 |
| **逻辑冲突** | 不同子任务的实现逻辑矛盾 | 标记给用户决策，不静默选择 |
| **无冲突** | 文件无交集，接口一致 | 直接合并 |

合并规则：新增文件直接复制；修改文件校验修改点后覆盖原文件（"原文件"指当前项目源码最新版本，可能已被前序批次合并修改过）；多源同文件触发文件冲突处理，三方合并以当前源码为准；跨子任务接口校验签名一致性。冲突处理细节见 [reference.md](reference.md)。

### 输出格式

```text
🔧 合并集成
━━━━━━━━━━━━━━━━

收集产出：N 个子任务，共 M 个文件

合并结果：
  ✅ 直接合并：X 个文件
  ⚠️ 冲突处理：Y 个文件
    - {文件}：文件冲突（S-01 + S-02），已三方合并
    - {文件}：接口冲突（UserService.login 签名不一致），以契约为准，已修复 S-02
  ❌ 无法合并：Z 个文件 → {文件}：逻辑冲突，需用户决策

[若有 ❌] 需用户决策的冲突：列出选项，请选择 [A/B/...]

合并日志：.codebuddy/task-dispatch/{task-name}/merge-log.md
确认合并结果，是否进入一致性校验？[Y/n]
```

`merge-log.md` 格式见 [reference.md](reference.md)。

---

## 阶段 5：一致性校验

验证集成结果的正确性和一致性。

### 校验维度与方式

| 维度 | 校验内容 | 校验方式 | 通过标准 |
|------|----------|----------|----------|
| **编译/语法** | 代码可解析无语法错误 | 运行语言检查命令（Python `py_compile`、TS `tsc --noEmit`、Go `go build`） | 零错误 |
| **接口一致** | 跨子任务接口调用与定义签名一致 | 读取所有 report.md，比对接口约定与实际实现 | 零偏差 |
| **导入完整** | 所有 import 指向已存在模块 | 扫描合并后文件的 import 语句，验证目标存在 | 零缺失 |
| **集成点验证** | 子任务间集成点调用正确 | 识别跨子任务调用关系，逐一验证 | 零偏差 |
| **验收标准** | 每个子任务验收标准均满足 | 逐项核对 | 100% 满足 |
| **冲突残留** | 阶段 4 标记的冲突已全部处理 | 复核冲突清单 | 零残留 |

### 输出格式

```text
📐 一致性校验
━━━━━━━━━━━━━━━━

校验范围：全部 N 个子任务的集成结果

逐项校验：
  ✅ 编译/语法：零错误
  ✅ 接口一致：零偏差
  ⚠️ 导入完整：1 个缺失 → {文件} import {模块}，模块未找到
  ✅ 集成点验证：零偏差
  ✅ 验收标准：100% 满足
  ✅ 冲突残留：零残留

校验结果：✅ 通过 / ⚠️ 存在问题（列出问题项）

问题处理：
  - 导入缺失：{文件} import {模块} → 补充创建 {模块} 或修正 import
```

校验通过后进入最终交付。

### 最终交付

```text
✅ 任务并行调度完成
━━━━━━━━━━━━━━━━

任务：{任务名称} ｜ 子任务：N 个（并行 X 批）｜ 产出文件：M 个（新增 A / 修改 B）
合并冲突：处理 Y 个 ｜ 一致性校验：✅ 通过
集成结果：已写入项目源码目录 ｜ 过程记录：.codebuddy/task-dispatch/{task-name}/

🚀 后续行动选择
1. 🔍 运行测试验证集成结果
2. 📝 生成实现报告（implementation-report skill）
3. ⏭️ 结束
请选择 [1/2/3]：
```

`final-report.md` 格式见 [reference.md](reference.md)。

---

## 反模式（不要做）

- ❌ 强行拆分强耦合任务 → 合并成本大于并行收益
- ❌ 拆分粒度过细（一个函数一个子任务）→ 协调成本爆炸
- ❌ 拆分粒度过粗（一个子任务含多个独立操作）→ 失去并行机会
- ❌ 忽略文件冲突就并行 → 合并时必然冲突返工
- ❌ 不定契约就让弱依赖子任务并行 → 接口不一致返工
- ❌ 子 agent 直接修改项目源码 → 绕过合并，无法检测冲突
- ❌ 子 agent 产出 diff 而非完整文件 → 合并复杂度高
- ❌ 子 agent 间传递大段代码 → prompt 膨胀
- ❌ 子 agent 自行扩大范围 → 破坏独立性
- ❌ 静默覆盖冲突文件 → 丢失产出，引入 bug
- ❌ 跳过一致性校验直接交付 → 接口不一致、导入缺失遗留

---

## 技术实现指引

### 所用工具

| 工具 | 用途 |
|------|------|
| `team_create` / `team_delete` | 创建/清理调度团队 |
| `Task`（team 模式） | 启动子 agent 并行执行 |
| `send_message` | 子 agent 间接口确认、子 agent 回报完成 |
| `write_to_file` / `read_file` | 产出写入/读取 |
| `search_content` / `search_file` | 一致性校验时扫描 import、接口调用 |

### 关键规则

1. **子 agent 必须并行启动**：同批次子 agent 用多个 Task 调用并行启动，不串行
2. **文件落盘式协作**：产出写入独立目录，prompt 只传路径和任务描述，不传大段代码
3. **主 agent 负责合并**：子 agent 不直接改项目源码，主 agent 统一合并
4. **契约先行**：弱依赖场景，主 agent 在启动子 agent 前写入契约文件
5. **冲突显式处理**：合并时检测冲突，分档处理，不静默覆盖
6. **完成后清理**：调用 `team_delete` 清理团队，产出文件保留供查阅
7. **批次串行**：有依赖的批次必须等前置批次完成才启动
8. **异常处理**：单个子 agent 失败时可重试或标记阻塞，不阻塞其他子任务

### 注意事项

- 同批次子 agent 建议 ≤ 5 个；子 agent 执行建议 ≤ 10 分钟，超时由主 agent 终止，**超时产出不参与合并**，标记"未完成"由主 agent 重试或补全
- 用户可随时中断，主 agent 清理团队并输出当前阶段中间结果
- 与 work-breakdown 区别：work-breakdown 只拆分不执行，task-dispatch 拆分+执行+合并

子 agent prompt 模板与冲突处理细节见 [reference.md](reference.md)。

---

## 使用示例

### 触发方式

用户明确要求并行执行时触发：

- "帮我并行实现用户模块、订单模块、支付模块"
- "这几个 bug 是独立的，并行修一下"
- "用 task-dispatch 拆分并行开发"
- "把这个重构任务拆成子任务并行执行"
- "多个子 agent 同时做这个功能"

### 典型流程

1. 用户：帮我并行实现用户服务、订单服务、支付服务三个模块
2. 主 agent：任务分析 → 适合并行（3 个独立模块）
3. 主 agent：拆分 S-01/S-02/S-03 → 独立性校验均 ✅ 完全独立
4. 主 agent：批次划分 → 第 1 批并行执行全部
5. 主 agent：创建团队，并行启动 3 个子 agent
6. 子 agent：各自在 `subtasks/S-0X/code/` 下产出代码 + report.md
7. 主 agent：收集产出，合并到项目源码目录
8. 主 agent：一致性校验（编译、接口、导入）→ 输出最终交付报告

### 查看过程文件

所有过程文件保存在：`.codebuddy/task-dispatch/{task-name}/`

- 拆分方案：`plan.md`；接口契约：`contracts/*.md`
- 子任务报告：`subtasks/*/report.md`
- 合并日志：`merge-log.md`；最终报告：`final-report.md`

---

## 附加资源

- 子 agent prompt 模板与冲突处理细节：[reference.md](reference.md)
- 任务拆分思路参考：`work-breakdown` skill（工作项拆分，不执行）
- 设计文档生成：`design-craft` skill
- 实现结果归档：`implementation-report` skill