circuit-breaker

概述

断路器技能是一种安全机制，可在自主开发期间防止无限循环、资源耗尽和意外破坏。它在循环级别运行（补充在任务级别运行的 resilient-execution）。没有断路器保护时，自主循环可能在停滞的问题上浪费数小时、耗尽 API 限额，或意外破坏配置文件。此技能会强制执行严格边界，确保自主操作高效且安全。

开始时宣布：“断路器已启用——正在监控停滞、速率限制和文件保护。”

---

阶段 1：检查断路器状态

每次循环迭代前，检查当前断路器状态：

+-----------+     threshold     +-----------+     cooldown     +------------+
|  CLOSED   |----exceeded----->|   OPEN    |----elapsed------>| HALF-OPEN  |
|  (normal) |                  |  (halted) |                  |  (probe)   |
+-----------+                  +-----------+                  +-----+------+
     ^                                                              |
     |                          success                             |
     +--------------------------------------------------------------+
     |                          failure                             |
     |                    +-----------+                              |
     +--------------------+   OPEN    |<----------------------------+
                          +-----------+

状态	含义	操作
CLOSED	正常运行	执行迭代，监控所有阈值
OPEN	因超出阈值而暂停	报告状态，等待冷却，或升级处理
HALF-OPEN	冷却后进行探测	允许执行一次迭代。成功则关闭；失败则重新打开。

停止：执行任何循环迭代前，先检查断路器状态。如果断路器为 OPEN，则不要执行。

---

阶段 2：停滞检测

在自主运行期间持续监控以下阈值：

条件	阈值	检测方法	操作
无进展	连续 3 次循环没有任何有意义的更改	跟踪每次循环中修改的文件和完成的任务	打开断路器
相同错误	连续 5 次循环产生相同错误	比较各次迭代的错误消息	打开断路器
输出下降	各次迭代的输出量下降 70%	比较最近 3 次迭代的输出行数	打开断路器
权限被拒	连续 3 次工具权限失败	跟踪权限错误	打开断路器
测试修复循环	超过 80% 的精力仅用于修复测试	跟踪每次迭代的工作类型	打开断路器，调查根本原因
循环式方法	相同的 2-3 种方法交替使用，仍未解决问题	跟踪方法历史	打开断路器

停滞评分

每次迭代都计算进展分数：

指标	分数
之前失败的测试现在通过	+3
任务标记为完成	+5
文件经过有意义的修改	+1
构建／lint 错误已解决	+2
与上次迭代相同的错误	-2
没有修改任何文件	-3
撤销之前的更改	-1

**阈值：**如果 3 次迭代的累计分数为负，则打开断路器。

停止：如果任何阈值被突破，立即打开断路器。不要尝试“再试一次”。

---

阶段 3：恢复流程

断路器打开时，按以下恢复顺序操作：

冷却期

• **默认：**重试前等待 30 分钟
• **目的：**防止在相同的失败状态中快速循环
• **冷却后：**断路器进入 HALF-OPEN 状态

HALF-OPEN 行为

1. 恰好允许执行一次迭代
2. 如果成功（进展分数为正）：关闭断路器，恢复正常运行
3. 如果失败（出现相同的停滞模式）：重新打开断路器，将冷却计时器加倍

恢复策略决策表

停滞类型	策略 1	策略 2	策略 3	策略 4
没有进展（卡在同一任务上）	重新分析并生成计划	将卡住的任务拆分为 3 个或更多子任务	跳到下一个任务，稍后再返回	升级并交由用户处理
错误相同（重复出现同一错误）	完全改变处理方式	检查错误是否由环境导致	搜索已知问题或解决方法	连同错误日志一起升级处理
测试修复循环（测试不断出错）	检查测试的前提假设	检查实现方式是否存在问题	缩小实现范围	连同测试分析一起升级处理
循环处理（反复交替使用相同修复方式）	暂停并重新分析根本原因	尝试尚未使用过的方法	缩小范围，先实现最小可运行版本	连同处理方式的历史记录一起升级处理

停止：恢复后，密切监控接下来的 3 次迭代。如果再次陷入停滞，立即升级处理。

---

第 4 阶段：速率限制

跟踪并强制执行 API 使用限制：

参数	默认值	用途
MAX_CALLS_PER_HOUR	100	防止过度使用 API
重置窗口	每小时（滚动）	自动重置计数器
倒计时显示	启用	显示达到限制前剩余的调用次数

速率限制行为

1. 跟踪滚动一小时内的 API 调用次数
2. 达到限制的 80% 时：显示警告，优先安排剩余调用
3. 达到限制的 100% 时：暂停执行，并显示距离重置的倒计时
4. 绝不超过限制——等待重置窗口

三层超时检测

对于长时间运行的操作（尤其是超时限制较长的 API 调用）：

层	检测方式	回退方案
1. 超时保护	退出代码 124 或超时信号	捕获部分输出，记录已完成的内容
2. JSON 验证	解析响应结构	尝试从原始响应中提取文本
3. 文本回退	捕获原始输出	记录所有内容，提交人工审核

---

第 5 阶段：文件保护

自主操作期间绝不能删除配置文件。这一点不可妥协。

受保护路径

路径	类型	受保护原因
.ralph/	目录	循环状态和配置
.ralphrc	文件	Ralph 配置
IMPLEMENTATION_PLAN.md	文件	当前计划——循环的真实依据
AGENTS.md	文件	Agent 定义
specs/	目录	规格说明——功能的真实依据
.claude/	目录	Claude Code 配置
CLAUDE.md	文件	Agent 操作手册
memory/	目录	跨会话持久保存的经验

