一、名词解释
Ralph：全称Ralph for Claude Code，是一个为 Claude Code CLI 打造的自主开发循环框架。它驱动 Claude Code 按照预设的任务清单反复执行编码任务，直到所有需求完成或触发退出条件。
Claude Code：Anthropic 官方发布的命令行 AI 编程助手，安装后通过claude命令在终端中交互。
Loop：一次循环，指 Ralph 调用 Claude Code 执行一轮任务、分析输出、更新状态的完整过程。
Circuit Breaker（熔断器）：一种保护机制，当检测到连续无进展、重复错误或输出衰退时，自动中止循环，防止 API 费用无谓消耗。
PRD：Product Requirements Document，产品需求文档。
Exit Signal：退出信号，Claude 输出中表示 “任务已完成” 的特征文本，Ralph 通过分析这些信号决定何时停止。
PROMPT.md：Ralph 项目的核心文件，包含开发者对 Claude 下达的开发指令和需求描述。
@fix_plan.md：优先级任务清单，采用 Checkbox 格式，Claude 按照清单逐一完成任务。
二、参考资料
1. Ralph 主线版（Linux/Bash）源码仓库
2. Windows 移植版源码仓库
3. Claude Code 官方文档
4. PowerShell 7 安装指南
5. PowerShell 7 国内镜像源
三、工具概述
3.1 背景
Ralph 主线版本（frankbria/ralph-claude-code）基于 Linux/Bash 编写，依赖 Unix 环境的timeout、kill、进程管理、文件权限等特性，无法直接在 Windows 上使用。本文描述的 Windows 版本由社区贡献者 jvdsouza 使用 PowerShell 重写，核心功能与主线版保持一致。
[作者注：Windows 版源码分支为claude/add-windows-support，与该仓库 main 分支的关系是一次性移植而非持续同步，部分主线新功能（如ralph-enable交互式向导）未被移植。]
3.2 核心工作原理
Ralph 的核心理念是“写需求 → 自动循环执行 → 自动停止”。用户只需编辑PROMPT.md（告诉 Claude 做什么）和@fix_plan.md（列出具体任务），然后运行ralph-loop，Ralph 便会：
Step1：读取PROMPT.md和@fix_plan.md，拼接为 Claude 的输入；
Step2：调用claudeCLI 执行开发任务，输出保存到logs/loop_N.log；
Step3：分析输出内容（完成信号、文件变更、错误数量），计算完成信心指数；
Step4：检查退出条件（连续 done 信号、高信心值、熔断器状态）；
Step5：若未满足退出条件，延时 5 秒后进入下一轮循环。
[作者注：Ralph 并不会修改用户的 PROMPT.md 文件，它只是读取。Claude 的输出可能会修改项目代码文件，Ralph 通过 git diff 检测变更。]
四、功能模块
Windows 版提供四条命令，覆盖从项目初始化到自主开发的完整流程：
| 命令 | 参数 | 功能 |
|---|---|---|
ralph-setup | <项目名> | 创建项目目录结构、模板文件（PROMPT.md、@fix_plan.md、@AGENT.md），初始化 git 仓库 |
ralph-import | <PRD文件路径>[项目名] | 调用 Claude Code 将产品需求文档自动转换为 Ralph 格式的项目文件 |
ralph-loop | 见下表 | 启动自主开发循环，驱动 Claude Code 反复执行任务 |
ralph-monitor | -RefreshInterval <秒> | 在独立终端窗口中显示实时执行仪表盘 |
4.1 ralph-loop 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
-MaxLoops | int | 50 | 最大循环轮数 |
-MaxCallsPerHour | int | 100 | 每小时最大 API 调用次数 |
-LoopTimeout | int | 900 | 单轮循环超时时间（秒） |
-PromptFile | string | PROMPT.md | 自定义 Prompt 文件路径 |
-ExitOnDone | switch | false | 检测到 done 信号后立即退出 |
-NoCircuitBreaker | switch | false | 禁用熔断器 |
-Verbose | switch | false | 输出详细调试日志 |
-Monitor | switch | false | 自动启动监控面板 |
-Status | switch | - | 显示当前状态后退出 |
-ResetCircuit | switch | - | 重置熔断器状态 |
-CircuitStatus | switch | - | 查看熔断器详细状态 |
-Help | switch | - | 显示帮助信息 |
4.2 核心保护机制
限速控制：以小时为单位追踪 API 调用次数，达到上限后自动等待至下一个整点。同时追踪 Claude API 的 500 次/5 小时硬限制，提前预警。
熔断器（Circuit Breaker）：模拟电气熔断器的三态模型——CLOSED（正常）→ HALF_OPEN（试探恢复）→ OPEN（熔断中止）。触发条件包括连续无文件变更、连续相同错误、输出量衰减超过阈值。
退出检测：通过正则匹配和可选的---RALPH_STATUS---结构化标记，识别 Claude 的 “任务完成” 信号。累积多个信号且信心值达标后才真正退出，避免误判。
五、依赖环境
| 依赖项 | 版本要求 | 获取方式 |
|---|---|---|
| Windows | 10 / 11（x64） | - |
| PowerShell | 7+（推荐） | winget install Microsoft.PowerShell |
| Claude Code CLI | 最新版 | npm install -g @anthropic-ai/claude-code |
| Git for Windows | 2.x+ | winget install Git.Git |
[作者注：Windows PowerShell 5.1 理论可运行，但部分 cmdlet 行为存在差异，建议使用 PowerShell 7+。安装完 Claude Code CLI 后需执行claude login完成认证。]
六、配置文件说明
6.1 项目级配置文件（需用户手动编辑）
| 文件 | 作用 | 是否必需 |
|---|---|---|
PROMPT.md | 开发指令与需求描述，Claude 的执行依据 | 必需 |
@fix_plan.md | 优先级任务清单（Checkbox 格式），Claude 按此逐一完成 | 推荐 |
@AGENT.md | 构建/运行/测试命令说明 | 推荐 |
6.2 .ralph_config.json 结构
该文件由ralph-loop首次运行时自动生成，用户可手动编辑来调整行为：
{"max_calls_per_hour":100,"loop_timeout_seconds":900,"max_loops":50,"circuit_breaker":{"enabled":true,"max_no_progress_loops":3,"max_same_error_loops":5,"output_decline_threshold":0.7},"exit_detection":{"consecutive_done_signals":2,"test_only_loop_threshold":3}}6.3 Ralph 运行时状态文件（自动生成，无需手动编辑）
| 文件 | 作用 |
|---|---|
.ralph_status.json | 当前运行状态（供 ralph-monitor 读取） |
.exit_signals.json | 退出信号累积记录（连续 done 计数、信心值） |
.circuit_breaker_state | 熔断器当前状态和计数 |
.circuit_breaker_history | 熔断器状态变迁历史（最近 20 次） |
.call_count/.call_timestamp | API 小时调用计数与时间戳 |
.five_hour_calls.json | 5 小时窗口调用追踪 |
.claude_progress.json | 当前循环 Claude 实时输出进度 |
6.4 项目目录结构
ralph-setup my-project执行后生成的完整目录结构：
my-project/ ├── PROMPT.md # 开发指令（必需） ├── @fix_plan.md # 任务清单 ├── @AGENT.md # 构建/测试命令 ├── .ralph_config.json # Ralph 配置（自动生成） ├── .gitignore # Git 忽略规则（自动生成） ├── specs/ # 规格文档目录 │ └── stdlib/ ├── src/ # 源代码目录 ├── examples/ # 示例代码目录 ├── tests/ # 测试代码目录 ├── logs/ # 运行日志目录 │ ├── loop_N_*.log # 每次循环的 Claude 完整输出 │ ├── analysis.log # 循环分析摘要记录 │ ├── circuit_breaker.log # 熔断器状态日志 │ └── ralph.log # Ralph 主日志 ├── docs/ # 文档目录 │ └── generated/ └── .git/ # Git 仓库七、安装与使用
7.1 安装步骤
# Step1：克隆 Windows 版仓库git clone https://github.com/jvdsouza/windows-ralph-claude.git cd windows-ralph-claude# Step2：运行安装脚本.\install.ps1# Step3：重启 PowerShell 使 PATH 生效安装脚本完成以下操作：
①创建%USERPROFILE%\.ralph\bin\目录，复制主脚本和库文件；
②创建%USERPROFILE%\.ralph\templates\目录，复制项目模板；
③生成 4 个 wrapper 脚本（ralph-loop、ralph-monitor、ralph-setup、ralph-import）；
④将%USERPROFILE%\.ralph\bin\添加至用户级 PATH 环境变量。
7.2 新建项目并启动
# 创建项目ralph-setup my-project cd my-project# 编辑需求文件notepad PROMPT.md notepad @fix_plan.md# 启动自主开发循环ralph-loop# 或启动并自动打开监控ralph-loop-Monitor-Verbose7.3 从 PRD 文档导入
ralph-import my-product-spec.md my-project此命令会调用 Claude Code 分析 PRD 文档内容，自动生成PROMPT.md、@fix_plan.md和specs/requirements.md。
7.4 PROMPT.md 示例
# Project: 用户管理系统 ## 概述 构建一个 RESTful API 的用户管理系统 ## 需求 - [ ] 用户注册/登录接口 - [ ] JWT 认证中间件 - [ ] 用户 CRUD API - [ ] 数据库迁移脚本 - [ ] 单元测试覆盖率 > 80% ## 技术约束 - 语言: TypeScript - 框架: Express.js - 数据库: PostgreSQL - 测试: Jest7.5 @fix_plan.md 示例
## 高优先级 - [ ] 初始化项目结构和 npm 依赖 - [ ] 实现数据库连接和迁移脚本 - [ ] 实现用户数据模型 - [ ] 实现用户注册 API - [ ] 实现用户登录和 JWT 签发 ## 中优先级 - [ ] 添加输入验证中间件 - [ ] 编写用户模块单元测试 ## 低优先级 - [ ] 生成 Swagger API 文档 ## 已完成 - [x] 项目需求分析八、源码修改清单
我们在实际部署和使用 Windows 版 Ralph 的过程中，发现并修复了若干 bug 与代码质量问题。本节详细列出所有修改，修改后的完整源码包随本文提供。
[作者注：以下修改均以 Windows 版源码仓库（jvdsouza/windows-ralph-claude, 分支 claude/add-windows-support）为基础。修改同时应用于源仓库文件（windows-ralph-claude*.ps1）和安装后的文件（%USERPROFILE%.ralph\bin*_main.ps1）。]
8.1 ralph_loop.ps1（主循环脚本，4 处修改）
| # | 严重程度 | 问题描述 | 修复方式 |
|---|---|---|---|
| 1 | 🔴 致命 | 变量名不匹配导致程序崩溃：脚本参数定义为$PromptFile（第 8 行），但第 690 行的前置校验处误写为$PROMPT_FILE。PowerShell 中下划线使两者成为不同变量，$PROMPT_FILE始终为$null，导致Test-Path收到空值抛出异常。表现为运行ralph-loop即报错退出。 | 将$PROMPT_FILE改为$PromptFile |
| 2 | 🟡 中等 | 函数引用父作用域变量，封装性差：Invoke-ClaudeCode函数内部直接使用脚本级变量$PromptFile和$FIX_PLAN_FILE，若函数被迁移至模块中将直接失效 | 为函数新增-PromptFile和-FixPlanFile参数，调用处显式传参 |
| 3 | 🟡 中等 | -Verbose参数形同虚设：参数已定义但脚本中无任何引用，用户传入后毫无效果 | 在配置加载和每轮循环分析两处增加if ($Verbose) { Write-Log "DEBUG" ... }逻辑 |
| 4 | 🔵 低 | $script:RalphStartTime死代码：脚本级变量已赋值但从未读取 | 主循环开始时记录时间戳，执行结束时输出总耗时（分钟） |
8.2 ralph_import.ps1（PRD 导入脚本，6 处修改）
| # | 严重程度 | 问题描述 | 修复方式 |
|---|---|---|---|
| 5 | 🟡 中等 | 正则表达式\n不匹配 Windows 换行符\r\n：6 处文件提取正则使用了仅匹配 LF 的\n，而 Windows 的Get-Content -Raw保留文件原始换行符\r\n，导致 PROMPT.md、@fix_plan.md、specs/requirements.md 三个文件的提取全部失败 | 全部改为\r?\n（兼容 LF 与 CRLF） |
8.3 install.ps1（安装脚本，4 处修改）
| # | 严重程度 | 问题描述 | 修复方式 |
|---|---|---|---|
| 6 | 🟡 中等 | 生成的 wrapper 脚本包含硬编码用户名路径：安装时将$INSTALL_DIR的实际值（如C:\Users\HaiMi\.ralph）写死进 wrapper 脚本，若安装包分发到其他机器或以其他用户身份运行会因路径不存在而失败 | 改为$env:USERPROFILE\.ralph\bin\...（运行时动态解析） |
8.4 修改文件汇总
| 文件 | 修改项数 | 影响范围 |
|---|---|---|
ralph_loop.ps1 | 4 | 核心循环（变量名修复 + 参数化 + Verbose + 耗时统计） |
ralph_import.ps1 | 6 | PRD 导入（正则兼容性修复） |
install.ps1 | 4 | 安装（wrapper 路径通用化） |
[作者注：除上述修改外，ralph_monitor.ps1、setup.ps1、response_analyzer.ps1、circuit_breaker.ps1四个模块经审计未发现变量名或逻辑 bug。]
九、注意事项
① Claude Code 认证：首次使用前务必执行claude login完成 Anthropic 账号认证，否则 ralph-loop 无法调用 API。
② API 费用：ralph-loop 会持续调用 Claude API，每轮消耗不等数量的 token。建议先用-MaxLoops 5 -MaxCallsPerHour 10小参数试跑，确认没问题再放开限制。
③ 熔断器重置：若循环被熔断器中止（通常是代码反复出错或 Claude 无进展），使用ralph-loop -ResetCircuit重置后重新运行。
④ Git 状态：Ralph 通过git diff检测文件变更。确保在 git 仓库中运行，且尽量不要有未跟踪的脏文件干扰判定。
⑤ PROMPT.md 内容：至少包含一个需求描述。如果文件为空或不存在，ralph-loop 会在启动校验阶段报错退出。
⑥ 与 Linux 主线版的差异：主线版的ralph-enable（交互式配置向导）和ralph-enable-ci（CI 自动化配置）在 Windows 版中不存在，请使用ralph-setup和ralph-import代替。主线版的 bash 安装脚本install.sh替换为 PowerShell 版的install.ps1。
十、总结
至此，你已对 Windows 版 Ralph for Claude Code 有了完整的了解。它是一个将 Claude Code 从 “单次问答工具” 升级为 “自主开发引擎” 的桥梁——你写需求，它循环执行，自动停止。
本文基于 Windows 版 Ralph 源码修改后撰写，修复了 6 个影响正常使用的 bug（含 1 个致命崩溃 bug），修改后的完整代码包已随文提供。若在使用中遇到其他问题，欢迎在评论区交流。
