用途
ralph-loop 用于执行 Ralph Wiggum 风格的长时运行迭代开发循环，并带有节奏控制。它面向需要多轮迭代的复杂任务，尤其是由许多相互衔接的离散步骤构成、并能从周期性反思中获益的工作。官方说明明确指出，不要将其用于简单的一次性任务或快速修复。
主要能力
- 迭代循环：任务内容保存到 .ralph/<name>.md，每次迭代处理任务并更新该文件，调用 ralph_done 工具进入下一轮迭代。
- 完成与终止：任务完成时输出 <promise>COMPLETE</promise>；循环在完成或达到最大迭代次数时结束，默认最大迭代次数为 50。
- 节奏控制参数：ralph_start 支持 maxIterations（默认 50）、itemsPerIteration（可选，建议每轮处理 N 个条目）、reflectEvery（可选，每 N 次迭代反思一次）、useSubagents（可选，将每个任务委派给子代理）、subagentAgent（可选，子代理名称，默认 'default'）。
- 子代理模式：可将每个清单任务委派给独立的子代理线程。其工作方式为：提取未完成的清单项（- [ ] Task），每个任务委派给一个全新的子代理线程（1 个任务 = 1 个子代理），子代理完成任务并标记为已完成（- [x] Task），主循环负责编排和跟踪进度，并对失败进行自动重试（2 次尝试）。
使用方式
Agent 工具调用示例：
ralph_start({ name: "loop-name", taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2", maxIterations: 50, // Default: 50 itemsPerIteration: 3, // Optional: suggest N items per turn reflectEvery: 10, // Optional: reflect every N iterations useSubagents: true, // Optional: delegate each task to subagent subagentAgent: "default" // Optional: subagent name (default: 'default') })
用户命令：
- /ralph start <name|path> - 启动新循环
- /ralph resume <name> - 恢复循环
- /ralph stop - 暂停循环（当代理空闲时）
- /ralph-stop - 停止活动循环（仅空闲时）
- /ralph status - 显示循环
- /ralph list --archived - 显示已归档循环
- /ralph archive <name> - 将循环移至归档
- /ralph clean [--all] - 清理已完成的循环
- /ralph cancel <name> - 删除循环
- /ralph nuke [--yes] - 删除所有 .ralph 数据
流式传输期间：按 ESC 中断，发送普通消息以恢复，空闲时运行 /ralph-stop 结束循环。
子代理模式启动命令：
/ralph start my-tasks --use-subagents --subagent-agent default
任务文件格式：
Task Title
Brief description.
Goals
- Goal 1
- Goal 2
Checklist
- [ ] Item 1
- [ ] Item 2
- [x] Completed item
Notes
(Update with progress, decisions, blockers)
适用场景
- 需要多次迭代的复杂任务。
- 包含许多相互衔接的离散步骤的任务。
- 能从周期性反思中获益的工作。
- 子代理模式适用于：任务相互独立（无共享状态）、每个任务足够大可以单独执行、希望任务之间清晰隔离、任务列表预先定义明确。
子代理模式的优点包括：每个任务拥有全新上下文（无污染）、隔离执行（失败不会级联）、清晰的任务跟踪与进度报告，适合独立、离散的任务。
限制与最佳实践
- 不适用于简单的一次性任务或快速修复。
- 循环在完成或达到最大迭代次数（默认 50）时结束。
- 暂停与停止命令仅在代理空闲时可用。
- 最佳实践：使用清晰的清单，将工作拆分为离散条目；随时更新，标记完成项并添加备注；遇到困难时进行反思以重新评估方法（普通模式）；仅在真正完成时才输出完成标记；子代理模式用于边界清晰的独立任务。
关于收费、价格、平台支持等具体信息，资料中暂未提供。