task-dispatcher

name	task-dispatcher
description	路由开发任务到 Codex 执行。触发词：/dispatch、任务分派。默认 Codex 执行，自动拆分任务、设置验证、支持并发分派。

Task Dispatcher

核心策略：任务细分 → 验证定义 → 并发分派 → Codex 执行 → 结果验收

触发方式

• /dispatch <任务描述>
• /task-dispatcher
• 检测到开发任务时自动触发

核心原则

原则	描述
先拆分，后执行	任务必须细分到单一职责
先预估，后分派	分派前必须预估时间，超限则拒绝
先验证，后分派	每个子任务必须有验证命令
可并发则并发	无依赖的任务并行执行
超时即终止	执行时间超限立即终止并诊断

工作流程

用户请求 → 是否需要深度推理？
              │
      ┌───────┴───────┐
      ▼ 是            ▼ 否
  Claude 推理    任务拆分
      │               │
      │               ▼
      │          时间预估 ──→ 超限? ──→ 拒绝分派，要求进一步拆分
      │               │ 正常
      │               ▼
      │          定义验证 → 依赖分析 → 并发分派
      │               │
      └───────┬───────┘
              ▼
         执行监控 ──→ 超时? ──→ 终止 + 诊断
              │ 正常
              ▼
         验证结果 → 通过/失败回退

第一步：任务拆分

拆分原则

原则	示例
单一职责	❌ "实现并测试登录" → ✅ "实现登录" + "测试登录"
单文件	❌ "重构 A 和 B" → ✅ "重构 A" + "重构 B"
可验证	每个子任务必须有对应的验证命令
原子性	执行失败可独立回退
时间可控	单个子任务预估时间 ≤ 120 秒

拆分判断

使用脚本判断是否需要拆分：

python ~/.claude/skills/task-dispatcher/scripts/task-logic.py should-split "任务描述"

必须拆分的情况：

• 包含「并」「和」「+」连接词
• 涉及多个文件
• 包含多个动词（实现、测试、重构...）
• 预估变更超过 100 行
• 预估时间超过 120 秒

第二步：时间预估（强制）

分派前必须预估时间，超限则拒绝分派。

预估命令

python ~/.claude/skills/task-dispatcher/scripts/task-logic.py estimate "任务描述"

时间限制

预估时间	风险等级	行动
≤ 90s	✅ ok	正常分派
90-120s	⚠️ warning	警告，建议拆分
> 120s	🚫 reject	拒绝分派，必须拆分

任务类型参考时间

类型	预估时间	说明
配置/格式化	15s	简单修改
函数/方法	45s	单个函数实现
测试用例	60s	单个测试文件
功能/组件	90s	边界，建议拆分
模块/系统	180s+	必须拆分

预估超限处理

当预估时间 > 120s 时：

1. 拒绝分派，不调用 Codex
2. 分析原因：多文件？多操作？范围过大？
3. 要求拆分：将任务拆分为更小的子任务
4. 重新预估：确保每个子任务 ≤ 120s

第三步：定义验证

每个子任务必须有验证命令，参考 templates/verification-reference.md

任务类型	验证命令
TypeScript	tsc --noEmit
Rust	cargo check
单测	npm test -- --grep '{pattern}'
API	curl -s {url} | jq .{field}

第四步：依赖分析

使用脚本分析依赖关系，生成执行批次：

python ~/.claude/skills/task-dispatcher/scripts/task-logic.py analyze-deps '[{"id":1,"deps":[]},{"id":2,"deps":[1]}]'

并发规则

条件	并发?
无依赖	✅ 并发
不同文件	✅ 并发
同文件不同函数	⚠️ 串行
有显式依赖	❌ 串行

第五步：并发分派

在单个消息中调用多个 Task 实现并发：

批次 1 (并发):
- Task(subagent_type="codex-executor", prompt=任务1)
- Task(subagent_type="codex-executor", prompt=任务2)

等待批次 1 完成...

