Ralph 用于 Claude Code

具备智能退出检测与速率限制的自主 AI 开发循环

Ralph 是 Geoffrey Huntley 针对 Claude Code 所提出技术的一种实现，该技术能够支持持续的自主开发周期，并以 Ralph Wiggum 的名字命名。它允许 Claude Code 在内置的安全机制（如防止无限循环和 API 过度使用）保障下，不断迭代改进您的项目直至完成。

一次安装，随处可用 - Ralph 可作为全局命令，在任何目录中均可使用。

项目状态

版本: v0.11.5 - 正在积极开发 核心功能: 已实现并经过测试 测试覆盖率: 566 个测试，通过率 100%

目前已实现的功能

• 具备智能退出检测的自主开发循环
• 双重条件退出机制：必须同时满足完成标志和显式 EXIT_SIGNAL 才能退出
• 每小时重置的速率限制（100 次/小时，可配置）
• 带有高级错误检测的熔断器（防止失控循环）
• 具有语义理解能力的响应分析器，支持两阶段错误过滤
• 支持 JSON 输出格式，并自动回退至文本解析
• 通过 --resume 标志实现会话连续性，保留上下文（无会话劫持）
• 会话过期机制，可配置超时时间（默认 24 小时）
• 现代化 CLI 标志：--output-format、--allowed-tools、--no-continue
• 交互式项目启用向导 ralph-enable
• .ralphrc 配置文件，用于项目设置
• 通过 --live 标志提供实时流输出，便于查看 Claude Code 的执行过程
• 多行错误匹配，精准检测卡死循环
• 针对 5 小时 API 使用上限的处理，并配合用户提示
• 与 tmux 集成，方便实时监控
• 支持 PRD 导入功能
• 基于 GitHub Actions 的 CI/CD 流水线
• 专用卸载脚本，确保干净彻底地移除

最新改进

v0.11.5 - 社区修复的 bug（最新版本）

