task-orchestrator

task-orchestrator 是一个面向复杂任务的任务编排 Skill。它的目标是把多步骤、多文件、多领域或可并行执行的任务拆解为更小的子任务，建立依赖关系，并通过多个 subagent 并行推进，最后统一合成结果。

这个 Skill 关注的不是“多开任务”本身，而是让 Agent 在复杂工作中具备更清晰的分工、更短的墙钟时间和更稳定的交付质量。

适用场景

当任务满足以下任一条件时，适合使用该 Skill：

• 涉及 3 个以上明显步骤。
• 涉及多个文件、模块、目录或技术领域。
• 可以按主题、文件、组件、数据批次或研究问题拆分。
• 需要并行调研、并行实现、并行测试或并行审查。
• 任务包括重构、迁移、复杂调试、新功能开发、测试生成、文档生成或代码审查。

典型例子：

• 重构多个目录下的错误处理逻辑。
• 为 CLI 工具同时添加配置、日志、子命令和进度条。
• 排查多个系统模块中的性能问题。
• 为一个功能同时实现 API、UI、数据库变更、测试和文档。
• 对多个来源、多个竞品或多个方案做研究并汇总。

不适用场景

以下情况通常不需要使用该 Skill：

• 单文件、单关注点的小改动。
• 所有步骤都强依赖前一步结果，无法并行。
• 任务范围未知，需要先做少量探索。
• 拆解、派发和合成的开销会超过直接完成任务的成本。

判断原则：如果能识别出 3 个以上相互独立的子任务，就优先拆解；如果任务本质是线性的，就不要强行并行化。

核心流程

1. Analyze

先分析任务边界，而不是立即执行：

• 明确最终交付物。
• 识别涉及的技术领域或知识领域。
• 找到天然拆分边界。
• 判断哪些部分可以并行，哪些部分必须串行。

2. Decompose

把任务拆成可独立完成的子任务：

• 每个子任务应有清晰输入、清晰输出和可验证结果。
• 大多数任务建议拆成 3 到 10 个子任务。
• 避免多个 subagent 同时写同一个文件。
• 如果写冲突不可避免，指定一个子任务作为文件 owner，其他子任务只产出补充材料。

3. Build Execution Plan

为每个子任务建立依赖图：

• 给每个子任务分配 ID。
• 标记依赖关系。
• 计算并行执行轮次。
• 找出关键路径，并尝试减少不必要依赖。

执行前应向用户展示：

• 子任务列表。
• 依赖关系。
• 并行轮次。
• 预计 subagent 调用数量。
• 是否需要用户确认或调整。

4. Dispatch

按轮次派发子任务：

• 每轮中，所有依赖已满足的子任务可以并行执行。
• 每个 subagent 都应获得明确上下文、具体任务、文件读写边界和成功标准。
• 如果某个 subagent 失败，先判断是否影响关键路径，再决定重试、绕过或延后处理。

5. Synthesize

所有子任务结束后进行合成：

• 收集各 subagent 输出。
• 检查是否覆盖用户原始目标。
• 合并冲突或重复内容。
• 做整体质量检查。
• 向用户汇报最终结果、关键决策和遗留风险。

常用拆解模式

代码改动

1. Explore: 理解现有实现
2. Design: 设计变更方案
3. Implement: 按文件、模块或组件拆分实现
4. Test: 编写或更新测试
5. Review: 自查一致性和风险

研究任务

1-N. Research: 每个主题、来源或问题一个 subagent
N+1. Synthesize: 汇总发现，识别共识、差异和建议

迁移任务

1. Audit: 盘点迁移范围
2. Plan: 定义迁移策略
3-N. Migrate: 按模块或组件并行迁移
N+1. Verify: 全局验证
N+2. Cleanup: 删除旧代码或临时兼容层

调试任务

1. Reproduce: 复现问题
2-N. Investigate: 并行验证不同假设
N+1. Fix: 基于确认的根因实现修复
N+2. Verify: 验证修复并添加回归测试

新功能开发

1. Design: 定义接口、数据模型和契约
2-N. Implement: API、UI、DB、服务逻辑等并行实现
N+1. Integrate: 集成各部分
N+2. Test: 端到端验证
N+3. Docs: 更新文档

更多模式见 references/decomposition-patterns.md。

Subagent 提示词模板

派发子任务时建议使用类似结构：

You are working on subtask {ID}: {title}

Context:
- Overall goal: {用户原始目标}
- Your specific role: {该子任务负责的范围}
- Dependencies completed: {已完成依赖的摘要}

Task:
{具体执行说明}

Files to work with:
- Read: {可读取文件}
- Write: {可创建或修改文件}

Success criteria:
- {可验证完成标准}

Save your output to: {输出路径}

关键点：

• 子任务说明必须具体。
• 文件读写边界必须明确。
• 成功标准必须可验证。
• 依赖输出要简洁传递，不要把无关上下文塞给 subagent。

目录结构

task-orchestrator/
├── SKILL.md
├── README.md
├── references/
│   └── decomposition-patterns.md
└── evals/
    └── evals.json

说明：

• SKILL.md 是 Codex 实际加载的 Skill 指令。
• README.md 是面向人类的使用和维护说明。
• references/decomposition-patterns.md 提供更细的任务拆解模式。
• evals/evals.json 存放 Skill 的评测样例。

使用示例

用户请求：

帮我给现有 API 增加鉴权功能，包括中间件、登录接口、刷新 token、测试和文档。

推荐编排：

Round 1:
- [Design] 定义鉴权方案、token 格式和接口契约
- [Explore] 调研项目现有 API 和中间件模式

Round 2:
- [Middleware] 实现鉴权中间件
- [Endpoints] 实现登录、注册或刷新 token 接口
- [Docs] 起草 API 文档

Round 3:
- [Tests] 编写单元测试和集成测试
- [Integration] 接入中间件和路由

Round 4:
- [Verify] 运行测试并做整体质量检查

质量准则

高质量编排应满足：

• 子任务之间边界清晰。
• 并行轮次真实可并行，而不是人为拆分。
• 每个子任务都有明确产物。
• 关键路径尽可能短。
• 合成阶段能产出一个统一结果，而不是一组松散报告。
• 用户始终能看懂当前计划、进度和风险。

常见问题

过度拆解

如果子任务超过 15 个，或每个子任务都很小，通常应合并相关任务，避免派发和合成成本过高。

虚假依赖

如果所有任务都被排成串行，检查依赖是否真实存在。很多任务只需要共同的设计输入，不需要等待彼此完成。

子任务太模糊

如果 subagent 需要反问“我要做什么”，说明子任务缺少输入、输出或成功标准。

忽略合成

并行执行后必须合成。没有合成阶段，用户只会得到割裂的局部结果。

过早并行

当架构、接口或迁移策略尚未确定时，不要直接并行实现。先完成设计，再把设计作为同步点分发给后续子任务。

维护建议

• 当发现新的高频任务类型时，把拆解模式补充到 references/decomposition-patterns.md。
• 当 Skill 在真实任务中表现不稳定时，优先检查子任务粒度、依赖判断和合成阶段。
• 新增评测样例时，覆盖不同任务类型：代码改动、调试、研究、迁移、测试和文档。
• 保持 SKILL.md 偏执行指令，保持 README 偏说明和维护文档。