agentleFS
HACK-WUHACK-WU/skills/skills/task-dispatch/SKILL.md

task-dispatch

Skill3 starsChanged 52 days agoMITView on GitHub

把编码 / 开发任务拆成多个独立子任务,并行分派子 agent 执行,主 agent 负责合并集成。触发:"并行开发"、"拆分子任务并行执行"、"多个子 agent 同时做",或多模块功能、多个独立 bug、多个模块重构。

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.