本手册特色

✅ 通俗易懂：用医疗类比解释技术概念，零基础也能看懂

✅ 快速上手：3步安装、一条命令启动，10分钟开始自动化开发

✅ 深入机制：完整解析双重退出检测、断路器等核心原理

✅ 实战案例：包含医疗APP开发完整流程演示

医学类比：理解Ralph

想象一下：你给住院医生写了一份详细的诊疗计划，然后回家睡觉。第二天早上回来，患者的所有检查、用药、护理都已经按计划完成了。Ralph就是这样一个“通宵值班的AI编程医生”——你给它一份项目需求，它就会持续工作，直到项目完成。

特性

医学类比

实际作用

自主循环

像住院医生持续查房

不断迭代直到任务完成

智能退出检测

像出院评估：多项指标达标才能出院

双重条件门控，防止误判

速率限制

像用药剂量控制

100次/小时，防止资源滥用

断路器保护

像心电监护报警

检测异常循环并自动停止

实时监控

像tmux生命体征监护仪

随时查看进度和日志

PRD导入

像将病历转化为诊疗方案

需求文档自动转为任务清单

会话连续性

像医生交接班

保持上下文，避免重复工作

��核心理念：一次安装，处处可用

Ralph的设计哲学很简单：全局安装一次，然后在任何项目中都可以直接使用。就像你在电脑上安装了Word，之后打开任何文档都能用。

1

克隆代码库

从 GitHub 下载 Ralph 的源代码到本地

终端命令

git clone https://github.com/frankbria/ralph-claude-code.git

cd ralph-claude-code

2

运行安装脚本

执行安装程序，自动配置全局命令

终端命令

./install.sh

3

验证安装成功

检查是否可以调用 ralph 命令

终端命令

ralph --help

# 如果显示帮助信息，安装成功！

✅ 安装后获得的全局命令

ralph - 启动自主开发循环 ralph-monitor - 启动实时监控仪表盘 ralph-setup - 创建新项目 ralph-import - 导入需求文档 ralph-migrate - 迁移旧项目结构

终端命令

# 假设你有一份需求文档 my-requirements.md

ralph-import my-requirements.md my-project

cd my-project

# 启动自动化开发（带监控）

ralph --monitor

终端命令

# 创建空白项目

ralph-setup my-awesome-project

cd my-awesome-project

# 编辑 .ralph/PROMPT.md 文件，写入你的项目需求

# 然后启动

ralph --monitor

医学类比：Ralph的工作流程

想象Ralph是一位住院医生，每天的工作流程是：  ① 查看医嘱（读取PROMPT.md） ② 执行诊疗（运行Claude Code） ③ 记录病程（更新任务列表和日志） ④ 评估疗效（检查退出条件） ⑤ 决定下一步（继续治疗或出院）  这个循环会一直重复，直到项目完成或达到限制。

步骤

操作

详细说明

①

读取指令

加载 .ralph/PROMPT.md 中的项目需求

②

执行Claude

调用Claude Code执行当前任务

③

记录进度

更新 .ralph/@fix_plan.md 任务状态

④

评估完成

检查是否满足退出条件（双重门控）

⑤

决定继续

未完成则返回步骤①，继续迭代

医学类比：出院评估标准

就像患者出院需要满足多项条件（体温正常、血常规正常、症状消失、医生签字），Ralph的项目也需要满足两个条件才能“出院”：  条件一：完成指标 ≥ 2（从自然语言启发式检测） 条件二：Claude显式确认 EXIT_SIGNAL: true  两个条件必须同时满足，这大大降低了误判风险！

完成指标

EXIT_SIGNAL

结果

≥ 2

true

✅ 退出（项目完成）

≥ 2

false

❌ 继续（Claude还在工作）

≥ 2

缺失

❌ 继续（默认为false）

< 2

true

❌ 继续（指标未达标）

⚠️ 医学类比：心电监护报警系统

就像ICU的心电监护仪会在检测到异常时自动报警，  Ralph的断路器会在以下情况自动触发：  ⚠️ 3次循环无进展（文件未修改） ⚠️ 5次相同错误（重复失败） ⚠️ 输出下降>70%（性能急剧下降）  触发后会自动停止循环，防止无限消耗API资源。

calorie-app-prd.md

# 每日卡路里追踪器 PRD

## 项目概述

一款通过拍照识别食物并计算卡路里的移动应用。

## 核心功能

1. 图片上传/拍照

2. AI食物识别

3. 数量输入（个/份/克）

4. 卡路里计算和汇总

5. 每日/每周统计图表

## 技术栈

- 框架：React Native

- 状态管理：Redux Toolkit

- 本地存储：SQLite

终端操作

# 步骤1：导入PRD创建项目

ralph-import calorie-app-prd.md calorie-tracker

# 步骤2：进入项目目录

cd calorie-tracker

# 步骤3：启动Ralph（带监控）

ralph --monitor --calls 80 --timeout 30

# 然后你就可以去睡觉了！

# Ralph会通宵工作，第二天早上回来查看结果

监控项

说明

当前循环次数

显示已执行了多少轮迭代

API调用统计

已使用/总限制（如 45/100）

最新日志

实时滚动显示执行日志

任务进度

当前正在处理的任务

断路器状态

正常/半开/断开

 tmux常用操作

Ctrl+B 然后 D - 分离会话（Ralph继续运行，你可以关闭终端） tmux attach - 重新连接查看进度 Ctrl+B 然后 ←/→ - 切换窗格

命令

说明

./install.sh

全局安装Ralph

./uninstall.sh

完全卸载Ralph

ralph-migrate

迁移旧项目到新结构

命令

说明

ralph-setup <项目名>

创建新的空白项目

ralph-import <文档> <项目名>

导入PRD创建项目

ralph

启动自主开发循环

ralph --monitor

启动并打开tmux监控（推荐）

ralph --status

查看当前状态

参数

说明

--calls N

限制每小时API调用次数（默认100）

--timeout M

设置执行超时分钟数（默认15）

--verbose

显示详细进度信息

--no-continue

禁用会话连续性（每次重新开始）

--reset-session

手动重置会话状态

--reset-circuit

重置断路器

--prompt FILE

使用自定义提示文件

可能的原因

① 达到API速率限制（等待倒计时后自动继续） ② 触发了断路器（检查是否有重复错误） ③ 达到Claude的5小时使用限制（等待60分钟或选择退出） ④ 项目已完成（检查.ralph/@fix_plan.md）

终端命令

# 查看状态

ralph --status

# 或者查看任务列表

cat .ralph/@fix_plan.md

# 查看日志

tail -f .ralph/logs/ralph.log

✅ 完全可以！

这正是Ralph的设计目的。推荐步骤：  1. 使用 ralph --monitor 启动 2. 按 Ctrl+B 然后 D 分离tmux会话 3. 关闭终端去睡觉 4. 第二天用 tmux attach 查看结果  为了安全，建议在Docker容器中运行。

终端命令

# 限制每小时最多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