保护机制

机制	工作方式	触发时机
允许列表强制执行	只有获准的工具才能修改受保护文件	对受保护路径执行任何文件写入操作之前
完整性验证	每次迭代后检查受保护文件是否存在	每轮循环迭代结束时
操作前检查	执行破坏性操作前验证受保护文件	执行 rm、git clean、git checkout . 之前
限制命令	禁止对受保护路径执行 git clean、git rm，禁止对配置目录执行 rm -rf	命令的目标为受保护路径时

破坏性操作前检查清单

执行任何 rm、git clean 或 git checkout . 之前：

1. 列出所有将受影响的文件
2. 逐一检查是否位于受保护路径列表中
3. 如果任何受保护文件将受到影响：中止并报告
4. 如果安全：谨慎继续
5. 操作后：确认所有受保护文件仍然存在

停止：如果任何操作后发现受保护文件缺失，立即停止并恢复该文件。

---

阶段 6：监控与指标

跟踪每次循环迭代中的以下指标：

指标	用途	告警阈值
循环次数	已执行的总迭代次数	单个任务超过 20 次
已完成任务数	衡量进度	连续 3 次或更多迭代为 0
修改的文件数	衡量变更速度	连续 3 次或更多迭代为 0
测试通过率	质量趋势	连续 3 次或更多迭代持续下降
错误频率	停滞早期预警	连续 3 次或更多迭代持续上升
输出量	生产力趋势	下降 70%
剩余 API 调用次数	接近速率限制的程度	剩余少于 20%
进度分数	整体健康状况	连续 3 次迭代为负

每次迭代的状态日志

## Iteration [N] — [timestamp]
- Circuit state: CLOSED / HALF-OPEN
- Tasks completed: [N]
- Files modified: [list]
- Tests: [X passed, Y failed, Z skipped]
- Errors encountered: [list]
- Progress score: [+/- N]
- API calls remaining: [N]
- Stagnation risk: LOW / MEDIUM / HIGH

---

反模式 / 常见错误

不要做什么	失败原因	应该怎么做
忽略停滞信号	在无法解决的问题上浪费数小时	达到阈值时打开断路器
手动覆盖已打开的断路器	绕过安全机制	严格遵循恢复流程
跳过文件保护检查	删除配置会使整个项目偏离正轨	操作后始终确认受保护文件完好
将冷却时间设为 0	在同一故障中快速反复循环	遵守至少 30 分钟的冷却时间
将仅修复测试的迭代计作进展	掩盖真正的问题（方法有误）	测试修复工作量超过 80% 时标记为停滞
删除并重新创建受保护文件	丢失配置状态	切勿删除受保护文件，只能更新
忽略速率限制警告	操作过程中触及硬性限制	达到限制的 80% 时优先处理
未预先检查就运行破坏性命令	可能删除受保护文件	始终先检查受影响的文件

---

防止自我合理化

想法	现实
“再试一次就能修好”	你 3 次迭代前就这么说过了。打开断路器。
“错误快修好了”	连续 5 次迭代都“快好了”，说明方法有误。
“我现在不能停，我就快成功了”	这是沉没成本谬误。打开断路器，重新评估。
“冷却时间太长了”	冷却时间可以避免在同一故障上浪费更多时间。
“这些配置文件不重要”	保护这些文件是有原因的。不要删除。
“不会触及速率限制”	跟踪它，不要猜测。
“这是个不同的错误”	检查它是否真的不同，还是同一根本原因以不同方式表现出来。

不要覆盖已打开的断路器。请遵循恢复流程。

---

集成点

技能	关系
resilient-execution	任务级重试（3 次尝试）。在单个任务内 resilient-execution 耗尽重试次数后，断路器才会启动。
autonomous-loop	断路器监控循环。检测到循环级停滞时打开断路器。
ralph-status	状态块提供用于检测停滞的指标。
verification-before-completion	断路器确保验证通过后才关闭循环。
self-learning	将停滞模式保存到记忆中，以便今后避免。
auto-improvement	断路器事件会纳入改进指标。

范围说明

范围	技能	行为
任务级	resilient-execution	针对单个失败任务尝试 3 种方法
循环级	circuit-breaker	模式表明存在系统性故障时，停止整个循环

在 resilient-execution 用尽单个任务内的重试次数后，断路器才会启动。如果每个任务即使重试 3 次仍持续失败，断路器就会检测到这一模式。

---

处理流程摘要

1. 每次循环迭代前： 检查熔断器状态（CLOSED/HALF-OPEN/OPEN）
2. 如果为 OPEN： 报告状态，等待冷却，或升级处理
3. 如果为 HALF-OPEN： 允许进行一次探测迭代，并评估结果
4. 如果为 CLOSED： 正常执行，监控所有阈值
5. 每次迭代后： 更新指标，计算进度分数，评估阈值
6. 如果超过阈值： 打开熔断器，报告原因，开始冷却
7. 冷却后： 进入 HALF-OPEN，允许进行一次探测
8. 探测后： 如果成功则关闭；如果失败则重新打开，并将冷却时间加倍

---

技能类型

RIGID — 必须严格遵守阈值和保护规则。不得放宽熔断器条件。不得覆盖已打开的熔断器。不得跳过文件保护检查。不得忽视停滞信号。