## 项目概述

Ralph for Claude Code 是一个基于 Shell 脚本的自主 AI 开发循环工具，旨在为 Claude Code CLI 提供持续、自主的开发迭代能力。它实现了 Geoffrey Huntley 提出的 Ralph 技术，通过智能退出检测和速率限制，让 Claude Code 能够迭代改进项目直至完成，同时避免无限循环和 API 过度使用。项目当前版本为 v0.11.5，处于积极开发阶段，拥有 784 个测试且全部通过。

## 核心功能

- **自主开发循环**：持续执行 Claude Code，根据项目需求迭代开发。
- **智能退出检测**：采用双条件退出门控，要求同时满足完成指标和显式 EXIT_SIGNAL。
- **会话连续性**：跨循环迭代保留上下文，支持会话过期和自动重置。
- **速率限制与熔断器**：内置 API 调用管理（默认每小时 100 次），熔断器防止停滞循环。
- **实时监控**：通过 tmux 集成提供实时仪表盘，显示循环状态、进度和日志。
- **任务管理**：基于优先级的任务列表和进度跟踪。
- **项目模板与交互式设置**：`ralph-enable` 向导自动检测项目类型并导入任务。
- **配置灵活**：支持 `.ralphrc` 配置文件、自定义提示词、超时设置等。
- **沙箱执行**：支持 Docker 和 E2B 云沙箱，隔离 Claude 执行环境。
- **GitHub 集成**：支持从 GitHub Issues 导入任务，并可自动创建 PR、关闭 Issue。
- **批处理队列**：`ralph-queue` 支持批量处理多个 Issue 或 PRD。
- **丰富的 CLI 选项**：包括 `--live` 实时输出、`--dry-run` 模拟运行、`--backup` 备份等。

## 适用与不适用场景

**适用场景：**
- 需要长时间自主运行的开发任务，如从 PRD 生成完整项目。
- 希望减少人工干预的迭代开发流程。
- 需要批量处理多个 GitHub Issue 或规格文档的场景。
- 希望在隔离环境中运行 AI 编码代理以增强安全性的场景。

**不适用场景：**
- 需要严格人工审查每一步的敏感项目。
- 对 API 成本极其敏感，无法容忍自主循环消耗大量 token 的场景。
- 需要实时交互式编程，而非自主循环的场景。
- 项目依赖复杂的外部服务，且无法在沙箱中复现的场景。

## 技术架构与依赖

Ralph 主要由 Shell 脚本（Bash）实现，核心组件包括：
- `ralph_loop.sh`：主循环脚本，负责执行 Claude Code、分析响应、更新状态。
- `lib/response_analyzer.sh`：响应分析器，解析 Claude 输出，检测完成信号。
- `lib/circuit_breaker.sh`：熔断器，防止停滞循环。
- `lib/sandbox_docker.sh` 和 `lib/e2b_helper.py`：沙箱执行支持。
- `ralph_monitor.sh`：监控仪表盘。
- `ralph_import.sh`、`ralph_enable.sh` 等辅助工具。

**主要依赖：**
- Bash 4.0+、Claude Code CLI、tmux（推荐）、jq、Git、GNU coreutils（macOS 需要）。
- 可选：Docker（沙箱）、E2B Python SDK（云沙箱）、GitHub CLI（Issue 集成）。

## 安装与快速开始

**安装（一次性）：**
```bash
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh
```

**项目初始化（每个项目）：**
```bash
# 在现有项目中启用（推荐）
cd my-existing-project
ralph-enable

# 或从 PRD 导入
ralph-import my-requirements.md my-project

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

**启动开发循环：**
```bash
ralph --monitor
```

## 典型使用方法

**基本用法：**
```bash
ralph --monitor              # 集成 tmux 监控
ralph --calls 50             # 限制每小时 API 调用次数
ralph --timeout 30           # 设置执行超时（分钟）
ralph --live                 # 实时流式输出
ralph --dry-run              # 模拟运行，不调用 API
```

**从 GitHub Issues 导入：**
```bash
ralph-import --github-issue 42
ralph-import --github-label "bug,P0" --select priority
```

**批处理队列：**
```bash
ralph-queue add --github-label "bug,P0"
ralph --process-queue
```

**沙箱执行：**
```bash
ralph --sandbox docker
ralph --sandbox e2b --sandbox-max-cost 5.00
```

## 配置与部署要点

**配置文件 `.ralphrc`：**
- 设置项目名称、类型、速率限制、工具权限、会话管理等。
- 环境变量优先级高于 `.ralphrc`。

**关键配置项：**
- `MAX_CALLS_PER_HOUR`：每小时最大调用次数（默认 100）。
- `CLAUDE_TIMEOUT_MINUTES`：单次执行超时（默认 15）。
- `ALLOWED_TOOLS`：允许的工具列表，默认包含特定 git 子命令和 npm/pytest。
- `SESSION_CONTINUITY`：会话连续性开关。
- `CB_NO_PROGRESS_THRESHOLD`：熔断器无进展阈值。

**部署要点：**
- 确保所有依赖已安装（Claude Code CLI、tmux、jq 等）。
- 对于无人值守运行，建议设置 `CB_AUTO_RESET=true` 和适当的速率限制。
- 沙箱执行时，确保 Docker 或 E2B 环境正确配置。

## 限制、风险与许可证

**限制：**
- 依赖 Claude Code CLI，其可用性和行为可能变化。
- 自主循环可能消耗大量 API token，需谨慎设置速率限制。
- 沙箱同步（E2B）不支持沙箱内提交的同步。
- 多提供商支持（如 Codex、Gemini）仍在规划中，当前仅支持 Claude。

**风险：**
- 自主代理可能执行意外操作，建议使用沙箱和工具权限限制。
- GitHub Issue 内容被视为不可信输入，需注意提示注入风险。
- 熔断器可能误判，导致提前退出或过度等待。

**许可证：** MIT License。

## 官方链接

- GitHub 仓库：https://github.com/frankbria/ralph-claude-code
- Claude Code：https://claude.ai/code
- Ralph 技术介绍：https://ghuntley.com/ralph/

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档（docs/ 目录）、CONTRIBUTING.md。
- 分析时间：2026-06-15（基于仓库内容中的日期）。