| 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 时：
- 拒绝分派，不调用 Codex
- 分析原因：多文件？多操作？范围过大？
- 要求拆分：将任务拆分为更小的子任务
- 重新预估：确保每个子任务 ≤ 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 模板。
超时回退策略
当任务超时或时间偏差过大时：
- 不要重试相同任务 - 重试也会超时
- 分析根因 - 使用 diagnose 命令
- 拆分任务 - 将大任务拆成更小的子任务
- 优化 prompt - 内联代码、限制读取范围
- 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> | 诊断超时原因 |
注意事项
- 必须预估时间: 分派前必须运行 estimate，超限则拒绝
- 必须拆分: 预估 > 120s 的任务必须拆分
- 必须验证: 每个子任务必须有验证命令
- 优先并发: 无依赖任务必须并发执行
- 超时即终止: 执行超过 120s 立即终止
- 偏差即诊断: 时间偏差 > 2 倍必须运行诊断
- 用户可见: 显示完整分派报告，包含预估时间
