一、名词解释

  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： 调用 claude CLI 执行开发任务，输出保存到 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 <秒>	在独立终端窗口中显示实时执行仪表盘

表(1) Windows 版 Ralph 命令一览

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	-	显示帮助信息

表(2) ralph-loop 参数列表

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

表(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_timestamp	API 小时调用计数与时间戳
.five_hour_calls.json	5 小时窗口调用追踪
.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 -Verbose

7.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
- 测试: Jest

7.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 死代码：脚本级变量已赋值但从未读取	主循环开始时记录时间戳，执行结束时输出总耗时（分钟）

表(7) ralph_loop.ps1 修改清单

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) 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.ps1	4	核心循环（变量名修复 + 参数化 + Verbose + 耗时统计）
ralph_import.ps1	6	PRD 导入（正则兼容性修复）
install.ps1	4	安装（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-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），修改后的完整代码包已随文提供。若在使用中遇到其他问题，欢迎在评论区交流。