一、名词解释Ralph全称Ralph for Claude Code是一个为 Claude Code CLI 打造的自主开发循环框架。它驱动 Claude Code 按照预设的任务清单反复执行编码任务直到所有需求完成或触发退出条件。Claude CodeAnthropic 官方发布的命令行 AI 编程助手安装后通过claude命令在终端中交互。Loop一次循环指 Ralph 调用 Claude Code 执行一轮任务、分析输出、更新状态的完整过程。Circuit Breaker熔断器一种保护机制当检测到连续无进展、重复错误或输出衰退时自动中止循环防止 API 费用无谓消耗。PRDProduct Requirements Document产品需求文档。Exit Signal退出信号Claude 输出中表示 “任务已完成” 的特征文本Ralph 通过分析这些信号决定何时停止。PROMPT.mdRalph 项目的核心文件包含开发者对 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-loopRalph 便会Step1读取PROMPT.md和fix_plan.md拼接为 Claude 的输入Step2调用claudeCLI 执行开发任务输出保存到logs/loop_N.logStep3分析输出内容完成信号、文件变更、错误数量计算完成信心指数Step4检查退出条件连续 done 信号、高信心值、熔断器状态Step5若未满足退出条件延时 5 秒后进入下一轮循环。[作者注Ralph 并不会修改用户的 PROMPT.md 文件它只是读取。Claude 的输出可能会修改项目代码文件Ralph 通过 git diff 检测变更。]四、功能模块Windows 版提供四条命令覆盖从项目初始化到自主开发的完整流程命令参数功能ralph-setup项目名创建项目目录结构、模板文件PROMPT.md、fix_plan.md、AGENT.md初始化 git 仓库ralph-importPRD文件路径[项目名]调用 Claude Code 将产品需求文档自动转换为 Ralph 格式的项目文件ralph-loop见下表启动自主开发循环驱动 Claude Code 反复执行任务ralph-monitor-RefreshInterval 秒在独立终端窗口中显示实时执行仪表盘表(1) Windows 版 Ralph 命令一览4.1 ralph-loop 参数参数类型默认值说明-MaxLoopsint50最大循环轮数-MaxCallsPerHourint100每小时最大 API 调用次数-LoopTimeoutint900单轮循环超时时间秒-PromptFilestringPROMPT.md自定义 Prompt 文件路径-ExitOnDoneswitchfalse检测到 done 信号后立即退出-NoCircuitBreakerswitchfalse禁用熔断器-Verboseswitchfalse输出详细调试日志-Monitorswitchfalse自动启动监控面板-Statusswitch-显示当前状态后退出-ResetCircuitswitch-重置熔断器状态-CircuitStatusswitch-查看熔断器详细状态-Helpswitch-显示帮助信息表(2) ralph-loop 参数列表4.2 核心保护机制限速控制以小时为单位追踪 API 调用次数达到上限后自动等待至下一个整点。同时追踪 Claude API 的 500 次/5 小时硬限制提前预警。熔断器Circuit Breaker模拟电气熔断器的三态模型——CLOSED正常→ HALF_OPEN试探恢复→ OPEN熔断中止。触发条件包括连续无文件变更、连续相同错误、输出量衰减超过阈值。退出检测通过正则匹配和可选的---RALPH_STATUS---结构化标记识别 Claude 的 “任务完成” 信号。累积多个信号且信心值达标后才真正退出避免误判。五、依赖环境依赖项版本要求获取方式Windows10 / 11x64-PowerShell7推荐winget install Microsoft.PowerShellClaude Code CLI最新版npm install -g anthropic-ai/claude-codeGit for Windows2.xwinget install Git.Git表(3) Windows 版 Ralph 依赖环境[作者注Windows PowerShell 5.1 理论可运行但部分 cmdlet 行为存在差异建议使用 PowerShell 7。安装完 Claude Code CLI 后需执行claude login完成认证。]六、配置文件说明6.1 项目级配置文件需用户手动编辑文件作用是否必需PROMPT.md开发指令与需求描述Claude 的执行依据必需fix_plan.md优先级任务清单Checkbox 格式Claude 按此逐一完成推荐AGENT.md构建/运行/测试命令说明推荐表(4) 用户手动编辑的配置文件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}}表(5) .ralph_config.json 默认配置6.3 Ralph 运行时状态文件自动生成无需手动编辑文件作用.ralph_status.json当前运行状态供 ralph-monitor 读取.exit_signals.json退出信号累积记录连续 done 计数、信心值.circuit_breaker_state熔断器当前状态和计数.circuit_breaker_history熔断器状态变迁历史最近 20 次.call_count/.call_timestampAPI 小时调用计数与时间戳.five_hour_calls.json5 小时窗口调用追踪.claude_progress.json当前循环 Claude 实时输出进度表(6) Ralph 运行时自动生成的状态文件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 仓库图(1) Ralph 项目目录结构七、安装与使用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改为$PromptFile2 中等函数引用父作用域变量封装性差Invoke-ClaudeCode函数内部直接使用脚本级变量$PromptFile和$FIX_PLAN_FILE若函数被迁移至模块中将直接失效为函数新增-PromptFile和-FixPlanFile参数调用处显式传参3 中等-Verbose参数形同虚设参数已定义但脚本中无任何引用用户传入后毫无效果在配置加载和每轮循环分析两处增加if ($Verbose) { Write-Log DEBUG ... }逻辑4 低$script:RalphStartTime死代码脚本级变量已赋值但从未读取主循环开始时记录时间戳执行结束时输出总耗时分钟表(7) ralph_loop.ps1 修改清单8.2 ralph_import.ps1PRD 导入脚本6 处修改#严重程度问题描述修复方式5 中等正则表达式\n不匹配 Windows 换行符\r\n6 处文件提取正则使用了仅匹配 LF 的\n而 Windows 的Get-Content -Raw保留文件原始换行符\r\n导致 PROMPT.md、fix_plan.md、specs/requirements.md 三个文件的提取全部失败全部改为\r?\n兼容 LF 与 CRLF表(8) ralph_import.ps1 修改清单8.3 install.ps1安装脚本4 处修改#严重程度问题描述修复方式6 中等生成的 wrapper 脚本包含硬编码用户名路径安装时将$INSTALL_DIR的实际值如C:\Users\HaiMi\.ralph写死进 wrapper 脚本若安装包分发到其他机器或以其他用户身份运行会因路径不存在而失败改为$env:USERPROFILE\.ralph\bin\...运行时动态解析表(9) install.ps1 修改清单8.4 修改文件汇总文件修改项数影响范围ralph_loop.ps14核心循环变量名修复 参数化 Verbose 耗时统计ralph_import.ps16PRD 导入正则兼容性修复install.ps14安装wrapper 路径通用化表(10) 修改文件汇总[作者注除上述修改外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-ciCI 自动化配置在 Windows 版中不存在请使用ralph-setup和ralph-import代替。主线版的 bash 安装脚本install.sh替换为 PowerShell 版的install.ps1。十、总结至此你已对 Windows 版 Ralph for Claude Code 有了完整的了解。它是一个将 Claude Code 从 “单次问答工具” 升级为 “自主开发引擎” 的桥梁——你写需求它循环执行自动停止。本文基于 Windows 版 Ralph 源码修改后撰写修复了 6 个影响正常使用的 bug含 1 个致命崩溃 bug修改后的完整代码包已随文提供。若在使用中遇到其他问题欢迎在评论区交流。
