Ralph for Claude Code
── 让AI通宵帮你写代码，就像住院医师值夜班
本手册特色 ✅ 通俗易懂：用医疗类比解释技术概念，零基础也能看懂 ✅ 快速上手：3步安装、一条命令启动，10分钟开始自动化开发 ✅ 深入机制：完整解析双重退出检测、断路器等核心原理 ✅ 实战案例：包含医疗APP开发完整流程演示 |
版本：v0.10.0 | 2026年1月
第一章认识Ralph：你的AI编程“住院医师”
1.1 什么是Ralph？
医学类比：理解Ralph 想象一下：你给住院医生写了一份详细的诊疗计划，然后回家睡觉。第二天早上回来，患者的所有检查、用药、护理都已经按计划完成了。Ralph就是这样一个“通宵值班的AI编程医生”——你给它一份项目需求，它就会持续工作，直到项目完成。 |
Ralph的全称是 Ralph for Claude Code，是一个让Claude Code（AI编程助手）能够自主循环工作的框架。它的名字来源于《辛普森一家》的角色Ralph Wiggum——一个虽然经常犯错，但从不放弃的小孩。
1.2 核心特性一览
特性 | 医学类比 | 实际作用 |
自主循环 | 像住院医生持续查房 | 不断迭代直到任务完成 |
智能退出检测 | 像出院评估：多项指标达标才能出院 | 双重条件门控，防止误判 |
速率限制 | 像用药剂量控制 | 100次/小时，防止资源滥用 |
断路器保护 | 像心电监护报警 | 检测异常循环并自动停止 |
实时监控 | 像tmux生命体征监护仪 | 随时查看进度和日志 |
PRD导入 | 像将病历转化为诊疗方案 | 需求文档自动转为任务清单 |
会话连续性 | 像医生交接班 | 保持上下文，避免重复工作 |
第二章快速上手：10分钟开始自动化开发
��核心理念：一次安装，处处可用 Ralph的设计哲学很简单：全局安装一次，然后在任何项目中都可以直接使用。就像你在电脑上安装了Word，之后打开任何文档都能用。 |
2.1 第一阶段：全局安装（仅需一次）
1 | 克隆代码库 从 GitHub 下载 Ralph 的源代码到本地 |
终端命令 git clone https://github.com/frankbria/ralph-claude-code.git cd ralph-claude-code |
终端命令 ralph --help # 如果显示帮助信息，安装成功！ |
✅ 安装后获得的全局命令 ralph - 启动自主开发循环 ralph-monitor - 启动实时监控仪表盘 ralph-setup - 创建新项目 ralph-import - 导入需求文档 ralph-migrate - 迁移旧项目结构 |
2.2 第二阶段：创建项目（每个新项目都需要）
方式A：导入现有需求文档（推荐）
终端命令 # 假设你有一份需求文档 my-requirements.md ralph-import my-requirements.md my-project cd my-project # 启动自动化开发（带监控） ralph --monitor |
方式B：创建空白项目
终端命令 # 创建空白项目 ralph-setup my-awesome-project cd my-awesome-project # 编辑 .ralph/PROMPT.md 文件，写入你的项目需求 # 然后启动 ralph --monitor |
第三章核心机制深度解析
3.1 工作循环原理
医学类比：Ralph的工作流程 想象Ralph是一位住院医生，每天的工作流程是： ① 查看医嘱（读取PROMPT.md） ② 执行诊疗（运行Claude Code） ③ 记录病程（更新任务列表和日志） ④ 评估疗效（检查退出条件） ⑤ 决定下一步（继续治疗或出院） 这个循环会一直重复，直到项目完成或达到限制。 |
步骤 | 操作 | 详细说明 |
① | 读取指令 | 加载 .ralph/PROMPT.md 中的项目需求 |
② | 执行Claude | 调用Claude Code执行当前任务 |
③ | 记录进度 | 更新 .ralph/@fix_plan.md 任务状态 |
④ | 评估完成 | 检查是否满足退出条件（双重门控） |
⑤ | 决定继续 | 未完成则返回步骤①，继续迭代 |
3.2 双重退出检测机制（核心创新）
医学类比：出院评估标准 就像患者出院需要满足多项条件（体温正常、血常规正常、症状消失、医生签字），Ralph的项目也需要满足两个条件才能“出院”： 条件一：完成指标 ≥ 2（从自然语言启发式检测） 条件二：Claude显式确认 EXIT_SIGNAL: true 两个条件必须同时满足，这大大降低了误判风险！ |
完成指标 | EXIT_SIGNAL | 结果 |
≥ 2 | true | ✅ 退出（项目完成） |
≥ 2 | false | ❌ 继续（Claude还在工作） |
≥ 2 | 缺失 | ❌ 继续（默认为false） |
< 2 | true | ❌ 继续（指标未达标） |
3.3 断路器保护机制
⚠️ 医学类比：心电监护报警系统 就像ICU的心电监护仪会在检测到异常时自动报警， Ralph的断路器会在以下情况自动触发： ⚠️ 3次循环无进展（文件未修改） ⚠️ 5次相同错误（重复失败） ⚠️ 输出下降>70%（性能急剧下降） 触发后会自动停止循环，防止无限消耗API资源。 |
第四章实战案例：开发医疗卡路里APP
让我们通过一个完整的例子，看看如何用Ralph开发一个医疗应用。
4.1 准备PRD需求文档
首先，创建一个需求文档calorie-app-prd.md：
calorie-app-prd.md # 每日卡路里追踪器 PRD ## 项目概述 一款通过拍照识别食物并计算卡路里的移动应用。 ## 核心功能 1. 图片上传/拍照 2. AI食物识别 3. 数量输入（个/份/克） 4. 卡路里计算和汇总 5. 每日/每周统计图表 ## 技术栈 - 框架：React Native - 状态管理：Redux Toolkit - 本地存储：SQLite |
4.2 启动自动化开发
终端操作 # 步骤1：导入PRD创建项目 ralph-import calorie-app-prd.md calorie-tracker # 步骤2：进入项目目录 cd calorie-tracker # 步骤3：启动Ralph（带监控） ralph --monitor --calls 80 --timeout 30 # 然后你就可以去睡觉了！ # Ralph会通宵工作，第二天早上回来查看结果 |
4.3 监控开发进度
使用--monitor参数会自动打开tmux分屏界面，实时显示：
监控项 | 说明 |
当前循环次数 | 显示已执行了多少轮迭代 |
API调用统计 | 已使用/总限制（如 45/100） |
最新日志 | 实时滚动显示执行日志 |
任务进度 | 当前正在处理的任务 |
断路器状态 | 正常/半开/断开 |
tmux常用操作 Ctrl+B 然后 D - 分离会话（Ralph继续运行，你可以关闭终端） tmux attach - 重新连接查看进度 Ctrl+B 然后 ←/→ - 切换窗格 |
第五章命令速查表
5.1 安装与卸载
命令 | 说明 |
./install.sh | 全局安装Ralph |
./uninstall.sh | 完全卸载Ralph |
ralph-migrate | 迁移旧项目到新结构 |
5.2 项目操作
命令 | 说明 |
ralph-setup <项目名> | 创建新的空白项目 |
ralph-import <文档> <项目名> | 导入PRD创建项目 |
ralph | 启动自主开发循环 |
ralph --monitor | 启动并打开tmux监控（推荐） |
ralph --status | 查看当前状态 |
5.3 高级配置
参数 | 说明 |
--calls N | 限制每小时API调用次数（默认100） |
--timeout M | 设置执行超时分钟数（默认15） |
--verbose | 显示详细进度信息 |
--no-continue | 禁用会话连续性（每次重新开始） |
--reset-session | 手动重置会话状态 |
--reset-circuit | 重置断路器 |
--prompt FILE | 使用自定义提示文件 |
第六章常见问题解答
Q1: Ralph运行中突然停止了？
可能的原因 ① 达到API速率限制（等待倒计时后自动继续） ② 触发了断路器（检查是否有重复错误） ③ 达到Claude的5小时使用限制（等待60分钟或选择退出） ④ 项目已完成（检查.ralph/@fix_plan.md） |
Q2: 如何知道项目进度？
终端命令 # 查看状态 ralph --status # 或者查看任务列表 cat .ralph/@fix_plan.md # 查看日志 tail -f .ralph/logs/ralph.log |
Q3: 可以通宵运行吗？
✅ 完全可以！ 这正是Ralph的设计目的。推荐步骤： 1. 使用 ralph --monitor 启动 2. 按 Ctrl+B 然后 D 分离tmux会话 3. 关闭终端去睡觉 4. 第二天用 tmux attach 查看结果 为了安全，建议在Docker容器中运行。 |
Q4: 如何限制API成本？
终端命令 # 限制每小时最多50次调用 ralph --calls 50 # 结合超时设置 ralph --calls 50 --timeout 20 |
附录项目文件结构
项目结构 my-project/ ├── .ralph/ # Ralph配置和状态（隐藏文件夹） │ ├── PROMPT.md # 主开发指令（核心文件） │ ├── @fix_plan.md # 优先级任务列表 │ ├── @AGENT.md # 构建和运行指令 │ ├── specs/ # 项目规格和需求 │ ├── examples/ # 使用示例 │ ├── logs/ # 执行日志 │ └── docs/generated/ # 自动生成的文档 └── src/ # 源代码（在项目根目录） |
学习资源 • 官方仓库：https://github.com/frankbria/ralph-claude-code • 版本号：v0.10.0 | 测试用例：308个 | 通过率：100% • 系统要求：Bash 4.0+, Claude Code CLI, tmux, jq, Git |
