task-batch - Autonomous Batch Task Execution (v2.88)
持续自主执行任务列表，包括prd解析、自动任务分解和完成验证。运行直到所有任务达到VERIFIED_DONE或发生重大故障。
基于以下研究：
- Sugar - 24/7自主AI编码代理层
- Daedalus/Talos - 具有依赖关系解析的任务队列守护进程
- Continuous Autonomous Task Loop Pattern
- claude-queue - 基于优先级的任务排队
快速开始
# 从prd文件
/task-batch docs/prd/feature-x.prq.md
# 从任务列表文件
/task-batch tasks/sprint-backlog.md
# 内联任务（分号分隔）
/task-batch "Add authentication; Implement user profile; Add password reset"
# 带优先级排序
/task-batch tasks/features.md --priority
# 与特定队友
/task-batch tasks/backend.md --teammates coder,reviewer,tester
核心设计原则
1. 持续自主执行
- 无需用户交互直到所有任务完成（除非发生关键故障）
- 每个任务都有新的上下文 - 每个任务都从干净的上下文开始，以避免污染
- 自动提交在每个VERIFIED_DONE任务之后
- 智能处理速率限制 - 指数退避，具有可配置的延迟
2. 停止条件
| 条件 | 动作 |
|---|---|
| 所有任务VERIFIED_DONE | 停止 - 输出摘要，删除团队 |
| 没有网络连接 | 停止 - 报告错误，保存状态 |
| 令牌限制达到 | 停止 - 保存进度，报告位置 |
| 系统崩溃/错误 | 停止 - 紧急保存，报告诊断 |
| 达到最大迭代次数 | 失败 - 严重错误：这表明无限循环，报告所有未完成任务 |
| 退出时剩余任务 | 失败 - 严重错误：除非发生严重故障，否则不要退出，除非有待办任务 |
| 正常用户问题 | 继续 - 在批次末尾排队响应 |
⚠️ 重要规则：没有部分成功
技能绝不能报告未完成任务的成功。
❌ 错误："完成了10个中的17个任务" → 摘要 → 退出0
✅ 正确："完成了10个中的17个任务" → 继续执行，直到所有17个完成
✅ 正确："由于[严重故障]无法继续" → 报告错误 → 退出1
如果无法继续执行（被阻塞的依赖项，严重故障），技能必须：
- 报告明确的失败状态
- 列出所有未完成任务及其原因
- 用非零代码退出
- 保存状态以手动恢复
3. 任务执行模型（多个任务）
关键：这项技能处理多个任务，不仅仅是一个任务。
+------------------------------------------------------------------+
| TASK-BATCH EXECUTION MODEL |
| (MULTIPLE TASKS - DEFAULT MODE) |
+------------------------------------------------------------------+
| |
| +----------+ +-------------+ +----------------+ |
| | PARSE |--->| PRIORITIZE |--->| DECOMPOSE | |
| | Input | | (optional) | | Complex Tasks | |
| +----------+ +-------------+ +-------+--------+ |
| | |
| +------------------------------------------v---------------+ |
| | TASK QUEUE (N TASKS) | |
| | | |
| | [Task1] [Task2] [Task3] [Task4] [TaskN] | |
| | Criteria Criteria Criteria Criteria Criteria | |
| | ✅ ✓✓✓ ✅ ✓✓✓ ⏳ ... ⏳ ... ⏳ ... | |
| +---------------------------+-------------------------------+ |
| | |
| +---------------------------v-------------------------------+ |
| | EXECUTION LOOP (FOR EACH TASK) | |
| | | |
| | FOR EACH task IN task_queue: | |
| | +--------+ +------------+ +---------------+ | |
| | | VALIDATE|-->| ORCHESTRATE|-->|CHECK CRITERIA| | |
| | | Criteria| | (10-step) | | (ALL must ✓) | |
| | +--------+ +------------+ +-------+-------+ | |
| | | | |
| | ALL MET? <--YES--NO--> | |
| | | RETRY | |
| | v | |
| | +---------------+ | |
| | | VERIFIED_DONE | | |
| | | + NEXT TASK | | |
| | +---------------+ | |
| +------------------------------------------------------------+ |
+------------------------------------------------------------------+ |
| | YES<--+-->NO | |
| | | | | |
| | +--------------+ | | |
| | v v | |
| | +-----------+ +------------+ | |
| | | AUTO-COMMIT| | RETRY | | |
| | | + NEXT | | (max 3) | | |
| | +-----------+ +------------+ | |
| | | |
| +------------------------------------------------------------+ |
| |
+------------------------------------------------------------------+
输入格式
1. PRD文件格式（.prq.md或.md）
# 功能：用户认证
## 优先级：高
## 概述
实现带有Google提供商的OAuth2认证。
## 任务
- [ ] P1：创建OAuth2服务模块
- [ ] P1：添加Google OAuth提供商配置
- [ ] P2：实现登录回调处理程序
- [ ] P2：添加会话管理
- [ ] P3：创建认证中间件
- [ ] P3：编写单元测试
## 依赖项
- P2任务依赖于P1任务的完成
## 验收标准
- 用户可以使用Google登录
- 会话持续7天
- 所有测试通过
2. 任务列表格式
# 冲刺积压 - 第12周
## 后端任务
1. [P1] 使用Redis实现速率限制
2. [P1] 为所有端点添加输入验证
3. [P2] 使用OpenAPI创建API文档
4. [P2] 添加请求日志中间件
## 前端任务
5. [P1] 修复登录表单验证
6. [P2] 为按钮添加加载状态
7. [P3] 实现暗模式切换
3. 内联任务
/task-batch "添加用户模式；创建CRUD端点；添加验证"
4. JSON任务文件
{
"batch_name": "auth-feature",
"tasks": [
{
"id": "auth-001",
"description": "创建OAuth2服务",
"priority": 1,
"dependencies": [],
"acceptance_criteria": ["模块存在", "导出配置客户端"]
},
{
"id": "auth-002",
"description": "添加Google提供商",
"priority": 1,
"dependencies": ["auth-001"],
"acceptance_criteria": ["Google OAuth配置", "测试通过"]
}
],
"config": {
"max_retries": 3,
"auto_commit": true,
"stop_on_failure": false
}
}
执行工作流
第1阶段：解析
将输入解析为结构化任务列表：
# 解析逻辑
输入类型检测：
- .prq.md或.md结尾→ PRD解析器
- .json结尾→ JSON解析器
- tasks/目录→ 多文件解析器
- 内联文本→ 内联解析器
任务提取：
- 提取任务描述
- 解析优先级标记（P1/P2/P3或HIGH/MEDIUM/LOW）
- 识别依赖项
- 提取验收标准
第2阶段：优先级排序（可选）
当设置--priority标志时：
优先级规则：
1. 显式优先级标记（P1 > P2 > P3）
2. 依赖项顺序（首先依赖项）
3. 文件顺序（如输入中列出）
4. 估计工作量（当优先级相同时，较小的任务优先）
第3阶段：分解
对于复杂度>6的任务：
分解规则：
- 如果任务有多个交付物
- 任务跨越多个文件
- 任务需要不同的专业知识
- 创建子任务依赖项
- 保留原始验收标准
第4阶段：执行（主循环）
# 执行循环的伪代码
task_queue = parse_and_prioritize(input)
completed_tasks = []
failed_tasks = []
iteration = 0
max_iterations = len(task_queue) * 5 # 安全限制
while task_queue and iteration < max_iterations:
# 速率限制检查
if rate_limit_detected():
sleep(exponential_backoff())
continue
# 选择下一个任务（尊重依赖项）
task = select_next_task(task_queue, completed_tasks)
if task is None:
# 所有剩余任务被阻塞 - 这是一个失败
blocked_tasks = identify_blocked_reasons(task_queue, completed_tasks)
report_failure("BLOCKED", blocked_tasks)
exit 1 # 失败 - 无法继续
# 每个任务都有新的上下文（通过新子代理）
result = execute_with_orchestrator(task)
if result == VERIFIED_DONE:
completed_tasks.append(task)
task_queue.remove(task)
auto_commit(task)
# 更新依赖任务
update_dependencies(task_queue, task)
else:
if task.retry_count < MAX_RETRIES:
task.retry_count += 1
# 重新排队反馈
task.feedback = result.errors
else:
failed_tasks.append(task)
# 不要中断 - 继续处理剩余任务
# 除非明确设置stop_on_failure
if config.stop_on_failure:
break
iteration++
# ══════════════════════════════════════════════════════════════════
# 关键：最终验证 - 不允许部分成功
# ══════════════════════════════════════════════════════════════════
if len(task_queue) > 0:
# 仍然有待处理的任务 - 这是一个失败
print("❌ BATCH FAILED: Incomplete tasks remain")
print(f" Completed: {len(completed_tasks)}")
print(f" Pending: {len(task_queue)}")
print(f" Failed: {len(failed_tasks)}")
for task in task_queue:
print(f" - {task.id}: {task.description}")
exit 1 # 明确失败
if len(failed_tasks) > 0:
# 一些任务在最大重试后失败
print("❌ BATCH FAILED: Tasks exceeded max retries")
for task in failed_tasks:
print(f" - {task.id}: {task.description}")
print(f" Error: {task.last_error}")
exit 1 # 明确失败
# 所有任务成功完成
output_summary(completed_tasks, [])
exit 0 # 成功
第5阶段：报告
摘要输出：
- 总任务数：N
- 完成：M
- 失败：X
- 跳过：Y（被失败阻塞）
- 对于每个任务：
- 状态：VERIFIED_DONE | FAILED | SKIPPED
- 持续时间：XX分钟
- 修改的文件：[列表]
- 提交：[sha1, sha2, ...]
- 对于失败的任务：
- 错误详情
- 重试尝试
- 建议的修复措施
团队协调（代理团队）
团队创建
# 在技能调用时自动创建
TeamCreate:
team_name: "task-batch-{timestamp}"
description: "批次执行：{batch_name}"
agent_type: "orchestrator"
任务分配
# 在共享列表中创建任务
TaskCreate:
subject: "{task_description}"
description: "{full_task_details}"
activeForm: "执行中：{task_description}"
metadata:
priority: "{priority}"
dependencies: ["{dep_task_ids}"]
acceptance_criteria: ["{criteria}"]
# 分配给适当的队友
TaskUpdate:
taskId: "{id}"
owner: "ralph-coder" # 或ralph-reviewer, ralph-tester
队友生成
# 根据任务类型生成队友
Task:
subagent_type: "ralph-coder"
team_name: "task-batch-{timestamp}"
name: "batch-coder"
prompt: |
执行任务：{task_description}
验收标准：
{acceptance_criteria}
上下文：新的执行，没有先前的上下文。
执行直到VERIFIED_DONE或最大重试次数达到。
钩子集成
| 钩子 | 目的 | 退出2行为 |
|---|---|---|
teammate-idle-quality-gate.sh |
空闲前的质量检查 | 用反馈继续工作 |
task-completed-quality-gate.sh |
完成前验证 | 防止完成，重试 |
ralph-subagent-start.sh |
加载Ralph上下文 | - |
batch-progress-tracker.sh |
跟踪批次进度 | 如果任务仍然存在，则继续 |
进度跟踪
# 进度文件：.ralph/batch/{batch_id}/progress.json
{
"batch_id": "batch-20260215-123456",
"started": "2026-02-15T12:00:00Z",
"total_tasks": 10,
"completed": 5,
"failed": 1,
"current_task": "auth-006",
"estimated_completion": "2026-02-15T14:30:00Z"
}
错误处理
速率限制处理
速率限制检测：
- API响应：429太多请求
- 错误消息包含"速率限制"
- 超时超过
恢复：
- 初始退避：60秒
- 最大退避：300秒（5分钟）
- 退避乘数：2x
- 最大重试次数：5
在最大重试次数超过时：
- 保存状态
- 报告错误
- 停止批次执行
任务失败处理
任务失败选项：
stop_on_failure: false # 继续处理剩余任务
stop_on_failure: true # 停止整个批次
失败恢复：
1. 记录错误详情
2. 捕获当前状态
3. 如果retry_count < MAX_RETRIES：
- 向任务添加反馈
- 重新排队重试
4. 否则：
- 标记为FAILED
- 跳过依赖任务
关键故障检测
关键故障（立即停止）：
- 无网络连接（ping失败）
- 令牌限制达到（>95%上下文使用）
- 系统崩溃（未处理异常）
- 认证失败
- 仓库损坏
非关键故障（继续）：
- 单个任务失败（如果stop_on_failure=false）
- 测试失败（触发重试）
- 语法检查错误（触发重试）
- 类型错误（触发重试）
CLI命令
# 基本批次执行
ralph batch tasks/features.md
# 带优先级排序
ralph batch tasks/sprint.md --priority
# 首次失败即停止
ralph batch tasks/critical.md --stop-on-failure
# 恢复中断的批次
ralph batch --resume batch-20260215-123456
# 检查批次状态
ralph batch --status batch-20260215-123456
# 列出运行中的批次
ralph batch --list
# 取消运行中的批次
ralph batch --cancel batch-20260215-123456
配置
默认配置
# ~/.ralph/config/batch.yaml
batch:
max_iterations_multiplier: 5 # max_iter = task_count * multiplier
max_retries_per_task: 3
auto_commit: true
stop_on_failure: false
priority_enabled: false
rate_limits:
initial_backoff_seconds: 60
max_backoff_seconds: 300
backoff_multiplier: 2
max_retries: 5
teammates:
default: [coder, reviewer]
complex: [coder, reviewer, tester]
critical: [coder, reviewer, tester, security]
hooks:
progress_tracking: true
quality_gates: true
每批次覆盖
# 在任务文件前置内容
---
batch:
max_retries: 5
stop_on_failure: true
teammates: [coder, tester]
---
完成标准
VERIFIED_DONE（每个任务）
每个任务需要全部：
- 实现完成
- 正确性通过（语法，逻辑）
- 质量通过（类型，语法检查）
- 安全性通过（无漏洞）
- 验收标准验证
- 自动提交成功
BATCH_COMPLETE（完整批次）
需要全部：
- 所有任务已处理（VERIFIED_DONE或FAILED）
- 摘要报告生成
- Git历史记录清晰（每个任务都有提交）
- 团队已删除
- 进度文件已归档
反模式
- NEVER 因非关键用户问题而停止（将它们排队）
- NEVER 使用无限循环（总是设置max_iterations）
- NEVER 跳过质量门（这会破坏VERIFIED_DONE）
- NEVER 在任务之间共享上下文（污染风险）
- NEVER 忽略速率限制（会导致失败）
- NEVER 在没有VERIFIED_DONE的情况下提交（不完整的工作）
- ⚠️ 重要：NEVER报告未完成任务的成功
"部分成功"反模式
❌ 错误行为：
输出："完成任务（10个中的17个）"
输出："剩余任务（7个）"
动作：退出0（成功）
✅ 正确行为：
选项A：继续执行直到所有17个任务完成
选项B：如果不能继续：
输出："❌ BATCH FAILED: Cannot continue"
输出："完成：10, 待办：7, 失败：0"
输出："原因：[被阻塞的依赖项 | 关键错误 | 令牌限制]"
退出：1（失败）
如果你发现自己即将输出带有剩余任务的摘要：
- 停止 - 不要输出成功
- 要么继续执行，要么报告明确的失败
- 部分完成=失败，不是成功
比较：/task-batch vs /orchestrator vs /loop
| 功能 | /task-batch | /orchestrator | /loop |
|---|---|---|---|
| 输入 | 多个任务 | 单个任务 | 单个任务 |
| 执行 | 直到全部完成 | 单个工作流 | 迭代细化 |
| 用户交互 | 最小（仅关键） | 完全澄清 | 迭代提示 |
| 停止条件 | 全部完成或关键故障 | VERIFIED_DONE | VERIFIED_DONE或最大迭代 |
| 任务分解 | 自动 | 手动（在计划中） | N/A |
| PRD支持 | 本机 | 通过澄清 | N/A |
| 优先级排序 | 是 | 否 | 否 |
| 最佳用途 | 批量功能，PRD执行 | 复杂单个任务 | 质量细化 |
代理团队集成（v2.88）
最佳场景：集成（代理团队+自定义子代理）
为什么这个技能选择场景C
- 批量协调需要跨队友跟踪多个任务
- 质量门对每个任务的VERIFIED_DONE至关重要
- 专业代理（ralph-coder, ralph-reviewer, ralph-tester）用于不同类型的任务
- 共享任务列表支持依赖管理和进度跟踪
- 持续执行受益于团队协调，无需用户干预
配置
- TeamCreate：在调用时创建团队"task-batch-{batch-id}"
- TaskCreate：为批次中的每个项目创建任务
- 生成：使用ralph-coder进行实现，ralph-reviewer进行验证
- 钩子：TeammateIdle + TaskCompleted进行质量验证
- 协调：共享任务列表位于~/.claude/tasks/task-batch-{id}/
VERIFIED_DONE保证与钩子
| 钩子 | 事件 | 目的 |
|---|---|---|
teammate-idle-quality-gate.sh |
TeammateIdle | 防止任务剩余时空闲 |
task-completed-quality-gate.sh |
TaskCompleted | 在标记为完成之前验证任务 |
ralph-subagent-stop.sh |
SubagentStop | 当队友停止时的质量门 |
batch-progress-tracker.sh |
PostToolUse | 更新批次进度文件 |
退出2行为：钩子返回退出2以强制继续，当：
- 队列中仍有更多任务
- 质量门失败但重试可用
- 依赖任务尚未完成
相关技能
/orchestrator- 基础10步工作流（内部使用）/loop- 迭代细化模式/gates- 质量验证门/clarify- 需求澄清（用于PRD解析）/retrospective- 批次后分析
行动报告（v2.93.0）
这项技能生成完整的自动报告用于可追溯性：
自动报告
当这项技能完成后，会自动生成：
- 在Claude对话中：可见结果
- 在仓库中：
docs/actions/task-batch/{timestamp}.md - 元数据JSON：
.claude/metadata/actions/task-batch/{timestamp}.json
报告内容
每个报告包括：
- ✅ 摘要：执行的任务描述
- ✅ 执行细节：持续时间，迭代次数，修改的文件
- ✅ 结果：发现的错误，建议
- ✅ 下一步：建议的后续行动
查看先前报告
# 列出这项技能的所有报告
ls -lt docs/actions/task-batch/
# 查看最新的报告
cat $(ls -t docs/actions/task-batch/*.md | head -1)
# 搜索失败的报告
grep -l "Status: FAILED" docs/actions/task-batch/*.md
手动生成（可选）
source .claude/lib/action-report-lib.sh
start_action_report "task-batch" "任务描述"
# ...执行...
complete_action_report "success" "摘要" "建议"
系统参考
-
Action Reports System - 完整文档
-
action-report-lib.sh - 辅助库