夜雨聆风什么是 ralph-loop？
ralph-loop 是 Claude Code 的官方插件（原名 ralph-wiggum，后因版权原因更名），本质上是一个自动迭代循环系统——让 AI 在完成工作后不退出，而是重新读取任务并继续优化，直到任务真正完成。
它的名字来源于《辛普森一家》中那个天真执着、撞了南墙也不回头的小警察 Ralph Wiggum。正如这个角色一样，这个插件让 AI 不知疲倦地干活——你说“写一个登录功能”，它不但写出代码，还会跑测试、发现报错、自己修 bug、再测试、再修……周而复始，直到满足你设定的目标为止。
它在技术社区中的定义极其简单粗暴：Ralph is a Bash loop。其实就是让 AI 反复执行同一个任务，但每次都是带着前面迭代的“经验”继续干。
为什么需要它
传统的 AI 编程工具有一个通病：“交差心态”。你让 Claude 重构一个 20 个文件的前端项目，它会告诉你“改了 3 个文件，测试有几个报错，剩下的你手动处理一下呗”。它认为“差不多就行”，但你得自己收拾烂摊子。
ralph-loop 专门解决这个问题——它就像给 AI 配了一个不知疲倦的监工，一旦任务没完成，就把它按回去继续干，直到任务真正被满足。
核心原理：Stop Hook
ralph-loop 背后只有十几行核心代码。它利用 Claude Code 的 Stop Hook 机制——当 Claude 尝试退出时，这个钩子自动触发，检查是否达到了预设的完成条件。
具体流程是这样的：
1. 你运行 /ralph-loop "任务描述" --completion-promise "COMPLETE" --max-iterations 30
2. Claude 开始执行任务，修改文件、运行测试
3. 当 Claude 认为“完事了”并试图退出时，Stop Hook 拦截退出请求
4. Hook 检查最后一条输出中是否包含指定的 --completion-promise 字符串（比如 "COMPLETE"）
5. 如果没有包含，Hook 将原始任务描述重新注入回会话，Claude 看到自己之前的产出（代码、测试日志、报错信息）继续迭代
6. 重复步骤 2-5，直到看到 "COMPLETE" 或达到 --max-iterations 上限
每次迭代的任务描述完全相同，但世界变了——文件被修改了、测试通过了部分、错误日志被捕获了。AI 通过这些反馈自我迭代，不需要你不停地告诉它“这个不对、再修一下”。
安装方法
在 Claude Code 终端中执行：
```bash
/plugin install ralph-loop@claude-plugins-official
```
安装后退出会话重新打开即可生效。启动循环使用：
```bash
/ralph-loop "你的任务描述" --completion-promise "通关密语" --max-iterations 30
```
强制停止循环使用 /cancel-ralph。
⚠️ 重要安全提示：--completion-promise 是字符串精确匹配，不是语义理解，必须严格一致。例如任务描述中约定输出 "
实战案例
案例 1：AI 盲扫代码 Bug（“不知道代码有没有问题，让 AI 自己循环排查”）
场景描述：你接手了一段别人写的遗留代码，功能看起来正常，但总感觉哪里不对劲，又没有明显的测试失败可以指出具体问题。你想让 AI 自己去“盲扫”——让它反复运行、反复报错、反复修复，把所有潜在的 bug 全部铲掉，而你不需要一步步告诉它哪里错了。
命令示例：
```bash
/ralph-loop "
我有一份旧代码在 src/legacy/ 目录下，可能有不少隐藏 bug。
请：
1. 扫描整个目录，识别潜在问题（空指针、类型错误、资源泄露、边界条件、竞态条件）
2. 针对每个可疑点编写单元测试来验证
3. 运行测试，根据失败结果修复代码
4. 修复后重新运行测试
5. 重复这个过程，直到所有编写的新测试都通过
完成标准：
- 新增测试覆盖率 > 80%
- 没有遗留的 ESLint 警告
- 所有新增测试都通过
完成后输出：
" --completion-promise "ALL_BUGS_FIXED" --max-iterations 50
```
实际运行流程：
· 第 1 轮：AI 分析代码，判断可能存在 7 个潜在问题，写了 4 个单元测试，其中 3 个失败、1 个通过。
· 第 2 轮：读取失败的测试报告，修复了第一个问题（一个空指针隐患），重新运行测试，2 个依然失败。
· 第 3 轮：修复第二个问题（一个数组越界 bug），测试通过数变成 3。
· 第 4 轮：修复了第三个问题（一个 SQL 拼接漏洞）。
· 第 5 轮：发现还有额外 2 个潜在风险，补充了测试，全部通过。
· ...直至第 8 轮：AI 输出
核心价值：你不需要知道 bug 具体在哪里，AI 自己“运行 → 出错 → 分析 → 修改 → 再运行”，直到把所有坑都踩一遍并填平。这正是 Ralph Loop 解决的核心痛点：确定性的失败优于不确定性的成功——只要报错信息准确，AI 就能在循环里通过自我调试把代码修好。
案例 2：自动化测试驱动开发（TDD）
场景描述：你想实现一个新功能（比如“用户注册并发送欢迎邮件”），但希望代码质量有保障——必须有充分的测试覆盖，而不是能跑就行就了事。让 AI 用 TDD 的方式从头开发：先写测试，再写代码，跑测试、失败、再修、再跑……
命令示例：
```bash
/ralph-loop "
实现用户注册功能，邮箱验证+发送欢迎邮件。
遵循 TDD 流程：
阶段1：编写失败测试
阶段2：实现最小代码让测试通过
阶段3：运行全量测试
阶段4：若失败则修复
阶段5：重构优化
阶段6：重复阶段3-5直到全绿
完成标准：
- 单元测试覆盖率 ≥ 85%
- 集成测试全部通过
- 无 ESLint/TypeScript 报错
完成后输出：
" --completion-promise "TDD_COMPLETE" --max-iterations 40
```
核心价值：AI 自己写了测试、自己跑、自己红转绿、自己重构——整个过程你完全可以放着不管，等它输出 TDD_COMPLETE 时，代码和测试都齐了。
案例 3：过夜跑完整项目重构
场景描述：你的项目有 30 个组件、几百个文件，想把它们从前端旧代码风格全部迁移到 TypeScript，还要求测试全部通过。这个工作量手工做需要好几个通宵，但让 ralph-loop 在你睡觉时跑，醒来直接验收成果。
命令示例：
```bash
/ralph-loop "
读取 codebase/ 下的所有 React 项目文件：
阶段1：识别所有 .js/.jsx 文件，将其转换为 .ts/.tsx
阶段2：补充缺失的 TypeScript 类型定义
阶段3：修复由此产生的类型错误
阶段4：运行完整测试套件
阶段5：修复全部测试失败
阶段6：重复阶段4-5直到所有测试通过
完成标准：
- 全量测试通过率 100%
- TypeScript 编译无错误
- 无运行时崩溃
完成后输出：
" --completion-promise "REFACTOR_COMPLETE" --max-iterations 100
```
实际数据：类似场景中，曾有 Y Combinator 黑客马拉松团队一夜之间让 AI 生成了 6 个完整的代码仓库。还有一个真实外包合同案例，原本报价 297** 的 API 成本就完成了验收。
使用这种方法时建议设置较大的 max-iterations（如 100），在关键迭代节点阶段性查看进度或手动确认检查点是否符合预期，避免错误方向被无限放大。
什么时候用 vs 什么时候不用
✅ 适合 ❌ 不适合
有明确验证标准（测试、Lint、类型检查） 需要人类主观判断的设计决策（比如 UI 配色方案）
全新功能开发或代码重构 没有明确“做完”标准的任务（如“写一段优雅的代码”）
Bug 自动修复循环 Token 预算敏感的项目（循环会消耗更多 token，但节省的是你的时间）
过夜批量处理 对代码改动控制极严的生产环境（建议先在独立分支上跑）
避坑指南
1. 一定要设 --max-iterations——这是防止 token 烧光的保命符。
2. completion-promise 必须精确匹配——如果任务描述说输出 "
3. 任务描述必须包含明确的完成标准——越是模糊，AI 越可能早早上交不合格作业。
---
ralph-loop 本质上是一个思想：用确定性失败代替不确定性的成功。它把 AI 从“你问一句我答一句”的聊天工具，变成了一个能自己和自己较劲、直到把活儿干完的自动化开发者。虽然 token 消耗更高，但在复杂任务面前，省下来的时间和精力往往更加宝贵。