• 修复了 API 限制误报：超时（退出码 124）不再被误认为是 API 的 5 小时限制 (#183)
• 三层 API 限制检测机制：超时保护 → 结构化 JSON（rate_limit_event）→ 过滤文本回退
• 无人值守模式：API 限制提示现在会在超时时自动等待，而不是直接退出
• 修复了 Bash 3.x 兼容性问题：将 ${,,} 小写替换语法替换为 POSIX 的 tr 命令 (#187)
• 新增 8 个 API 限制检测测试用例（测试总数从 548 增加到 566）

v0.11.4 - Bug 修复与兼容性改进

• 修复了进度检测问题：循环中的 Git 提交现在会被计入进度 (#141)
• 修复了复选框正则表达式：日期条目 [2026-01-29] 不再被误认为是复选框 (#144)
• 修复了会话劫持问题：使用 --resume <session_id> 替代 --continue (#151)
• 修复了 EXIT_SIGNAL 覆盖问题：当 STATUS: COMPLETE 且 EXIT_SIGNAL: false 时，现在会继续运行 (#146)
• 修复了 ralph-import 无限挂起的问题（添加了用于非交互模式的 --print 标志）
• 修复了 ralph-import 绝对路径处理问题
• 修复了 macOS 上使用 Homebrew coreutils 时的跨平台日期命令问题
• 添加了可通过环境变量配置的熔断阈值 (#99)
• 为非零 base-index 配置增加了 tmux 支持
• 新增 13 个回归测试用例，用于测试进度检测和复选框正则表达式

v0.11.3 - 直播流与 beads 修复

• 添加了实时 Claude Code 可见性的直播输出模式，通过 --live 标志实现 (#125)
• 修复了使用正确 bd list 参数导入 beads 任务的问题 (#150)
• 应用了 CodeRabbit 审查修复：驼峰命名变量、尊重状态的回退逻辑、jq 防御措施
• 新增 12 个测试用例，用于改进直播流和 beads 导入功能

v0.11.2 - 设置权限修复

• 修复了问题 #136：ralph-setup 现在会创建具有一致工具权限的 .ralphrc 文件
• 更新了默认的 ALLOWED_TOOLS 列表，加入了 Edit、Bash(npm *) 和 Bash(pytest)
• ralph-setup 和 ralph-enable 现在都会生成完全相同的 .ralphrc 配置文件
• Monitor 现在会将所有 CLI 参数转发给内部的 ralph 循环 (#126)
• 新增 16 个测试用例，用于测试权限和参数转发功能

v0.11.1 - 完成指标修复

• 修复了 JSON 输出模式下恰好执行 5 次循环后过早退出的问题
• completion_indicators 现在仅在 EXIT_SIGNAL: true 时才会累计
• 与文档中记录的双条件退出机制保持一致

v0.11.0 - Ralph 启用向导

• 添加了 ralph-enable 交互式向导，用于在现有项目中启用 Ralph
• 五阶段向导：环境检测 → 任务来源选择 → 配置 → 文件生成 → 验证
• 自动检测项目类型（TypeScript、Python、Rust、Go）和框架（Next.js、FastAPI、Django）
• 可从 beads、GitHub Issues 或 PRD 文档中导入任务
• 添加了用于 CI/自动化流程的非交互式版本 ralph-enable-ci
• 新增库组件：enable_core.sh、wizard_utils.sh、task_sources.sh

v0.10.1 - Bug 修复与 Monitor 路径修正

• 修复了 ralph_monitor.sh 中硬编码的路径，以确保与 v0.10.0 兼容
• 修复了 JSON 格式中 EXIT_SIGNAL 的解析问题
• 添加了安全熔断机制（连续出现 5 个完成指标后强制退出）
• 修复了缩进 Markdown 中的复选框解析问题

v0.10.0 - .ralph/ 子文件夹结构（破坏性变更）

• 破坏性变更：所有 Ralph 特定文件均移至 .ralph/ 子文件夹
• 项目根目录保持整洁：仅保留 src/、README.md 和用户文件
• 添加了 ralph-migrate 命令，用于升级现有项目

早期版本（v0.9.x）

v0.9.9 - EXIT_SIGNAL 门控与卸载脚本

• 修复了过早退出的 bug：完成指标现在需要 Claude 明确的 EXIT_SIGNAL: true
• 添加了专门的 uninstall.sh 脚本，用于干净地移除 Ralph

v0.9.8 - 用于 PRD 导入的现代化 CLI

• 对 ralph_import.sh 进行了现代化改造，采用 Claude Code CLI 的 JSON 输出格式
• 增强了错误处理能力，使用结构化的 JSON 错误信息

v0.9.7 - 会话生命周期管理

• 实现了完整的会话生命周期管理，并设置了自动重置触发条件
• 添加了 --reset-session CLI 标志，用于手动重置会话

v0.9.6 - JSON 输出与会话管理

• 扩展了 parse_json_response() 函数，以支持 Claude Code CLI 的 JSON 格式
• 添加了会话管理相关函数

v0.9.5 - v0.9.0 - 包括 PRD 导入测试、项目设置测试、安装测试、提示文件修复、现代化 CLI 命令以及熔断器增强等功能

进展中

• 扩展测试覆盖率
• 自动化徽章更新

迈向 v1.0 的时间表：约 4 周 | 完整路线图 | 欢迎贡献！

功能特性

• 自主开发循环 - 根据您的项目需求持续执行 Claude Code
• 智能退出检测 - 双条件检查，需同时满足完成指标和明确的 EXIT_SIGNAL
• 会话连续性 - 通过自动会话管理，在循环迭代之间保持上下文
• 会话过期 - 可配置的超时时间（默认 24 小时），并自动重置会话
• 速率限制 - 内置 API 调用管理，包括每小时限制和倒计时定时器
• 5 小时 API 限制处理 - 三层检测机制（超时保护、JSON 解析、过滤文本），并针对无人值守模式自动等待
• 实时监控 - 实时仪表盘显示循环状态、进度和日志
• 任务管理 - 结构化方法，提供优先级任务列表和进度跟踪
• 项目模板 - 快速搭建新项目，采用最佳实践结构
• 交互式项目设置 - ralph-enable 向导，适用于现有项目及任务导入
• 配置文件 - .ralphrc 用于项目特定设置和工具权限
• 全面日志记录 - 详细的执行日志，包含时间戳和状态跟踪
• 可配置超时 - 可为 Claude Code 操作设置执行超时（1–120 分钟）
• 详细进度模式 - 执行过程中可选择详细的进度更新
• 响应分析器 - 基于 AI 的 Claude Code 响应分析，具备语义理解能力
• 熔断器 - 先进的错误检测机制，包括两阶段过滤、多行错误匹配和自动恢复
• CI/CD 集成 - GitHub Actions 工作流，支持自动化测试
• 干净卸载 - 专用卸载脚本，实现彻底移除
• 直播输出 - 通过 --live 标志实现实时查看 Claude Code 执行情况

快速入门

Ralph 包括两个阶段：一次性安装和每个项目的设置。

一次性安装              多次使用
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-enable         |
| 添加全局命令    |          | ralph-import prd.md  |
|                 |          | ...                  |
+-----------------+          +----------------------+

第一阶段：安装 Ralph（仅需执行一次）

在您的系统上全局安装 Ralph：

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

这会将 ralph、ralph-monitor、ralph-setup、ralph-import、ralph-migrate、ralph-enable 和 ralph-enable-ci 命令添加到您的 PATH 中。

注意：您只需在每个系统上执行一次此操作。安装完成后，您可以根据需要删除克隆的仓库。

第二阶段：初始化项目（按项目进行）

选项 A：在现有项目中启用 Ralph（推荐）

cd my-existing-project

# 交互式向导 - 自动检测项目类型并导入任务
ralph-enable

# 或者指定任务来源
ralph-enable --from beads
ralph-enable --from github --label "sprint-1"
ralph-enable --from prd ./docs/requirements.md

# 开始自主开发
ralph --monitor

选项 B：导入现有的 PRD/规格文档

# 将现有的 PRD/规格文档转换为 Ralph 格式
ralph-import my-requirements.md my-project
cd my-project

# 审查并调整生成的文件：
# - .ralph/PROMPT.md（Ralph 指令）
# - .ralph/fix_plan.md（任务优先级）
# - .ralph/specs/requirements.md（技术规格）

# 开始自主开发
ralph --monitor

选项 C：从头创建新项目

# 创建空白的 Ralph 项目
ralph-setup my-awesome-project
cd my-awesome-project

# 手动配置项目需求
# 编辑 .ralph/PROMPT.md 以设定项目目标
# 编辑 .ralph/specs/ 以提供详细规格
# 编辑 .ralph/fix_plan.md 以设定初始优先级

# 开始自主开发
ralph --monitor

后续使用（设置完成后）

一旦 Ralph 安装完成且项目已初始化：

# 导航到任意 Ralph 项目并运行：
ralph --monitor              # 集成 tmux 监控（推荐）

# 或者使用独立终端：
ralph                        # 终端 1：Ralph 循环
ralph-monitor               # 终端 2：实时监控仪表盘

卸载 Ralph

要从您的系统中完全移除 Ralph：

# 运行卸载脚本
./uninstall.sh

# 或者如果您已删除仓库，可下载并运行：
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash

理解 Ralph 文件

运行 ralph-enable 或 ralph-import 后，您将获得一个 .ralph/ 目录，其中包含多个文件。以下是每个文件的作用以及是否需要编辑它们：

文件	自动生成？	您应该...
.ralph/PROMPT.md	是（智能默认值）	审查并自定义 项目目标和原则
.ralph/fix_plan.md	是（可导入任务）	添加/修改 具体实现任务
.ralph/AGENT.md	是（检测构建命令）	很少编辑（由 Ralph 自动维护）
.ralph/specs/	空目录	当 PROMPT.md 不够详细时添加文件
.ralph/specs/stdlib/	空目录	添加可重用的模式和规范
.ralphrc	是（项目感知）	很少编辑（合理默认值）

主要文件之间的关系

PROMPT.md（高层次目标）
    ↓
specs/（必要时的详细需求）
    ↓
fix_plan.md（Ralph 执行的具体任务）
    ↓
AGENT.md（构建/测试命令 - 自动维护）

何时使用 specs/

• 简单项目：通常 PROMPT.md + fix_plan.md 就足够了
• 复杂功能：添加 specs/feature-name.md 以提供详细需求
• 团队规范：添加 specs/stdlib/convention-name.md 以提供可重用模式

有关详细说明，请参阅 用户指南；有关实际项目配置，请参阅 examples/ 目录。

工作原理

Ralph 基于一个简单而强大的循环运作：

1. 读取指令 - 加载包含项目需求的 PROMPT.md
2. 执行 Claude 代码 - 在当前上下文和优先级下运行 Claude 代码
3. 跟踪进度 - 更新任务列表并记录执行结果
4. 评估完成情况 - 检查退出条件及项目完成信号
5. 重复 - 直到项目完成或达到限制为止

智能退出检测

Ralph 使用 双重条件检查 来防止在高效迭代过程中过早退出：

退出需要同时满足以下两个条件：

1. completion_indicators >= 2（基于自然语言模式的启发式检测）
2. Claude 在 RALPH_STATUS 块中明确发出 EXIT_SIGNAL: true

示例行为：

第 5 轮：Claude 输出“阶段完成，进入下一功能”
        → completion_indicators: 3（基于模式的高度信心）
        → EXIT_SIGNAL: false（Claude 表示还需要更多工作）
        → 结果：继续（尊重 Claude 的明确意图）

第 8 轮：Claude 输出“所有任务完成，项目准备就绪”
        → completion_indicators: 4
        → EXIT_SIGNAL: true（Claude 确认已完成）
        → 结果：退出，并显示“project_complete”

其他退出条件：

• .ralph/fix_plan.md 中的所有任务均标记为完成
• Claude 代码连续多次发出“完成”信号
• 测试导向的循环次数过多（表明功能已完成）
• Claude API 使用时间达到 5 小时上限（此时会提示用户等待或退出）

在现有项目中启用 Ralph

ralph-enable 命令提供了一个交互式向导，用于将 Ralph 添加到现有项目中：

cd my-existing-project
ralph-enable

向导流程：

1. 检测环境 - 识别项目类型（TypeScript、Python 等）和框架
2. 选择任务来源 - 可从 beads、GitHub Issues 或 PRD 文档中选择
3. 配置设置 - 设置工具权限和循环参数
4. 生成文件 - 创建 .ralph/ 目录和 .ralphrc 配置文件
5. 验证设置 - 确认所有文件均已正确创建

非交互模式，适用于 CI/自动化：

ralph-enable-ci                              # 合理默认值
ralph-enable-ci --from github               # 从 GitHub Issues 导入
ralph-enable-ci --project-type typescript   # 覆盖自动检测
ralph-enable-ci --json                      # 机器可读输出

导入现有需求

Ralph 可以使用 Claude 代码将现有的 PRD、规格文档或需求文件转换为适当的 Ralph 格式。

支持的格式

• Markdown (.md) - 产品需求、技术规格
• 文本文件 (.txt) - 纯文本需求
• JSON (.json) - 结构化需求数据
• Word 文档 (.docx) - 商业需求
• PDF (.pdf) - 设计文档、规格
• 任何基于文本的格式 - Ralph 会智能解析内容

使用示例

# 转换 Markdown 格式的 PRD
ralph-import product-requirements.md my-app

# 转换文本规格
ralph-import requirements.txt webapp

# 转换 JSON 格式的 API 规格
ralph-import api-spec.json backend-service

# 让 Ralph 根据文件名自动命名项目
ralph-import design-doc.pdf

生成的内容

Ralph-import 会创建一个完整的项目，包含以下内容：

• .ralph/PROMPT.md - 转换为 Ralph 开发指令
• .ralph/fix_plan.md - 将需求分解为优先级任务
• .ralph/specs/requirements.md - 从您的文档中提取的技术规格
• .ralphrc - 包含工具权限的项目配置文件
• 标准 Ralph 结构 - .ralph/ 中的所有必要目录和模板文件

转换过程智能且保留了您原有的需求，同时使其可被自主开发所执行。

配置

项目配置 (.ralphrc)

每个 Ralph 项目都可以有一个 .ralphrc 配置文件：

# .ralphrc - Ralph 项目配置
PROJECT_NAME="my-project"
PROJECT_TYPE="typescript"

# Claude Code CLI 命令（自动检测，如有需要可覆盖）
CLAUDE_CODE_CMD="claude"
# CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code"  # 替代方案：使用 npx

# Shell 初始化文件 — 在运行 claude 之前先加载（适用于 zsh/fish 用户，
# 其 PATH 或环境变量仅在其 shell 的初始化文件中设置）
#RALPH_SHELL_INIT_FILE="~/.zshrc"

# 循环设置
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
# 每小时令牌预算（0 = 禁用）。一次 Claude 调用可能消耗 10 万+ 令牌。
#MAX_TOKENS_PER_HOUR=500000

# 工具权限
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

# 会话管理
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24

# 断路器阈值
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5

速率限制与断路器

Ralph 包含智能的速率限制和断路器功能：

# 默认：每小时 100 次调用
ralph --calls 50

# 带集成监控
ralph --monitor --calls 50

# 查看当前使用情况（显示本小时已使用的调用次数和令牌数）
ralph --status

速率限制支持两个独立的限制——两者每小时重置一次：

设置	默认	描述
MAX_CALLS_PER_HOUR	100	每小时最大 Claude 调用次数
MAX_TOKENS_PER_HOUR	0（禁用）	每小时累计最大令牌数

令牌跟踪会从每次 Claude 响应中提取 input_tokens + output_tokens。单次调用可能消耗 10 万+ 令牌，因此 MAX_TOKENS_PER_HOUR 提供了 MAX_CALLS_PER_HOUR 单独无法实现的成本控制。

断路器会自动：

• 使用高级两阶段过滤检测 API 错误和速率限制问题
• 在连续 3 次循环无进展或连续 5 次循环出现相同错误时打开断路器
• 消除因 JSON 字段中包含“error”而导致的误报
• 通过多行错误匹配准确检测卡住的循环
• 逐步恢复，进入半开监控状态
• 自动恢复在冷却期后（默认：30 分钟）——OPEN → HALF_OPEN → CLOSED
• 提供详细的错误跟踪和日志记录，包括状态历史

自动恢复选项：

# 默认：自动恢复尝试前有 30 分钟的冷却期
CB_COOLDOWN_MINUTES=30     # 在 .ralphrc 中设置（0 = 立即）

# 启动时自动重置断路器（用于完全无人值守的操作）
ralph --auto-reset-circuit
# 或在 .ralphrc 中设置：CB_AUTO_RESET=true

Claude API 5 小时限制

当 Claude 的 5 小时使用限制达到时，Ralph 会：

1. 使用三层验证检测该限制（超时保护 → 结构化 JSON → 过滤后的文本回退）
2. 提示您选择：
   • 选项 1：等待 60 分钟以重置限制（带倒计时）
   • 选项 2：优雅退出
3. 无人值守模式：在提示超时（30 秒）后自动等待，而不是退出
4. 防止因回显的文件内容提及“5 小时限制”而产生的误报。

自定义提示

# 使用自定义提示文件
ralph --prompt my_custom_instructions.md

# 带集成监控
ralph --monitor --prompt my_custom_instructions.md

执行超时

# 设置 Claude Code 执行超时（默认：15 分钟）
ralph --timeout 30  # 复杂任务的 30 分钟超时

# 带监控和自定义超时
ralph --monitor --timeout 60  # 60 分钟超时

# 快速迭代的短超时
ralph --verbose --timeout 5  # 带进度的 5 分钟超时

详细模式

# 在执行过程中启用详细的进度更新
ralph --verbose

# 可与其他选项结合使用
ralph --monitor --verbose --timeout 30

实时输出流

# 启用对 Claude Code 执行的实时可见性
ralph --live

# 与监控结合使用以获得最佳体验
ralph --monitor --live

# 实时输出会写入 .ralph/live.log
tail -f .ralph/live.log  # 在另一个终端查看

实时流模式会实时显示 Claude Code 的输出，让您清楚地了解每次循环迭代中正在发生的事情。

会话连续性

Ralph 会在循环迭代之间保持会话上下文，以提高连贯性：

# 默认启用会话连续性，只需使用 --continue 标志
ralph --monitor                 # 使用会话连续性

# 不带会话上下文从头开始
ralph --no-continue             # 独立的迭代

# 手动重置会话（清除上下文）
ralph --reset-session           # 清除当前会话

# 查看会话状态
cat .ralph/.ralph_session              # 查看当前会话文件
cat .ralph/.ralph_session_history      # 查看会话过渡历史

会话自动重置触发条件：

• 断路器打开（检测到停滞）
• 手动中断（Ctrl+C / SIGINT）
• 项目完成（优雅退出）
• 手动重置断路器（--reset-circuit）
• 会话到期（默认：24 小时）

会话会持久化到 .ralph/.ralph_session，其有效期可配置（默认：24 小时）。最近 50 次会话过渡会被记录到 .ralph/.ralph_session_history 中，以便调试。

退出阈值

在 ~/.ralph/ralph_loop.sh 中修改这些变量：

退出检测阈值：

MAX_CONSECUTIVE_TEST_LOOPS=3     # 经过3次仅测试循环后退出
MAX_CONSECUTIVE_DONE_SIGNALS=2   # 收到2次“完成”信号后退出
TEST_PERCENTAGE_THRESHOLD=30     # 如果30%以上的循环仅为测试循环，则发出警告

熔断器阈值：

CB_NO_PROGRESS_THRESHOLD=3       # 连续3次循环无文件更改时触发熔断
CB_SAME_ERROR_THRESHOLD=5        # 连续5次循环出现重复错误时触发熔断
CB_OUTPUT_DECLINE_THRESHOLD=70   # 输出下降超过70%时触发熔断
CB_COOLDOWN_MINUTES=30           # 从“OPEN”状态自动恢复为“HALF_OPEN”状态前的冷却时间（分钟）
CB_AUTO_RESET=false              # true = 启动时重置为“CLOSED”状态（绕过冷却期）

完成指标与 EXIT_SIGNAL 门控：

completion_indicators	EXIT_SIGNAL	结果
>= 2	true	退出（“project_complete”）
>= 2	false	继续（Claude仍在工作）
>= 2	缺失	继续（默认为 false）
< 2	true	继续（未达到阈值）

项目结构

Ralph 为每个项目创建标准化的结构，其中包含用于配置的 .ralph/ 子文件夹：

my-project/
├── .ralph/                 # Ralph 配置与状态文件（隐藏文件夹）
│   ├── PROMPT.md           # Ralph 的主要开发说明
│   ├── fix_plan.md         # 优先级任务列表
│   ├── AGENT.md            # 构建和运行说明
│   ├── specs/              # 项目规格与需求
│   │   └── stdlib/         # 标准库规格
│   ├── examples/           # 使用示例与测试用例
│   ├── logs/               # Ralph 执行日志
│   └── docs/generated/     # 自动生成的文档
├── .ralphrc                # Ralph 配置文件（工具权限、设置）
└── src/                    # 源代码实现（位于项目根目录）

迁移：如果您有使用旧式扁平结构的现有 Ralph 项目，请运行 ralph-migrate 自动将文件移至 .ralph/ 子文件夹。

最佳实践

编写有效提示

1. 明确具体 - 清晰的需求带来更好的结果
2. 优先排序 - 使用 .ralph/fix_plan.md 引导 Ralph 的关注点
3. 设定边界 - 定义范围内外的内容
4. 包含示例 - 展示预期的输入/输出

项目规格

• 将详细需求放在 .ralph/specs/ 中
• 使用 .ralph/fix_plan.md 进行优先级任务跟踪
• 保持 .ralph/AGENT.md 更新以包含构建指令
• 记录关键决策和架构设计

监控进度

• 使用 ralph-monitor 获取实时状态更新
• 查看 .ralph/logs/ 中的日志以了解详细的执行历史
• 监控 .ralph/status.json 以进行程序化访问
• 注意退出条件信号

系统要求

• Bash 4.0+ - 用于脚本执行
• Claude Code CLI - npm install -g @anthropic-ai/claude-code（或使用 npx — 在 .ralphrc 中设置 CLAUDE_CODE_CMD）
• tmux - 终端多路复用器，推荐用于集成监控
• jq - 用于状态跟踪的 JSON 处理工具
• Git - 版本控制（项目初始化为 Git 仓库）
• GNU coreutils - 提供 timeout 命令（执行超时）
  • Linux：大多数发行版已预装
  • macOS：通过 brew install coreutils 安装（提供 gtimeout）
• 标准 Unix 工具 - grep、date 等

测试要求（开发）

请参阅 TESTING.md 以获取完整的测试指南。

如果您想运行测试套件：

# 安装 BATS 测试框架
npm install -g bats bats-support bats-assert

# 运行所有测试（566 个测试）
npm test

# 运行特定测试套件
bats tests/unit/test_rate_limiting.bats
bats tests/unit/test_exit_detection.bats
bats tests/unit/test_json_parsing.bats
bats tests/unit/test_cli_modern.bats
bats tests/unit/test_cli_parsing.bats
bats tests/unit/test_session_continuity.bats
bats tests/unit/test_enable_core.bats
bats tests/unit/test_task_sources.bats
bats tests/unit/test_ralph_enable.bats
bats tests/unit/test_wizard_utils.bats
bats tests/unit/test_circuit_breaker_recovery.bats
bats tests/integration/test_loop_execution.bats
bats tests/integration/test_prd_import.bats
bats tests/integration/test_project_setup.bats
bats tests/integration/test_installation.bats

# 运行错误检测和熔断器测试
./tests/test_error_detection.sh
./tests/test_stuck_loop_detection.sh

当前测试状态：

• 566 个测试，分布在 18 个测试文件中
• 100% 通过率（556/556 通过）
• 全面的单元和集成测试
• 专门针对 JSON 解析、CLI 标志、熔断器、EXIT_SIGNAL 行为、启用向导以及安装流程的测试

覆盖率说明：使用 kcov 测量 Bash 代码覆盖率时，在追踪子进程执行方面存在根本性限制。测试通过率（100%）是质量门槛。详情请参阅 bats-core#15。

安装 tmux

# Ubuntu/Debian
sudo apt-get install tmux

# macOS
brew install tmux

# CentOS/RHEL
sudo yum install tmux

安装 GNU coreutils（macOS）

Ralph 使用 timeout 命令来实现执行超时。在 macOS 上，您需要安装 GNU coreutils：

# 安装 coreutils（提供 gtimeout）
brew install coreutils

# 验证安装
gtimeout --version

Ralph 会自动检测并在 macOS 上使用 gtimeout。安装完成后无需额外配置。

监控与调试

实时仪表板

# 推荐使用集成的 tmux 监控
ralph --monitor

# 在单独终端手动监控
ralph-monitor

实时显示：

• 当前循环次数及状态
• 已使用的 API 调用数与限额
• 最近的日志条目
• 速率限制倒计时

tmux 控制键：

• Ctrl+B 后按 D - 分离会话（Ralph 仍会继续运行）
• Ctrl+B 后按 ←/→ - 切换窗格
• tmux list-sessions - 查看活动会话
• tmux attach -t <session-name> - 重新连接到会话

状态检查

# JSON 格式的状态输出
ralph --status

# 手动检查日志
tail -f .ralph/logs/ralph.log

常见问题

• Ralph 在第一次循环中静默退出 - 可能是 Claude Code CLI 未安装或未添加到 PATH 中。Ralph 在启动时会验证命令是否存在，并显示安装说明。如果使用 npx，请在 .ralphrc 文件中添加 CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code"。
• 速率限制 - Ralph 会自动等待并显示倒计时。
• 5 小时 API 限制 - Ralph 会检测并提示用户采取行动（等待或退出）。
• 卡住的循环 - 检查 fix_plan.md 文件，查看是否有不明确或冲突的任务。
• 提前退出 - 如果 Ralph 过早停止，请检查退出阈值。
• 过早退出 - 检查 Claude 是否设置了 EXIT_SIGNAL: false（Ralph 现在会尊重此设置）。
• 执行超时 - 对于复杂操作，可增加 --timeout 参数的值。
• 缺少依赖项 - 确保已安装 Claude Code CLI 和 tmux。
• tmux 会话丢失 - 使用 tmux list-sessions 和 tmux attach 重新连接。
• 会话过期 - 默认情况下，会话会在 24 小时后过期；使用 --reset-session 可以重新开始。
• timeout: command not found（macOS） - 安装 GNU coreutils：brew install coreutils。
• 权限被拒绝 - 当 Claude Code 被拒绝执行某些命令时，Ralph 会停止：
  1. 编辑 .ralphrc 文件，将 ALLOWED_TOOLS 更新为包含所需工具。
  2. 常见模式：Bash(npm *)、Bash(git *)、Bash(pytest)。
  3. 更新 .ralphrc 后运行 ralph --reset-session。
  4. 使用 ralph --monitor 重新启动。

贡献

Ralph 正在积极寻求贡献者！我们正朝着 v1.0.0 版本努力，拥有清晰的优先级和详细的路线图。

请参阅 CONTRIBUTING.md 获取完整的贡献指南，其中包括：

• 入门和设置说明
• 开发工作流程和提交规范
• 代码风格指南
• 测试要求（必须达到 100% 的通过率）
• 拉取请求流程和代码审查指南
• 质量标准和检查清单

快速入门

# 分支并克隆
git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
cd ralph-claude-code

# 安装依赖并运行测试
npm install
npm test  # 所有 566 个测试必须通过

优先贡献领域

1. 测试实现 - 帮助扩展测试覆盖率
2. 功能开发 - 日志轮转、试运行模式、指标
3. 文档 - 教程、故障排除指南、示例
4. 实际测试 - 使用 Ralph，报告 bug，分享反馈

每一份贡献都很重要 - 从修复错别字到实现重大功能！

许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

致谢

• 灵感来源于 Geoffrey Huntley 创建的 Ralph 技术
• 专为 Anthropic 的 Claude Code 构建
• 社区的反馈与贡献

相关项目

• Claude Code - 驱动 Ralph 的 AI 编码助手
• Aider - Ralph 技术的原始实现

---

命令参考

安装命令（只需运行一次）

./install.sh              # 全局安装 Ralph
./uninstall.sh            # 从系统中移除 Ralph（专用脚本）
./install.sh uninstall    # 替代方案：从系统中移除 Ralph
./install.sh --help       # 显示安装帮助
ralph-migrate             # 将现有项目迁移到 .ralph/ 结构

Ralph 循环选项

ralph [OPTIONS]
  -h, --help              显示帮助信息
  -c, --calls NUM         设置每小时最大调用次数（默认：100）
  -p, --prompt FILE       设置提示文件（默认：PROMPT.md）
  -s, --status            显示当前状态并退出
  -m, --monitor           使用 tmux 会话和实时监控启动
  -v, --verbose           在执行过程中显示详细进度更新
  -l, --live              启用实时流输出（即时查看 Claude Code）
  -t, --timeout MIN       设置 Claude Code 执行超时时间（1-120 分钟，默认：15 分钟）
  --output-format FORMAT  设置输出格式：json（默认）或文本
  --allowed-tools TOOLS   设置允许使用的 Claude 工具（默认：Write, Read, Edit, Bash(git *), Bash(npm *), Bash(pytest)）
  --no-continue           禁用会话连续性（每次循环都从头开始）
  --reset-circuit         重置断路器
  --circuit-status        显示断路器状态
  --auto-reset-circuit    启动时自动重置断路器（绕过冷却时间）
  --reset-session         手动重置会话状态
  -b, --backup            在每次循环前启用自动 git 备份分支（需要 git）
  --rollback [BRANCH]     回滚到备份分支（若未指定，则列出可用分支）

项目相关命令（按项目）

ralph-setup project-name     # 创建新的 Ralph 项目
ralph-enable                 # 在现有项目中启用 Ralph（交互式）
ralph-enable-ci              # 在现有项目中启用 Ralph（非交互式）
ralph-import prd.md project  # 将 PRD/规格转换为 Ralph 项目
ralph --monitor              # 使用集成监控启动
ralph --status               # 检查当前循环状态
ralph --verbose              # 启用详细进度更新
ralph --timeout 30           # 设置 30 分钟的执行超时
ralph --calls 50             # 限制每小时 API 调用次数为 50 次
ralph --reset-session        # 手动重置会话状态
ralph --live                 # 启用实时流输出
ralph-monitor                # 手动监控仪表板

tmux 会话管理

tmux list-sessions        # 查看活跃的 Ralph 会话
tmux attach -t <name>     # 重新连接到已分离的会话
# Ctrl+B then D           # 分离会话（保持运行）

---

开发路线图

Ralph 目前正处于积极开发阶段，正朝着 v1.0.0 版本稳步前进。完整路线图请参阅 IMPLEMENTATION_PLAN.md。

当前状态：v0.11.5

已交付内容：

• 核心循环功能，具备智能退出检测
• 双条件退出门控（完成指标 + EXIT_SIGNAL）
• 限流机制（每小时100次调用）及熔断模式
• 具有语义理解能力的响应分析器
• 556项全面测试（100%通过率）
• 直播输出模式，可实时查看Claude Code代码
• tmux集成与实时监控
• 支持现代CLI JSON解析的PRD导入功能
• 安装系统与项目模板
• 现代化CLI命令，支持JSON输出
• 使用GitHub Actions的CI/CD流水线
• 面向现有项目的交互式ralph-enable向导
• .ralphrc配置文件支持
• 基于自动重置触发器的会话生命周期管理
• 可配置超时时间的会话过期机制
• 专用卸载脚本

测试覆盖率细分：

• 单元测试：477项（CLI解析、JSON处理、退出检测、限流与令牌预算、会话连续性、启用向导、直播流、熔断恢复、文件保护、完整性检查）
• 集成测试：136项（循环执行、边缘场景、安装、项目初始化、PRD导入）
• 测试文件：18个

通往v1.0.0的道路（约4周）

增强测试

• 安装与设置工作流测试
• tmux集成测试
• 监控仪表盘测试

核心功能

• 日志轮转功能
• 模拟运行模式

高级功能与优化

• 端到端测试
• 最终文档编写与发布准备

详细进度跟踪请参阅IMPLEMENTATION_STATUS.md。

如何贡献

Ralph现正招募贡献者！完整指南请见CONTRIBUTING.md。优先领域：

1. 测试实现 - 帮助扩展测试覆盖率（查看计划）
2. 功能开发 - 日志轮转、模拟运行模式、指标收集
3. 文档编写 - 使用示例、教程、故障排除指南
4. Bug报告 - 实际使用反馈及边缘场景

---

准备好让AI构建你的项目了吗？ 从./install.sh开始，剩下的就交给Ralph吧！

星标历史

Ralph for Claude Code 快速上手指南

Ralph 是一个基于 Geoffrey Huntley 技术实现的自主 AI 开发循环工具，专为 Claude Code 设计。它能驱动 Claude Code 持续迭代改进你的项目，直到任务完成，并内置了智能退出检测、速率限制和熔断机制以防止无限循环或 API 滥用。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Linux, macOS (推荐), 或 WSL2 (Windows)。
  • 注：已修复 Bash 3.x 兼容性问题，支持更广泛的 Linux 发行版。
• 核心依赖:
  • Node.js & npm: 用于运行 Claude Code CLI。
  • Claude Code CLI: 必须已安装并配置好 API Key (npm install -g @anthropic-ai/claude-code)。
  • Git: 用于版本控制和进度追踪。
  • tmux (可选但推荐): 用于实时监控面板 (ralph --monitor)。
  • jq: 用于处理 JSON 输出（通常系统自带或通过包管理器安装）。
• API 配额: 确保你的 Anthropic API 账户有足够的额度（默认限制为每小时 100 次调用，可配置）。

安装步骤

Ralph 的安装分为两个阶段：全局安装（只需一次）和 项目初始化（每个项目一次）。

第一阶段：全局安装 (One-time Install)

将 Ralph 安装为全局命令，以便在任何目录下使用。

# 1. 克隆仓库
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# 2. 运行安装脚本
./install.sh

安装完成后，ralph, ralph-monitor, ralph-enable, ralph-import 等命令将添加到你的系统 PATH 中。

提示: 安装成功后，你可以删除克隆的 ralph-claude-code 目录，不影响使用。如需卸载，运行 ./uninstall.sh 或通过 curl 运行远程卸载脚本。

第二阶段：项目初始化 (Per-Project Setup)

根据你的项目状态，选择以下任一方式初始化：

方案 A：在现有项目中启用 (推荐)

使用交互式向导自动检测项目类型（如 TypeScript, Python, Rust）并导入任务。

cd my-existing-project

# 启动交互式向导 (自动识别框架并导入任务)
ralph-enable

# 或者指定任务来源：
# ralph-enable --from beads       # 从 beads 任务列表导入
# ralph-enable --from github      # 从 GitHub Issues 导入
# ralph-enable --from prd ./docs/requirements.md # 从 PRD 文档导入

方案 B：导入现有的需求文档 (PRD)

将现有的需求文档转换为 Ralph 格式。

# 转换需求文档并创建项目结构
ralph-import my-requirements.md my-project
cd my-project

# (可选) 手动调整生成的 .ralph/ 目录下的配置文件

方案 C：从零创建新项目

创建一个带有最佳实践结构的空白 Ralph 项目。

# 创建新项目
ralph-setup my-awesome-project
cd my-awesome-project

# 手动编辑 .ralph/PROMPT.md 定义项目目标
# 手动编辑 .ralph/specs/ 添加详细规格

基本使用

初始化完成后，即可启动自主开发循环。

启动开发循环 (带实时监控)

这是最推荐的用法，它会启动一个 tmux 会话，同时运行 Ralph 循环和实时监控面板。

# 在项目根目录下运行
ralph --monitor

• 左侧/主窗口: 显示 Claude Code 的实时执行日志。
• 监控面板: 显示循环状态、进度条、API 调用计数和错误信息。

分离模式 (无 tmux)

如果你不想使用 tmux，可以在两个独立的终端窗口中分别运行：

终端 1 (执行循环):

ralph

终端 2 (查看监控):

ralph-monitor

常用参数示例

• 断点续传: 如果循环意外中断，使用 --resume 恢复上下文（防止会话劫持）。

  ralph --resume <session_id>
  

• 实时流式输出: 直接在当前终端查看 Claude Code 的实时输出。

  ralph --live
  

• 指定允许的工具: 限制 Claude Code 可使用的工具范围。

  ralph --allowed-tools "Edit,Bash(npm *)"
  

• 单次执行不连续: 运行一次后停止，不进入自动循环。

  ralph --no-continue
  

停止循环

Ralph 具备智能退出检测，当检测到 EXIT_SIGNAL: true 且完成指标满足时会自动停止。若需强制停止：

• 在 tmux 模式中：按下 Ctrl+b 然后输入 :kill-pane 或直接关闭终端。
• 在普通模式中：按下 Ctrl+C。