SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ralph-claude-code-autonomous-development

ralph-claude-code-autonomous-development

编程与开发

查看项目

更新于 10-16 10:36

技能介绍

用途

Ralph 是一个用于 Claude Code 的自主 AI 开发循环（Autonomous Development Loop），让 Claude Code 能够持续、自动地迭代执行开发任务，直到项目完成。它实现了 Geoffrey Huntley 提出的「Ralph Wiggum」技术，并加入了智能退出检测、会话连续性管理、速率限制和熔断机制，以避免陷入无限循环。

主要能力

  • 让 Claude Code 在连续自主循环中运行，直至项目完成
  • 跨迭代管理会话连续性并保留上下文
  • 强制执行双条件退出门控：完成指示标记 + 显式 EXIT_SIGNAL
  • 对 API 调用进行速率限制（默认每小时 100 次），并支持自动重置
  • 通过语义分析和熔断器检测卡死的循环
  • 通过 tmux 集成提供实时监控面板
  • 从 PRD、GitHub Issues 或 beads 任务管理器导入任务
  • 支持 JSON 输出格式，并可在解析失败时自动回退到文本解析

安装方式

阶段一：全局安装 Ralph（一次性）

# Clone and install Ralph system-wide
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

# Verify installation
which ralph
ralph --version

该步骤会添加以下全局命令：

  • ralph - 主自主循环
  • ralph-monitor - 实时面板
  • ralph-setup - 创建新的 Ralph 项目
  • ralph-enable - 在现有项目中启用 Ralph
  • ralph-import - 导入 PRD/规格说明
  • ralph-migrate - 升级到最新目录结构

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

可选择以下方式之一：

方式 A：在现有项目中启用（推荐）

cd my-existing-project
ralph-enable  # Interactive wizard

方式 B：导入已有 PRD

ralph-import requirements.md my-project
cd my-project

方式 C：创建新项目

ralph-setup my-awesome-project
cd my-awesome-project

核心命令

# Start autonomous development with integrated monitoring
ralph --monitor

# Start without monitoring (requires separate terminal for ralph-monitor)
ralph

# Resume existing session (preserves context)
ralph --resume <session_id>

# Live streaming output (real-time visibility)
ralph --live

# Configure output format
ralph --output-format json
ralph --output-format text

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

# Disable auto-continuation (require manual approval)
ralph --no-continue

# Custom timeout (1-120 minutes, default: 30)
ralph --timeout 60

# Verbose progress mode
ralph --verbose

# Reset session manually
ralph --reset-session

另有 ralph-enable、ralph-enable-ci、ralph-import、ralph-migrate、ralph-monitor 等设置、配置与监控命令，支持从 beads、GitHub 标签或 PRD 文件导入任务。

项目结构

Ralph 将项目组织在 .ralph/ 子目录中，包含：

my-project/
├── .ralph/
│   ├── PROMPT.md              # Main instructions for Claude
│   ├── fix_plan.md            # Prioritized task list
│   ├── .ralphrc               # Project configuration
│   ├── specs/                 # Technical specifications
│   │   └── requirements.md
│   ├── logs/                  # Execution logs
│   │   ├── ralph.log
│   │   └── claude_responses.log
│   └── sessions/              # Session management
│       └── current_session.json
├── src/                       # Your actual code
└── README.md

配置

.ralphrc 文件由 ralph-enable 或 ralph-setup 自动创建，包含允许的工具、输出格式、超时时间、速率限制、会话超时以及可选的熔断器阈值等配置项。也可通过环境变量覆盖，如 RATE_LIMIT_PER_HOUR、SESSION_TIMEOUT_HOURS、CIRCUIT_BREAKER_THRESHOLD、LOG_DIR、CLAUDE_API_KEY 等。

退出检测

Ralph 使用双条件退出门控：

  1. 完成指示标记——Claude 用 [x] 标记任务完成
  2. 显式 EXIT_SIGNAL——Claude 必须在 PROMPT.md 中设置 EXIT_SIGNAL: true

两个条件必须同时满足，Ralph 才会退出，以防止过早退出。若 Claude 显式设置 EXIT_SIGNAL: false，即使完成指示已积累，Ralph 也会继续工作。

速率限制

Ralph 对 API 调用施加限制以防滥用，默认每小时 100 次，可在 .ralphrc 中配置。达到上限时显示倒计时。此外，Claude API 每账号有 5 小时限制，Ralph 通过三层机制检测：超时保护、JSON 解析中的 rate_limit_event 检测、以及排除超时错误后的文本回退检查。v0.11.5 修复了超时（退出码 124）被误判为 API 限制的问题。

熔断器

通过语义分析、两阶段过滤、多行错误匹配检测卡死状态，默认阈值为连续 3 次错误。当同一错误重复 3 次以上、连续 3 次以上循环无进展、或完成指示累积但无 EXIT_SIGNAL 时自动触发。

常见使用模式

资料给出了多种使用模式：从 PRD 启动新项目、在现有项目启用、从 beads 导入任务、导入 GitHub Issues、恢复中断的会话、自定义工具权限，以及 CI/CD 集成（提供了 GitHub Actions 工作流示例）。

适用场景

适用于希望让 Claude Code 长时间自主迭代开发的场景，如按 PRD 构建 REST API、从任务列表驱动开发、在 CI 中自动推进需求等。

限制与故障排查

资料列出的常见问题包括：过早退出、陷入无限循环、速率限制过快触达、会话过期、超时误判为 API 限制、JSON 解析错误、工具权限被拒、监控不显示更新、旧版本迁移问题等，并给出相应解决方式。最佳实践包括从小规模开始、始终使用监控、设置合理超时、运行前提交版本控制、显式退出信号、注意速率限制、使用 --resume 保留上下文等。卸载可用官方 uninstall 脚本，会移除全局命令与 shell 配置，但不会移除项目的 .ralph/ 目录。