Ralph开发循环调试指南：问题诊断与解决方案

循环提前终止排查方案

问题现象：Ralph开发循环在未完成项目时意外终止。
根本原因：v0.9.9前版本仅依赖单一完成指示器判断，易导致误判。
解决步骤：

1. 升级至v0.9.9+版本，启用双重条件检查（通过完成指示器与显式信号共同判断）
2. 系统同时验证两个条件：
   • 条件1：完成指示器数量≥2（自然语言模式检测）
   • 条件2：Claude明确设置EXIT_SIGNAL: true
3. 示例场景：当Claude输出"功能开发中"时，即使完成指示器达3个，因EXIT_SIGNAL: false，循环将继续执行。

卡顿循环检测与修复方法

问题现象：Ralph陷入重复相同错误的无限循环。
根本原因：错误检测机制未有效过滤表面正常但实际异常的响应。
解决步骤：

1. 启用内置两阶段错误检测：
   • 阶段1：过滤"is_error": false等JSON字段伪装的错误
   • 阶段2：通过上下文模式识别实际执行异常
2. 执行状态检查命令：

# 查看当前循环状态
ralph --status

# 实时监控错误日志
tail -f logs/ralph.log

API限流应对技巧

问题现象：遭遇Claude API的5小时使用限制，导致开发中断。
根本原因：API调用频率超过服务提供商限制。
解决步骤：

1. 系统自动检测限流错误后提供选项：
   • 选项1：等待60分钟限制重置（带实时倒计时）
   • 选项2：30秒优雅退出当前循环
2. 提前配置调用阈值预防限流：

# 设置每小时最大调用次数
ralph --calls 50

# 启用集成监控模式
ralph --monitor --calls 50

会话上下文丢失恢复方案

问题现象：跨循环迭代时丢失关键开发上下文。
根本原因：会话状态未有效持久化或传输中断。
解决步骤：

1. 默认启用会话连续性：

ralph --monitor

2. 特殊场景处理：
   • 启动全新会话（清除历史上下文）：ralph --no-continue
   • 手动重置当前会话：ralph --reset-session

长时任务超时配置方法

问题现象：复杂任务因执行时间过长触发超时终止。
根本原因：默认超时阈值不适应大型任务需求。
解决步骤：

1. 根据任务复杂度调整超时参数：

# 设置30分钟超时（单位：分钟）
ralph --timeout 30

# 启用详细进度更新（每5分钟）
ralph --verbose --timeout 60

电路断路器状态管理

问题现象：API错误或速率限制导致持续失败。
根本原因：缺乏故障隔离机制导致级联失败。
解决步骤：

1. 理解断路器工作机制：
   • 触发条件：3个无进展循环或5个相同错误循环
   • 恢复策略：通过半开状态逐步恢复服务调用
2. 状态管理命令：

# 查看当前断路器状态
ralph --circuit-status

# 手动重置断路器
ralph --reset-circuit

项目初始化失败修复指南

问题现象：PRD文档导入失败或项目结构创建不完整。
根本原因：需求文档格式错误或依赖组件缺失。
解决步骤：

1. 重新导入PRD文档：

ralph-import product-requirements.md my-project

2. 手动创建标准项目结构：

ralph-setup new-project

开发循环优化配置策略

核心优化方向：通过合理配置提升开发效率与稳定性。
关键配置项：

1. 循环控制参数（在~/.ralph/ralph_loop.sh中修改）：

MAX_CONSECUTIVE_TEST_LOOPS=3      # 连续测试循环阈值
MAX_CONSECUTIVE_DONE_SIGNALS=2    # 连续完成信号阈值
TEST_PERCENTAGE_THRESHOLD=30      # 测试循环占比阈值

2. 提示文件优化：
   • PROMPT.md明确项目需求边界
   • @fix_plan.md设置任务优先级
   • specs/目录提供技术规范细节