Task Dispatch（任务并行调度）

概述

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

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

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

定位

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

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

适用前提：同一会话内

本 skill 默认一个主 agent 在场：主 agent 拆分 → 并行启动子 agent（team_create + Task）→ 子 agent 间可用 send_message 协调 → 主 agent 合并产出。

这套机制依赖三件事：主 agent 存在、子 agent 可通信、生命周期同一会话。

场景	该用什么
同一会话内，多个独立子任务并行做完并合并	✅ 本 skill
用户要在多个对话窗 / 多个 IDE 手工并行（无主 agent 在场、窗口间无法通信）	❌ 本 skill 不适用 → 用 delivery-slicing（切片与批次）+ code-implement 并行窗口模式 + integration-merge（拼接）

为什么不能直接套：跨会话时 send_message 不存在、team_create 无意义、主 agent 缺席导致"合并集成"无人执行；且跨窗口的冲突防线必须前置（目录互斥 + 契约冻结），本 skill 的"合并时检测冲突"是事后防线，不足以支撑跨窗口场景。

判定一句话：Agent 之间能不能互相发消息？ 能 → 本 skill；不能 → delivery-slicing 路线。

核心原则

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 严格串行，无法并行
全局视角需求	需要统一调整跨模块接口、全局命名等
共享核心数据结构	多个子任务都要修改同一核心数据结构

输出格式

📥 任务分析
━━━━━━━━━━━━━━━━

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

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

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

---

阶段 1：子任务拆分

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

拆分维度

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

子任务描述规范

每个子任务必须包含：

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

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

三维度独立性校验

对每对子任务做检查：

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

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

独立性等级

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

输出格式

🔀 子任务拆分
━━━━━━━━━━━━━━━━

共拆出 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，避免资源竞争过大

顺序无关批次识别

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

排序校验

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

输出格式

🔗 批次划分
━━━━━━━━━━━━━━━━

执行批次：
  第 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）：

你是子 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：批次完成确认

🔨 批次 {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。

---

阶段 4：合并集成

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

合并流程

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

冲突检测与处理

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

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

输出格式

🔧 合并集成
━━━━━━━━━━━━━━━━

收集产出：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。

---

阶段 5：一致性校验

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

校验维度与方式

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

输出格式

📐 一致性校验
━━━━━━━━━━━━━━━━

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

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

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

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

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

最终交付

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

任务：{任务名称} ｜ 子任务：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。

---

反模式（不要做）

• ❌ 强行拆分强耦合任务 → 合并成本大于并行收益
• ❌ 拆分粒度过细（一个函数一个子任务）→ 协调成本爆炸
• ❌ 拆分粒度过粗（一个子任务含多个独立操作）→ 失去并行机会
• ❌ 忽略文件冲突就并行 → 合并时必然冲突返工
• ❌ 不定契约就让弱依赖子任务并行 → 接口不一致返工
• ❌ 子 agent 直接修改项目源码 → 绕过合并，无法检测冲突
• ❌ 子 agent 产出 diff 而非完整文件 → 合并复杂度高
• ❌ 子 agent 间传递大段代码 → prompt 膨胀
• ❌ 子 agent 自行扩大范围 → 破坏独立性
• ❌ 静默覆盖冲突文件 → 丢失产出，引入 bug
• ❌ 跳过一致性校验直接交付 → 接口不一致、导入缺失遗留
• ❌ 跨会话 / 跨 IDE 场景硬套本 skill → 无主 agent、子 agent 无法通信，send_message / team_create 全部失效 → 应走 delivery-slicing + integration-merge
• ❌ 把本 skill 当"冲突防线" → 它的冲突检测是事后的（合并时才发现），只适合同会话内快速合并；跨窗口并行必须事前防线（目录互斥 + 契约冻结）

---

技术实现指引

所用工具

工具	用途
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。

---

使用示例

触发方式

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

• "帮我并行实现用户模块、订单模块、支付模块"
• "这几个 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
• 任务拆分思路参考：work-breakdown skill（工作项拆分，不执行）
• 跨会话 / 跨 IDE 并行（切片 + 批次 + 契约冻结）：delivery-slicing skill
• 跨窗口产出合流（拼接）：integration-merge skill
• 设计文档生成：design-craft skill
• 实现结果归档：implementation-report skill