Ralph 自治开发循环用例体系解析从 Actor 目录到熔断器状态机的完整场景建模【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-codeRalph 是一个面向 Claude Code 的自治 AI 开发循环系统核心目标是以最少的人工介入和 Token 浪费完成软件项目实现。本文基于仓库中的docs/archive/2025-10-milestones/USE_CASES.md遵循 Alistair Cockburn 用例方法论编写的 6 个用例与 Actor 目录结合ralph_loop.sh、lib/response_analyzer.sh、lib/circuit_breaker.sh、ralph_monitor.sh等源码实现完整解读 Ralph 的角色体系、用例层级、主成功场景与扩展流程、目标层级、成功度量与术语表。读完本文你将能理解 Ralph 每一次循环迭代内部发生了什么、熔断器如何在三次无进展后打开、响应分析器如何计算置信度并触发退出以及如何通过ralph --reset-circuit等命令手动介入。一、系统概述自治开发循环的参与者模型系统目标与角色根据用例文档Ralph 系统的核心定义如下系统名称Ralph —— 自治 AI 开发循环Autonomous AI Development Loop系统目标以最少的人工干预和 Token 浪费完成软件项目实现主执行者Primary ActorRalph —— 编排 Claude Code 的 bash 脚本辅助执行者Supporting ActorsClaude CodeAI 开发引擎、Human Developer发起者与审查者该文档归档于 docs/archive/2025-10-milestones/属于 Phase 2 里程碑2025-10-01完成时编写的用例文档是当前IMPLEMENTATION_STATUS.md与IMPLEMENTATION_PLAN.md所追踪方案的早期行为规格。Actor 能力与约束目录执行者类型核心目标关键能力关键约束Ralph系统持续执行开发循环直到项目完成或熔断器打开携带 PROMPT.md 指令执行 Claude Code分析响应中的完成信号跟踪文件变更与进度管理调用频率限制每小时 100 次通过熔断器检测停滞工作完成时优雅退出不能修改项目需求必须遵守 API 限流熔断器打开时不得覆盖需要有效的 PROMPT.md 与 fix_plan.mdClaude CodeAI 系统按 PROMPT.md 指令实现特性、修复缺陷、运行测试读/写/编辑文件执行 bash 命令运行测试并分析结果搜索代码库输出结构化状态报告每日 5 小时 API 限制Token 上下文限制不能访问外部网络除经批准的工具必须遵循 PROMPT.mdHuman Developer人类发起 Ralph、审查结果、必要时介入创建 PROMPT.md 与 fix_plan.md启动/停止 Ralph重置熔断器审查代码变更受阻时提供澄清自治循环执行期间不在场Ralph 运行时不能修改文件合并前必须审查变更从源码看Ralph 的无法覆盖打开的熔断器约束由 lib/circuit_breaker.sh 的can_execute()与 ralph_loop.sh 主循环中的should_halt_execution检查共同保障一旦状态文件.ralph/.circuit_breaker_state为 OPEN循环直接 break 并提示用户运行ralph --reset-circuit。二、用例层级一个系统目标五个子目标用例文档将系统目标完成项目实现分解为 5 个子目标每个子目标对应一个用例执行开发循环UC-1检测完成条件UC-2防止资源浪费UC-3处理错误条件UC-4提供可观测性UC-5外加一个纯人工触发的用例 UC-6重置熔断器。这 6 个用例构成了 Ralph 行为契约的完整骨架下文逐一展开。三、UC-1执行开发循环Execute Development Loop前置条件与成功保证前置条件全部满足才能启动循环PROMPT.md 存在且有效ralph_loop.sh中启动时若$PROMPT_FILE.ralph/PROMPT.md不存在会直接报错并给出修复指引见 ralph_loop.shfix_plan.md 存在且至少包含一个任务Claude Code CLI 已安装且可访问由validate_claude_command校验ralph_loop.shgit 仓库已初始化进度检测依赖 git diff成功保证Postcondition一个开发任务完成文件被修改并提交若有变更状态被记录到日志与 status.json熔断器状态更新退出信号被分析与记录主成功场景14 步Ralph 读取 PROMPT.mdRalph 检查熔断器状态必须为 CLOSED 或 HALF_OPENRalph 确认限流允许执行Ralph 携带 PROMPT.md 执行 Claude CodeClaude Code 读取 fix_plan.md 并选择任务Claude Code 实现任务修改文件Claude Code 运行相关测试Claude Code 输出 RALPH_STATUS 块Ralph 分析 Claude 的响应analyze_responseRalph 更新.exit_signals文件update_exit_signalsRalph 在熔断器中记录循环结果record_loop_resultRalph 递增调用计数器Ralph 将完成情况记录到 status.json 与 logs/若无退出条件Ralph 进入下一轮循环源码印证主循环位于 ralph_loop.sh 的while true中每轮迭代依次执行日志轮转 → 更新会话时间戳 →init_call_tracking步骤 2、3 对应的熔断器初始化和计数重置→should_halt_execution→can_make_call→should_exit_gracefully→update_status→create_backup→execute_claude_code→track_metrics。其中execute_claude_coderalph_loop.sh内部完成步骤 4–11构建 Claude 命令、执行、analyze_response、update_exit_signals、统计files_changed与has_errors、最后调用record_loop_result。扩展流程Extensions扩展编号触发条件处理行为2a熔断器为 OPEN显示熔断器状态 → 展示用户指引查看日志、重置等→ 以退出码 1 退出用例结束3a超出每小时调用数上限计算距下个小时重置的秒数 → 显示倒计时 → 等待重置 → 回到步骤 43b达到 API 5 小时限制在 Claude 输出中检测 rate limit 错误 → 询问用户重试还是退出选重试等待 5 分钟后继续选退出则优雅退出用例结束4aClaude Code 执行失败记录错误到logs/ralph_error.log→ 将 status.json 更新为 failed → 下一轮循环重试若连续 5 次失败则熔断器打开 → 回到步骤 29a响应分析检测到 EXIT_SIGNALtrue记录成功完成 → 将 status.json 更新为 complete → 显示完成摘要 → 以退出码 0 退出用例结束11a熔断器打开检测不到进展记录熔断器打开 → 将 status.json 更新为 circuit_open → 向用户显示指引 → 以退出码 1 退出用例结束执行频率循环持续执行直到完成或满足退出条件。性能目标正常条件下每个循环应在 5 分钟内完成。值得注意扩展 3a/3b 在当前源码中对应两类不同的限流。每小时 100 次调用限制由.ralph/.call_count、.ralph/.last_reset驱动can_make_call与wait_for_resetralph_loop.sh5 小时 API 限制则由 ralph_loop.sh 的execute_claude_code失败分支分层检测——先查rate_limit_event的status:rejected再以文本兜底匹配 5.*hour.*limit命中后返回码 2主循环展示 30 秒超时的选择菜单等待 60 分钟或退出。四、UC-2检测项目完成Detect Project Completion主执行者与职责主执行者Ralph经由lib/response_analyzer.sh利益相关者Human Developer希望可靠退出、Claude Code发出完成信号成功保证完成状态被准确判定.exit_signals文件记录决策置信度分数被计算0–100EXIT_SIGNAL 被正确设置true/false主成功场景Ralph 读取 Claude Code 输出文件Ralph 检查结构化 RALPH_STATUS 块Ralph 发现 STATUS: COMPLETE 且 EXIT_SIGNAL: trueRalph 将置信度分数设为 100Ralph 在.response_analysis中将 exit_signal 设为 trueRalph 用 done_signals 数组更新.exit_signalsRalph 在下一轮循环检查时触发优雅退出扩展流程扩展编号触发条件处理行为2a未找到结构化输出搜索自然语言完成关键词命中 10 置信度→ 检查 nothing to do 模式命中 15 置信度且 exit_signaltrue→ 跳到步骤 63aSTATUS 为 IN_PROGRESS检查 WORK_TYPE 字段连续第 3 轮为 TESTING 则标记 test_only连续第 3 轮 FILES_MODIFIED0 则熔断器打开exit_signal 设为 false → 跳到步骤 63bSTATUS 为 BLOCKED递增 blocked_loops 计数器若 3 则建议人工介入exit_signal 设为 false → 跳到步骤 66a置信度 40即使没有显式 EXIT_SIGNAL 也设置 exit_signaltrue记录高置信度完成检测 → 跳到步骤 7源码印证响应分析逻辑实现在 lib/response_analyzer.sh 的analyze_response()。它支持三种 JSON 格式扁平格式、Claude CLI 对象格式、Claude CLI 数组格式与文本兜底解析关键词与模式定义于文件头部COMPLETION_KEYWORDSdone、complete、finished、all tasks complete、project complete、ready for reviewNO_WORK_PATTERNSnothing to do、no changes、already implemented、up to dateTEST_ONLY_PATTERNSnpm test、bats、pytest、jest、cargo test、go test、running testsupdate_exit_signals()lib/response_analyzer.sh维护.ralph/.exit_signals中的三个滚动数组test_only_loops、done_signals、completion_indicators各保留最近 5 条。主循环中的should_exit_gracefully()ralph_loop.sh随后据此判定退出理由连续测试轮数 3test_saturation、完成信号 2completion_signals、连续 5 次 EXIT_SIGNALtrue 的安全熔断safety_circuit_breaker、完成指示 2 且 Claude 显式 EXIT_SIGNALtrueproject_complete、以及 fix_plan.md 全部复选框完成plan_complete。关于扩展 6a 中的置信度阈值当前源码在 JSON 模式下对置信度的处理已演化为显式 EXIT_SIGNAL 优先.response_analysis中.analysis.exit_signal代表 Claude 的显式意图仅当 Claude 明确 EXIT_SIGNALtrue 时才可能触发 project_complete 退出避免启发式误判导致的提前退出见 ralph_loop.sh 的注释。性能目标分析应在 1 秒内完成。五、UC-3防止资源浪费——熔断器Circuit Breaker设计意图熔断器模式基于 Michael Nygard《Release It!》中的经典模式用于检测停滞stagnation即没有文件变更并阻止失控循环烧掉 Token。成功保证失控循环被检测并中止Token 浪费被最小化 1K 浪费 Token中止时给出清晰的用户指引熔断器状态跨重启持久化主成功场景与状态机Ralph 将熔断器初始化为 CLOSED每轮循环后调用record_loop_result()Ralph 通过 git diff 统计 files_changedRalph 从 Claude 输出检测 has_errorsRalph 计算 output_length熔断器更新 consecutive_no_progress 计数器consecutive_no_progress 为 0检测到进展熔断器保持 CLOSEDRalph 进入下一轮循环状态机源码lib/circuit_breaker.sh 定义三个状态与四个可配置阈值状态含义进入条件CLOSED正常运行检测到进展初始状态HALF_OPEN 下恢复进展时回到 CLOSEDHALF_OPEN监控模式检查恢复连续 2 轮无进展OPEN检测到失败执行中止无进展阈值、同错误阈值、权限拒绝阈值任一达到可配置阈值默认值均可用环境变量覆盖CB_NO_PROGRESS_THRESHOLD3 # 连续 N 轮无进展则打开 CB_SAME_ERROR_THRESHOLD5 # 连续 N 轮同一错误则打开 CB_OUTPUT_DECLINE_THRESHOLD70 # 输出量下降超过 70% 则打开 CB_PERMISSION_DENIAL_THRESHOLD2 # 连续 N 轮权限被拒则打开 CB_COOLDOWN_MINUTES30 # OPEN → HALF_OPEN 自动恢复的冷却时间 CB_AUTO_RESETfalse # 启动时是否跳过冷却直接重置为 CLOSED扩展流程扩展编号触发条件状态迁移行为6a本轮无文件变更consecutive_no_progress 1保持 CLOSED继续到步骤 96b连续第 2 轮无变更consecutive_no_progress 2 →HALF_OPEN记录 monitoring mode 警告6c连续第 3 轮无变更consecutive_no_progress 3 →OPEN显示停止消息与指引退出码 1用例结束6d连续第 5 轮检测到同一错误consecutive_same_error 5 →OPEN原因为 Same error repeated in 5 consecutive loops转 6c37a检测到文件变更恢复consecutive_no_progress 重置为 0若为 HALF_OPEN 则转 CLOSED记录 circuit recovered继续到步骤 9源码印证record_loop_result()lib/circuit_breaker.sh将进展定义为四个来源的并集git diff 检出未提交变更、响应分析出现has_completion_signalSTATUS: COMPLETE 或显式 EXIT_SIGNAL、Claude 报告 files_modified 0、以及Claude 在提问不算进展也不算停滞抑制 no-progress 计数器见 Issue #190。状态文件.ralph/.circuit_breaker_state持久化state、consecutive_no_progress、consecutive_same_error、total_opens、reason、opened_at等字段而.ralph/.circuit_breaker_history以 JSON 数组记录每次状态迁移log_circuit_transition。性能目标熔断器检查 100ms。六、UC-4处理 API 限流Handle API Rate Limits成功保证遵守 API 限流调用计数器被准确跟踪小时级重置自动处理用户被告知等待时间主成功场景Ralph 检查当前小时YYYYMMDDHH 格式Ralph 读取.last_reset时间戳当前小时与 last_reset 相同Ralph 读取.call_countcall_count 为 45 100 上限Ralph 允许执行Ralph 将 call_count 递增为 46Ralph 将更新后的计数写入.call_count执行继续扩展流程扩展编号触发条件处理行为3a检测到新小时将 call_count 重置为 0 → 将当前小时写入.last_reset→ 记录 call counter reset for new hour → 回到步骤 55acall_count 达到或超过 100计算距下一小时的秒数 → 显示倒计时 Rate limit reached. Waiting HH:MM:SS... → 睡眠等待 → 重置计数器 → 回到步骤 65bClaude 返回 API 限流错误检测输出中的 rate_limit_error → 提示 API 5-hour limit reached. Retry? (y/n) → 输入 y 等待 5 分钟后重试输入 n 优雅退出用例结束源码印证小时级调用计数由init_call_tracking()ralph_loop.sh、can_make_call()ralph_loop.sh与wait_for_reset()ralph_loop.sh实现。MAX_CALLS_PER_HOUR默认 100可通过 CLI 参数--calls NUM或.ralphrc覆盖MAX_TOKENS_PER_HOUR默认 0禁用可设置以限制每小时累计 TokenToken 计数来自 Claude 输出的usage字段见extract_token_usage。5 小时限制的交互流程对应扩展 5b实现在 ralph_loop.sh返回码 2 分支30 秒无输入时自动选择等待以支持无人值守运行。性能目标限流检查 50ms。七、UC-5提供循环监控Provide Loop Monitoring主执行者与职责主执行者ralph-monitor.sh前置条件Ralph 正在运行ralph_loop.sh监控在独立终端启动主成功场景用户在独立终端启动 ralph-monitor.sh监控器每 2 秒读取一次 status.json监控器显示循环数、状态、时间戳监控器读取.call_count并显示 Calls: 45/100监控器读取.circuit_breaker_state并显示状态监控器读取.exit_signals并显示信号计数监控器检测到 status.json 更新监控器用新数据刷新显示循环继续回到步骤 2扩展流程扩展编号触发条件处理行为3astatus.json 尚不存在显示 Waiting for Ralph to start... → 睡眠 2 秒 → 回到步骤 25a熔断器为 OPEN以红色显示状态 → 显示熔断原因 → 显示 Execution halted 消息 → 继续到步骤 77aRalph 已退出检测最终状态 → 显示完成摘要 → 显示总循环数、时长、退出原因 → 监控器退出用例结束源码印证监控仪表盘实现在 ralph_monitor.sh 的display_status()REFRESH_INTERVAL2秒。除用例文档提到的字段外它还读取.ralph/progress.json展示 Claude 执行中的动画进度、沙箱状态Sandbox 区块仅在有沙箱提供方时显示与问题队列进度Issue Queue 区块仅当.ralph/queue.json存在时显示。若熔断器打开主循环会调用should_halt_execution显示红色的 EXECUTION HALTED: Circuit Breaker Opened 面板与排查指引lib/circuit_breaker.sh。另外ralph --monitor会在 tmux 中创建三窗格会话左Ralph 循环右上Claude 实时输出右下状态监控见 ralph_loop.sh 的setup_tmux_session。性能目标更新延迟 2 秒。八、UC-6重置熔断器手动介入主执行者Human Developer——这是全部 6 个用例中唯一以人类为主执行者的用例。前置条件熔断器为 OPENRalph 已中止执行用户已查阅日志并定位问题主成功场景11 步用户从 ralph-monitor 或日志发现熔断器打开用户查阅logs/ralph.log理解原因用户修复根本问题更新 fix_plan.md、修复错误等用户运行ralph --reset-circuitRalph 加载 circuit_breaker.sh 函数Ralph 调用reset_circuit_breaker(Manual reset by user)Ralph 将.circuit_breaker_state中的状态设为 CLOSEDRalph 将所有计数器重置为 0Ralph 记录 Circuit breaker reset to CLOSED stateRalph 显示成功消息用户可重新启动 Ralph 执行扩展流程扩展编号触发条件处理行为2a无法从日志确定原因运行ralph --status获取更多信息 → 检查.circuit_breaker_history的状态迁移记录 → 查阅最近的 Claude 输出文件 → 回到步骤 33a问题在 PROMPT.md 或 specs/编辑 PROMPT.md 澄清需求 → 用缺失信息更新 specs/ → 提交变更 → 回到步骤 43b问题是配置或环境安装缺失依赖 → 修复环境变量 → 验证配置 → 回到步骤 4源码印证ralph --reset-circuit在 ralph_loop.sh 中直接 sourcelib/circuit_breaker.sh并调用reset_circuit_breaker(Manual reset via command line)随后调用reset_session(manual_circuit_reset)清理会话状态。reset_circuit_breaker()本体lib/circuit_breaker.sh将状态文件重写为 CLOSED 并将所有计数器清零。若 OPEN 状态下未手动重置init_circuit_breaker()还会按CB_COOLDOWN_MINUTES默认 30 分钟自动过渡到 HALF_OPEN或按CB_AUTO_RESETtrue启动时直接回到 CLOSED。性能目标重置即时完成。九、目标层级Goal Hierarchy用例文档用一棵树完整呈现系统目标到子目标、成功与失败判据的映射SYSTEM GOAL: Complete project implementation with minimal token waste ├─ SUB-GOAL 1: Execute development loops (UC-1) │ ├─ Success: Files changed, tests pass, tasks completed │ └─ Failure: No files changed, tests fail, no progress │ ├─ SUB-GOAL 2: Detect when no more progress is possible (UC-2) │ ├─ Success: Exit gracefully with completion summary │ └─ Failure: Continue looping when work is done │ ├─ SUB-GOAL 3: Prevent resource waste (UC-3) │ ├─ Success: Halt execution when stagnant │ └─ Failure: Burn tokens in infinite loops │ ├─ SUB-GOAL 4: Respect API limits (UC-4) │ ├─ Success: Wait for reset, continue seamlessly │ └─ Failure: Exceed limits, API errors │ └─ SUB-GOAL 5: Provide visibility (UC-5) ├─ Success: User has real-time status └─ Failure: Black box, no feedback这张树可以当作 Ralph 系统的验收测试地图每一条 Success 分支都对应可验证的运行结果每一条 Failure 分支都对应熔断器或退出检测必须拦截的场景。十、成功度量Success Metrics用例文档为每个用例定义了可量化的成功标准用例成功标准目标值UC-1循环完成率 95%UC-1平均循环时长 5 分钟UC-2完成检测准确率 90%UC-2误报率 5%UC-3熔断器触发时间 3 个循环UC-3停滞时的 Token 浪费 1,000 TokensUC-4限流合规率100%UC-4达到上限时的等待时间最小UC-5监控更新延迟 2 秒UC-6手动重置成功率100%这些指标是 2025-10 里程碑文档设定的历史目标反映设计意图而非已发布基准当前仓库中的实际行为以ralph_loop.sh的阈值配置为准如MAX_CONSECUTIVE_TEST_LOOPS3、MAX_CONSECUTIVE_DONE_SIGNALS2见 ralph_loop.sh。仓库同时通过.ralph/logs/metrics.jsonltrack_metricsralph_loop.sh记录每轮循环的时长与成功与否配合ralph-stats.sh可对实际表现做事后核对。十一、非功能需求Non-Functional Requirements可靠性Reliability可用性网络与 API 可用时达到 99%容错优雅处理 Claude API 错误数据完整性意外终止时无数据丢失性能Performance响应时间状态检查 100ms吞吐量支持连续运行数天可扩展性支持 100 循环的项目可用性Usability可学习性新用户在 30 分钟内理解系统错误消息失败时给出清晰、可操作的指引文档完整的用例与示例安全性Security认证遵循 Claude API 认证授权仅操作被授权的文件数据隐私不记录敏感数据从源码看安全性还体现在工具权限收敛上Ralph 默认通过--allowedTools传入白名单化的工具集安全 git 子命令、npm、pytest 等见 ralph_loop.sh刻意避免宽泛的Bash(git *)匹配破坏性命令权限被拒会触发专门的退出路径并指导用户更新.ralphrc的 ALLOWED_TOOLSralph_loop.sh。若需更强的隔离可选用--sandbox docker或--sandbox e2b把 Claude 的执行放进容器/云沙箱见 docs/DOCKER_SANDBOX.md 与 docs/E2B_SANDBOX.md。十二、术语表Glossary术语定义Circuit Breaker通过检测停滞来阻止失控循环的模式Exit Signal表明 Claude 已完成全部工作的指示器LoopRalph 执行一次 Claude Code 的迭代Rate Limit每小时允许的最大 API 调用次数100Response Analyzer解析 Claude 输出信号的组件Stagnation无进展的状态无文件变更Test-Only Loop只运行测试、无实现工作的循环这些术语在源码中均有对应实体熔断器 .ralph/.circuit_breaker_state与.ralph/.circuit_breaker_history退出信号 .ralph/.exit_signals调用计数 .ralph/.call_count与.ralph/.last_reset响应分析结果 .ralph/.response_analysis。十三、延伸阅读与调试入口用例文档原文docs/archive/2025-10-milestones/USE_CASES.mdPhase 2 完成报告用例文档编写背景docs/archive/2025-10-milestones/PHASE2_COMPLETION.md主循环实现ralph_loop.sh响应分析器实现lib/response_analyzer.sh熔断器实现lib/circuit_breaker.sh监控仪表盘实现ralph_monitor.sh相关测试用例tests/unit/test_exit_detection.bats、tests/unit/test_circuit_breaker_recovery.bats、tests/unit/test_rate_limiting.bats、tests/unit/test_status_updates.bats实践时排查一个Ralph 卡住的问题可以遵循 UC-6 的扩展 2a 流程先ralph --status看 status.json 的最终状态与 exit_reason再ralph --circuit-status查看熔断器当前状态与累计打开次数然后检查.ralph/logs/ralph.log与最近的claude_output_*.log最后依据原因修复后执行ralph --reset-circuit重新启动循环。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ralph 自治开发循环用例体系解析：从 Actor 目录到熔断器状态机的完整场景建模
Ralph 自治开发循环用例体系解析从 Actor 目录到熔断器状态机的完整场景建模【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-codeRalph 是一个面向 Claude Code 的自治 AI 开发循环系统核心目标是以最少的人工介入和 Token 浪费完成软件项目实现。本文基于仓库中的docs/archive/2025-10-milestones/USE_CASES.md遵循 Alistair Cockburn 用例方法论编写的 6 个用例与 Actor 目录结合ralph_loop.sh、lib/response_analyzer.sh、lib/circuit_breaker.sh、ralph_monitor.sh等源码实现完整解读 Ralph 的角色体系、用例层级、主成功场景与扩展流程、目标层级、成功度量与术语表。读完本文你将能理解 Ralph 每一次循环迭代内部发生了什么、熔断器如何在三次无进展后打开、响应分析器如何计算置信度并触发退出以及如何通过ralph --reset-circuit等命令手动介入。一、系统概述自治开发循环的参与者模型系统目标与角色根据用例文档Ralph 系统的核心定义如下系统名称Ralph —— 自治 AI 开发循环Autonomous AI Development Loop系统目标以最少的人工干预和 Token 浪费完成软件项目实现主执行者Primary ActorRalph —— 编排 Claude Code 的 bash 脚本辅助执行者Supporting ActorsClaude CodeAI 开发引擎、Human Developer发起者与审查者该文档归档于 docs/archive/2025-10-milestones/属于 Phase 2 里程碑2025-10-01完成时编写的用例文档是当前IMPLEMENTATION_STATUS.md与IMPLEMENTATION_PLAN.md所追踪方案的早期行为规格。Actor 能力与约束目录执行者类型核心目标关键能力关键约束Ralph系统持续执行开发循环直到项目完成或熔断器打开携带 PROMPT.md 指令执行 Claude Code分析响应中的完成信号跟踪文件变更与进度管理调用频率限制每小时 100 次通过熔断器检测停滞工作完成时优雅退出不能修改项目需求必须遵守 API 限流熔断器打开时不得覆盖需要有效的 PROMPT.md 与 fix_plan.mdClaude CodeAI 系统按 PROMPT.md 指令实现特性、修复缺陷、运行测试读/写/编辑文件执行 bash 命令运行测试并分析结果搜索代码库输出结构化状态报告每日 5 小时 API 限制Token 上下文限制不能访问外部网络除经批准的工具必须遵循 PROMPT.mdHuman Developer人类发起 Ralph、审查结果、必要时介入创建 PROMPT.md 与 fix_plan.md启动/停止 Ralph重置熔断器审查代码变更受阻时提供澄清自治循环执行期间不在场Ralph 运行时不能修改文件合并前必须审查变更从源码看Ralph 的无法覆盖打开的熔断器约束由 lib/circuit_breaker.sh 的can_execute()与 ralph_loop.sh 主循环中的should_halt_execution检查共同保障一旦状态文件.ralph/.circuit_breaker_state为 OPEN循环直接 break 并提示用户运行ralph --reset-circuit。二、用例层级一个系统目标五个子目标用例文档将系统目标完成项目实现分解为 5 个子目标每个子目标对应一个用例执行开发循环UC-1检测完成条件UC-2防止资源浪费UC-3处理错误条件UC-4提供可观测性UC-5外加一个纯人工触发的用例 UC-6重置熔断器。这 6 个用例构成了 Ralph 行为契约的完整骨架下文逐一展开。三、UC-1执行开发循环Execute Development Loop前置条件与成功保证前置条件全部满足才能启动循环PROMPT.md 存在且有效ralph_loop.sh中启动时若$PROMPT_FILE.ralph/PROMPT.md不存在会直接报错并给出修复指引见 ralph_loop.shfix_plan.md 存在且至少包含一个任务Claude Code CLI 已安装且可访问由validate_claude_command校验ralph_loop.shgit 仓库已初始化进度检测依赖 git diff成功保证Postcondition一个开发任务完成文件被修改并提交若有变更状态被记录到日志与 status.json熔断器状态更新退出信号被分析与记录主成功场景14 步Ralph 读取 PROMPT.mdRalph 检查熔断器状态必须为 CLOSED 或 HALF_OPENRalph 确认限流允许执行Ralph 携带 PROMPT.md 执行 Claude CodeClaude Code 读取 fix_plan.md 并选择任务Claude Code 实现任务修改文件Claude Code 运行相关测试Claude Code 输出 RALPH_STATUS 块Ralph 分析 Claude 的响应analyze_responseRalph 更新.exit_signals文件update_exit_signalsRalph 在熔断器中记录循环结果record_loop_resultRalph 递增调用计数器Ralph 将完成情况记录到 status.json 与 logs/若无退出条件Ralph 进入下一轮循环源码印证主循环位于 ralph_loop.sh 的while true中每轮迭代依次执行日志轮转 → 更新会话时间戳 →init_call_tracking步骤 2、3 对应的熔断器初始化和计数重置→should_halt_execution→can_make_call→should_exit_gracefully→update_status→create_backup→execute_claude_code→track_metrics。其中execute_claude_coderalph_loop.sh内部完成步骤 4–11构建 Claude 命令、执行、analyze_response、update_exit_signals、统计files_changed与has_errors、最后调用record_loop_result。扩展流程Extensions扩展编号触发条件处理行为2a熔断器为 OPEN显示熔断器状态 → 展示用户指引查看日志、重置等→ 以退出码 1 退出用例结束3a超出每小时调用数上限计算距下个小时重置的秒数 → 显示倒计时 → 等待重置 → 回到步骤 43b达到 API 5 小时限制在 Claude 输出中检测 rate limit 错误 → 询问用户重试还是退出选重试等待 5 分钟后继续选退出则优雅退出用例结束4aClaude Code 执行失败记录错误到logs/ralph_error.log→ 将 status.json 更新为 failed → 下一轮循环重试若连续 5 次失败则熔断器打开 → 回到步骤 29a响应分析检测到 EXIT_SIGNALtrue记录成功完成 → 将 status.json 更新为 complete → 显示完成摘要 → 以退出码 0 退出用例结束11a熔断器打开检测不到进展记录熔断器打开 → 将 status.json 更新为 circuit_open → 向用户显示指引 → 以退出码 1 退出用例结束执行频率循环持续执行直到完成或满足退出条件。性能目标正常条件下每个循环应在 5 分钟内完成。值得注意扩展 3a/3b 在当前源码中对应两类不同的限流。每小时 100 次调用限制由.ralph/.call_count、.ralph/.last_reset驱动can_make_call与wait_for_resetralph_loop.sh5 小时 API 限制则由 ralph_loop.sh 的execute_claude_code失败分支分层检测——先查rate_limit_event的status:rejected再以文本兜底匹配 5.*hour.*limit命中后返回码 2主循环展示 30 秒超时的选择菜单等待 60 分钟或退出。四、UC-2检测项目完成Detect Project Completion主执行者与职责主执行者Ralph经由lib/response_analyzer.sh利益相关者Human Developer希望可靠退出、Claude Code发出完成信号成功保证完成状态被准确判定.exit_signals文件记录决策置信度分数被计算0–100EXIT_SIGNAL 被正确设置true/false主成功场景Ralph 读取 Claude Code 输出文件Ralph 检查结构化 RALPH_STATUS 块Ralph 发现 STATUS: COMPLETE 且 EXIT_SIGNAL: trueRalph 将置信度分数设为 100Ralph 在.response_analysis中将 exit_signal 设为 trueRalph 用 done_signals 数组更新.exit_signalsRalph 在下一轮循环检查时触发优雅退出扩展流程扩展编号触发条件处理行为2a未找到结构化输出搜索自然语言完成关键词命中 10 置信度→ 检查 nothing to do 模式命中 15 置信度且 exit_signaltrue→ 跳到步骤 63aSTATUS 为 IN_PROGRESS检查 WORK_TYPE 字段连续第 3 轮为 TESTING 则标记 test_only连续第 3 轮 FILES_MODIFIED0 则熔断器打开exit_signal 设为 false → 跳到步骤 63bSTATUS 为 BLOCKED递增 blocked_loops 计数器若 3 则建议人工介入exit_signal 设为 false → 跳到步骤 66a置信度 40即使没有显式 EXIT_SIGNAL 也设置 exit_signaltrue记录高置信度完成检测 → 跳到步骤 7源码印证响应分析逻辑实现在 lib/response_analyzer.sh 的analyze_response()。它支持三种 JSON 格式扁平格式、Claude CLI 对象格式、Claude CLI 数组格式与文本兜底解析关键词与模式定义于文件头部COMPLETION_KEYWORDSdone、complete、finished、all tasks complete、project complete、ready for reviewNO_WORK_PATTERNSnothing to do、no changes、already implemented、up to dateTEST_ONLY_PATTERNSnpm test、bats、pytest、jest、cargo test、go test、running testsupdate_exit_signals()lib/response_analyzer.sh维护.ralph/.exit_signals中的三个滚动数组test_only_loops、done_signals、completion_indicators各保留最近 5 条。主循环中的should_exit_gracefully()ralph_loop.sh随后据此判定退出理由连续测试轮数 3test_saturation、完成信号 2completion_signals、连续 5 次 EXIT_SIGNALtrue 的安全熔断safety_circuit_breaker、完成指示 2 且 Claude 显式 EXIT_SIGNALtrueproject_complete、以及 fix_plan.md 全部复选框完成plan_complete。关于扩展 6a 中的置信度阈值当前源码在 JSON 模式下对置信度的处理已演化为显式 EXIT_SIGNAL 优先.response_analysis中.analysis.exit_signal代表 Claude 的显式意图仅当 Claude 明确 EXIT_SIGNALtrue 时才可能触发 project_complete 退出避免启发式误判导致的提前退出见 ralph_loop.sh 的注释。性能目标分析应在 1 秒内完成。五、UC-3防止资源浪费——熔断器Circuit Breaker设计意图熔断器模式基于 Michael Nygard《Release It!》中的经典模式用于检测停滞stagnation即没有文件变更并阻止失控循环烧掉 Token。成功保证失控循环被检测并中止Token 浪费被最小化 1K 浪费 Token中止时给出清晰的用户指引熔断器状态跨重启持久化主成功场景与状态机Ralph 将熔断器初始化为 CLOSED每轮循环后调用record_loop_result()Ralph 通过 git diff 统计 files_changedRalph 从 Claude 输出检测 has_errorsRalph 计算 output_length熔断器更新 consecutive_no_progress 计数器consecutive_no_progress 为 0检测到进展熔断器保持 CLOSEDRalph 进入下一轮循环状态机源码lib/circuit_breaker.sh 定义三个状态与四个可配置阈值状态含义进入条件CLOSED正常运行检测到进展初始状态HALF_OPEN 下恢复进展时回到 CLOSEDHALF_OPEN监控模式检查恢复连续 2 轮无进展OPEN检测到失败执行中止无进展阈值、同错误阈值、权限拒绝阈值任一达到可配置阈值默认值均可用环境变量覆盖CB_NO_PROGRESS_THRESHOLD3 # 连续 N 轮无进展则打开 CB_SAME_ERROR_THRESHOLD5 # 连续 N 轮同一错误则打开 CB_OUTPUT_DECLINE_THRESHOLD70 # 输出量下降超过 70% 则打开 CB_PERMISSION_DENIAL_THRESHOLD2 # 连续 N 轮权限被拒则打开 CB_COOLDOWN_MINUTES30 # OPEN → HALF_OPEN 自动恢复的冷却时间 CB_AUTO_RESETfalse # 启动时是否跳过冷却直接重置为 CLOSED扩展流程扩展编号触发条件状态迁移行为6a本轮无文件变更consecutive_no_progress 1保持 CLOSED继续到步骤 96b连续第 2 轮无变更consecutive_no_progress 2 →HALF_OPEN记录 monitoring mode 警告6c连续第 3 轮无变更consecutive_no_progress 3 →OPEN显示停止消息与指引退出码 1用例结束6d连续第 5 轮检测到同一错误consecutive_same_error 5 →OPEN原因为 Same error repeated in 5 consecutive loops转 6c37a检测到文件变更恢复consecutive_no_progress 重置为 0若为 HALF_OPEN 则转 CLOSED记录 circuit recovered继续到步骤 9源码印证record_loop_result()lib/circuit_breaker.sh将进展定义为四个来源的并集git diff 检出未提交变更、响应分析出现has_completion_signalSTATUS: COMPLETE 或显式 EXIT_SIGNAL、Claude 报告 files_modified 0、以及Claude 在提问不算进展也不算停滞抑制 no-progress 计数器见 Issue #190。状态文件.ralph/.circuit_breaker_state持久化state、consecutive_no_progress、consecutive_same_error、total_opens、reason、opened_at等字段而.ralph/.circuit_breaker_history以 JSON 数组记录每次状态迁移log_circuit_transition。性能目标熔断器检查 100ms。六、UC-4处理 API 限流Handle API Rate Limits成功保证遵守 API 限流调用计数器被准确跟踪小时级重置自动处理用户被告知等待时间主成功场景Ralph 检查当前小时YYYYMMDDHH 格式Ralph 读取.last_reset时间戳当前小时与 last_reset 相同Ralph 读取.call_countcall_count 为 45 100 上限Ralph 允许执行Ralph 将 call_count 递增为 46Ralph 将更新后的计数写入.call_count执行继续扩展流程扩展编号触发条件处理行为3a检测到新小时将 call_count 重置为 0 → 将当前小时写入.last_reset→ 记录 call counter reset for new hour → 回到步骤 55acall_count 达到或超过 100计算距下一小时的秒数 → 显示倒计时 Rate limit reached. Waiting HH:MM:SS... → 睡眠等待 → 重置计数器 → 回到步骤 65bClaude 返回 API 限流错误检测输出中的 rate_limit_error → 提示 API 5-hour limit reached. Retry? (y/n) → 输入 y 等待 5 分钟后重试输入 n 优雅退出用例结束源码印证小时级调用计数由init_call_tracking()ralph_loop.sh、can_make_call()ralph_loop.sh与wait_for_reset()ralph_loop.sh实现。MAX_CALLS_PER_HOUR默认 100可通过 CLI 参数--calls NUM或.ralphrc覆盖MAX_TOKENS_PER_HOUR默认 0禁用可设置以限制每小时累计 TokenToken 计数来自 Claude 输出的usage字段见extract_token_usage。5 小时限制的交互流程对应扩展 5b实现在 ralph_loop.sh返回码 2 分支30 秒无输入时自动选择等待以支持无人值守运行。性能目标限流检查 50ms。七、UC-5提供循环监控Provide Loop Monitoring主执行者与职责主执行者ralph-monitor.sh前置条件Ralph 正在运行ralph_loop.sh监控在独立终端启动主成功场景用户在独立终端启动 ralph-monitor.sh监控器每 2 秒读取一次 status.json监控器显示循环数、状态、时间戳监控器读取.call_count并显示 Calls: 45/100监控器读取.circuit_breaker_state并显示状态监控器读取.exit_signals并显示信号计数监控器检测到 status.json 更新监控器用新数据刷新显示循环继续回到步骤 2扩展流程扩展编号触发条件处理行为3astatus.json 尚不存在显示 Waiting for Ralph to start... → 睡眠 2 秒 → 回到步骤 25a熔断器为 OPEN以红色显示状态 → 显示熔断原因 → 显示 Execution halted 消息 → 继续到步骤 77aRalph 已退出检测最终状态 → 显示完成摘要 → 显示总循环数、时长、退出原因 → 监控器退出用例结束源码印证监控仪表盘实现在 ralph_monitor.sh 的display_status()REFRESH_INTERVAL2秒。除用例文档提到的字段外它还读取.ralph/progress.json展示 Claude 执行中的动画进度、沙箱状态Sandbox 区块仅在有沙箱提供方时显示与问题队列进度Issue Queue 区块仅当.ralph/queue.json存在时显示。若熔断器打开主循环会调用should_halt_execution显示红色的 EXECUTION HALTED: Circuit Breaker Opened 面板与排查指引lib/circuit_breaker.sh。另外ralph --monitor会在 tmux 中创建三窗格会话左Ralph 循环右上Claude 实时输出右下状态监控见 ralph_loop.sh 的setup_tmux_session。性能目标更新延迟 2 秒。八、UC-6重置熔断器手动介入主执行者Human Developer——这是全部 6 个用例中唯一以人类为主执行者的用例。前置条件熔断器为 OPENRalph 已中止执行用户已查阅日志并定位问题主成功场景11 步用户从 ralph-monitor 或日志发现熔断器打开用户查阅logs/ralph.log理解原因用户修复根本问题更新 fix_plan.md、修复错误等用户运行ralph --reset-circuitRalph 加载 circuit_breaker.sh 函数Ralph 调用reset_circuit_breaker(Manual reset by user)Ralph 将.circuit_breaker_state中的状态设为 CLOSEDRalph 将所有计数器重置为 0Ralph 记录 Circuit breaker reset to CLOSED stateRalph 显示成功消息用户可重新启动 Ralph 执行扩展流程扩展编号触发条件处理行为2a无法从日志确定原因运行ralph --status获取更多信息 → 检查.circuit_breaker_history的状态迁移记录 → 查阅最近的 Claude 输出文件 → 回到步骤 33a问题在 PROMPT.md 或 specs/编辑 PROMPT.md 澄清需求 → 用缺失信息更新 specs/ → 提交变更 → 回到步骤 43b问题是配置或环境安装缺失依赖 → 修复环境变量 → 验证配置 → 回到步骤 4源码印证ralph --reset-circuit在 ralph_loop.sh 中直接 sourcelib/circuit_breaker.sh并调用reset_circuit_breaker(Manual reset via command line)随后调用reset_session(manual_circuit_reset)清理会话状态。reset_circuit_breaker()本体lib/circuit_breaker.sh将状态文件重写为 CLOSED 并将所有计数器清零。若 OPEN 状态下未手动重置init_circuit_breaker()还会按CB_COOLDOWN_MINUTES默认 30 分钟自动过渡到 HALF_OPEN或按CB_AUTO_RESETtrue启动时直接回到 CLOSED。性能目标重置即时完成。九、目标层级Goal Hierarchy用例文档用一棵树完整呈现系统目标到子目标、成功与失败判据的映射SYSTEM GOAL: Complete project implementation with minimal token waste ├─ SUB-GOAL 1: Execute development loops (UC-1) │ ├─ Success: Files changed, tests pass, tasks completed │ └─ Failure: No files changed, tests fail, no progress │ ├─ SUB-GOAL 2: Detect when no more progress is possible (UC-2) │ ├─ Success: Exit gracefully with completion summary │ └─ Failure: Continue looping when work is done │ ├─ SUB-GOAL 3: Prevent resource waste (UC-3) │ ├─ Success: Halt execution when stagnant │ └─ Failure: Burn tokens in infinite loops │ ├─ SUB-GOAL 4: Respect API limits (UC-4) │ ├─ Success: Wait for reset, continue seamlessly │ └─ Failure: Exceed limits, API errors │ └─ SUB-GOAL 5: Provide visibility (UC-5) ├─ Success: User has real-time status └─ Failure: Black box, no feedback这张树可以当作 Ralph 系统的验收测试地图每一条 Success 分支都对应可验证的运行结果每一条 Failure 分支都对应熔断器或退出检测必须拦截的场景。十、成功度量Success Metrics用例文档为每个用例定义了可量化的成功标准用例成功标准目标值UC-1循环完成率 95%UC-1平均循环时长 5 分钟UC-2完成检测准确率 90%UC-2误报率 5%UC-3熔断器触发时间 3 个循环UC-3停滞时的 Token 浪费 1,000 TokensUC-4限流合规率100%UC-4达到上限时的等待时间最小UC-5监控更新延迟 2 秒UC-6手动重置成功率100%这些指标是 2025-10 里程碑文档设定的历史目标反映设计意图而非已发布基准当前仓库中的实际行为以ralph_loop.sh的阈值配置为准如MAX_CONSECUTIVE_TEST_LOOPS3、MAX_CONSECUTIVE_DONE_SIGNALS2见 ralph_loop.sh。仓库同时通过.ralph/logs/metrics.jsonltrack_metricsralph_loop.sh记录每轮循环的时长与成功与否配合ralph-stats.sh可对实际表现做事后核对。十一、非功能需求Non-Functional Requirements可靠性Reliability可用性网络与 API 可用时达到 99%容错优雅处理 Claude API 错误数据完整性意外终止时无数据丢失性能Performance响应时间状态检查 100ms吞吐量支持连续运行数天可扩展性支持 100 循环的项目可用性Usability可学习性新用户在 30 分钟内理解系统错误消息失败时给出清晰、可操作的指引文档完整的用例与示例安全性Security认证遵循 Claude API 认证授权仅操作被授权的文件数据隐私不记录敏感数据从源码看安全性还体现在工具权限收敛上Ralph 默认通过--allowedTools传入白名单化的工具集安全 git 子命令、npm、pytest 等见 ralph_loop.sh刻意避免宽泛的Bash(git *)匹配破坏性命令权限被拒会触发专门的退出路径并指导用户更新.ralphrc的 ALLOWED_TOOLSralph_loop.sh。若需更强的隔离可选用--sandbox docker或--sandbox e2b把 Claude 的执行放进容器/云沙箱见 docs/DOCKER_SANDBOX.md 与 docs/E2B_SANDBOX.md。十二、术语表Glossary术语定义Circuit Breaker通过检测停滞来阻止失控循环的模式Exit Signal表明 Claude 已完成全部工作的指示器LoopRalph 执行一次 Claude Code 的迭代Rate Limit每小时允许的最大 API 调用次数100Response Analyzer解析 Claude 输出信号的组件Stagnation无进展的状态无文件变更Test-Only Loop只运行测试、无实现工作的循环这些术语在源码中均有对应实体熔断器 .ralph/.circuit_breaker_state与.ralph/.circuit_breaker_history退出信号 .ralph/.exit_signals调用计数 .ralph/.call_count与.ralph/.last_reset响应分析结果 .ralph/.response_analysis。十三、延伸阅读与调试入口用例文档原文docs/archive/2025-10-milestones/USE_CASES.mdPhase 2 完成报告用例文档编写背景docs/archive/2025-10-milestones/PHASE2_COMPLETION.md主循环实现ralph_loop.sh响应分析器实现lib/response_analyzer.sh熔断器实现lib/circuit_breaker.sh监控仪表盘实现ralph_monitor.sh相关测试用例tests/unit/test_exit_detection.bats、tests/unit/test_circuit_breaker_recovery.bats、tests/unit/test_rate_limiting.bats、tests/unit/test_status_updates.bats实践时排查一个Ralph 卡住的问题可以遵循 UC-6 的扩展 2a 流程先ralph --status看 status.json 的最终状态与 exit_reason再ralph --circuit-status查看熔断器当前状态与累计打开次数然后检查.ralph/logs/ralph.log与最近的claude_output_*.log最后依据原因修复后执行ralph --reset-circuit重新启动循环。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考