批次 2 (并发):
- Task(subagent_type="codex-executor", prompt=任务3)

第六步：执行监控与超时控制

超时检查

执行完成后检查时间偏差：

python ~/.claude/skills/task-dispatcher/scripts/task-logic.py check-timeout <实际秒数> <预估秒数>

超时判定

状态	条件	行动
normal	实际 ≈ 预估 (±50%)	继续
slow	实际 > 预估 2 倍	警告，检查原因
timeout	实际 > 120s	立即终止
abnormal	实际 > 预估 3 倍	终止 + 诊断

超时诊断

当发生超时时，运行诊断：

python ~/.claude/skills/task-dispatcher/scripts/task-logic.py diagnose "任务描述" <实际秒数> <预估秒数>

输出诊断报告，包含：

• 可能原因（读取大目录、任务过大、多文件等）
• 改进建议（拆分任务、限制读取范围、内联代码等）

超时处理流程

执行开始 → 记录开始时间
    │
执行中... → 超过 120s? → 是 → 强制终止
    │           │
执行完成       否
    │           │
检查偏差 ←──────┘
    │
偏差 > 2倍? → 是 → 运行诊断 → 分析原因 → 调整策略
    │
    否
    ↓
继续下一任务

第七步：失败回退

失败类型	策略
编译错误	Codex 重试 + 错误信息
测试失败	Codex 重试 + 失败用例
执行超时	终止 + 诊断 + 拆分任务
时间偏差大	Claude 分析原因，优化 prompt
连续 2 次失败	Claude 接管分析

重试时使用 templates/codex-retry.md 模板。

超时回退策略

当任务超时或时间偏差过大时：

1. 不要重试相同任务 - 重试也会超时
2. 分析根因 - 使用 diagnose 命令
3. 拆分任务 - 将大任务拆成更小的子任务
4. 优化 prompt - 内联代码、限制读取范围
5. Claude 接管 - 如果仍无法解决

委托模板

模板	用途
templates/codex-task.md	标准 Codex 任务
templates/codex-task-optimized.md	优化版（限制读取范围）
templates/codex-retry.md	重试任务
templates/dispatch-report.md	分派报告

Token 优化

默认约束（添加到每个 Codex prompt）：

• 禁止读取 node_modules 目录
• 禁止读取 target、dist、build 目录
• 单次任务读取文件不超过 20 个

优化策略：

• 内联参考代码（不要说「参考 sdk.ts」，直接贴代码）
• 限定文件范围（明确列出路径 + 行号）
• 给出实现骨架

Token 检查

input_tokens	状态	行动
< 500K	✅ 正常	继续
500K - 1M	⚠️ 警告	检查不必要文件
> 1M	🔴 异常	优化 prompt
> 5M	🚨 严重	立即终止

目录结构

task-dispatcher/
├── skill.md                    # 本文件
├── scripts/
│   └── task-logic.py           # 拆分/依赖/验证/时间预估/超时诊断
└── templates/
    ├── codex-task.md           # 标准任务模板
    ├── codex-task-optimized.md # 优化版任务模板
    ├── codex-retry.md          # 重试任务模板
    ├── dispatch-report.md      # 分派报告模板
    └── verification-reference.md # 验证命令参考

脚本命令

命令	说明
should-split <task>	判断是否需要拆分
analyze-deps <json>	分析依赖关系
verify <exit> <stdout>	判断验证是否失败
estimate <task>	预估执行时间
check-timeout <actual> <est>	检查超时状态
diagnose <task> <actual> <est>	诊断超时原因

注意事项

1. 必须预估时间: 分派前必须运行 estimate，超限则拒绝
2. 必须拆分: 预估 > 120s 的任务必须拆分
3. 必须验证: 每个子任务必须有验证命令
4. 优先并发: 无依赖任务必须并发执行
5. 超时即终止: 执行超过 120s 立即终止
6. 偏差即诊断: 时间偏差 > 2 倍必须运行诊断
7. 用户可见: 显示完整分派报告，包含预估时间