agentleFS
konglong87konglong87/enjoy_harness_ai/skills/harness-enable-circuit-breaker/SKILL.md

harness-enable-circuit-breaker

Skill0 starsChanged 8 months agoMITView on GitHub

熔断机制技能,实现三层熔断保护(迭代次数+Token+错误计数),防止AI无限循环、成本失控、错误扩散

The file

Files
SKILL.md

harness-enable-circuit-breaker 熔断机制技能

核心能力

  1. 检查前置条件(harness-init)
  2. 监控全局迭代计数器(ITERATION_COUNTER.md)
  3. 监控任务级错误计数(.task-{id}.md)
  4. 监控Token消耗(单任务阈值)
  5. 触发熔断(自动停止执行)
  6. 记录熔断事件(EVENT_LOG.md)
  7. 建议后续操作(默认自动恢复,真实阻塞再升级)

前置条件

  • harness-init 已完成
  • ITERATION_COUNTER.md 文件存在
  • .EnjoyHarness/EXECUTION_CONTRACT.md 可读

执行步骤

Step 1: 检查前置条件

使用 Read 工具读取:.EnjoyHarness/SKILL_REGISTRY.md

检查条件:

  • harness-init 已标记为完成

如果未完成:

❌ 错误: 系统未初始化
💡 请先运行: harness-init

Step 2: 读取全局迭代计数器

使用 Read 工具读取:.EnjoyHarness/ITERATION_COUNTER.md

提取关键信息:

  • 当前迭代次数(current_iteration)
  • 最大迭代次数(max_iterations)
  • 关联任务(task_id)
  • 开始时间(start_time)

Step 3: 检查三层熔断条件

3.1 层级1: 全局迭代次数熔断

检查条件:

触发条件: current_iteration ≥ max_iterations(默认100次)
优先级: 最高(全局保护)
目的: 防止AI无限循环,控制成本

熔断动作:

# 创建熔断文件
echo "CIRCUIT_BREAKER: ITERATION_LIMIT_EXCEEDED" > .EnjoyHarness/.circuit-breaker-iteration
echo "Current iteration: {current_iteration}/{max_iterations}" >> .EnjoyHarness/.circuit-breaker-iteration
echo "Timestamp: {当前时间}" >> .EnjoyHarness/.circuit-breaker-iteration

# 输出警告
echo "❌ 熔断触发: 迭代次数达到上限({current_iteration}/{max_iterations})"
echo "💡 建议: 先执行自动失败处理;仅在真实阻塞时升级 harness-escalate-to-human"

3.2 层级2: Token消耗熔断

使用 Bash 工具估算当前Token消耗:

# 获取当前任务的Token消耗(从GLOBAL_STATE.md中提取)
CURRENT_TOKEN=$(grep -A 5 "current_task" .EnjoyHarness/GLOBAL_STATE.md | grep "token_used" | awk '{print $2}')

if [ "$CURRENT_TOKEN" -gt 10000 ]; then
  # 创建熔断文件
  echo "CIRCUIT_BREAKER: TOKEN_LIMIT_EXCEEDED" > .EnjoyHarness/.circuit-breaker-token
  echo "Token used: {CURRENT_TOKEN}/10000" >> .EnjoyHarness/.circuit-breaker-token
  echo "Timestamp: {当前时间}" >> .EnjoyHarness/.circuit-breaker-token

  # 输出警告
  echo "❌ 熔断触发: Token消耗超限({CURRENT_TOKEN}/10000)"
  echo "💡 建议: 优化上下文加载,减少Token消耗"
fi

3.3 层级3: 任务级错误计数熔断

使用 Bash 工具检查任务错误计数:

# 查找所有任务追踪文件
for task_file in .EnjoyHarness/.task-*.md; do
  if [ -f "$task_file" ]; then
    # 提取错误计数
    ERROR_COUNT=$(grep "error_count:" "$task_file" | awk '{print $2}')
    TASK_ID=$(basename "$task_file" .md | sed 's/.task-//')

    if [ "$ERROR_COUNT" -ge 3 ]; then
      # 创建熔断文件
      echo "CIRCUIT_BREAKER: ERROR_LIMIT_EXCEEDED" > .EnjoyHarness/.circuit-breaker-task-${TASK_ID}
      echo "Task ID: ${TASK_ID}" >> .EnjoyHarness/.circuit-breaker-task-${TASK_ID}
      echo "Error count: ${ERROR_COUNT}/3" >> .EnjoyHarness/.circuit-breaker-task-${TASK_ID}
      echo "Timestamp: {当前时间}" >> .EnjoyHarness/.circuit-breaker-task-${TASK_ID}

      # 输出警告
      echo "❌ 熔断触发: 任务错误次数达到上限({TASK_ID}: {ERROR_COUNT}/3)"
      echo "💡 建议: 先走 harness-handle-failure 自动恢复链路"
    fi
  fi
done

Step 4: 判断是否需要触发熔断

使用 Bash 工具检查熔断文件:

# 检查是否存在任何熔断文件
if ls .EnjoyHarness/.circuit-breaker-* 1> /dev/null 2>&1; then
  echo "⚠️ 检测到熔断触发,停止执行"

  # 统计熔断类型
  ITER_BREAKERS=$(ls .EnjoyHarness/.circuit-breaker-iteration 2>/dev/null | wc -l)
  TOKEN_BREAKERS=$(ls .EnjoyHarness/.circuit-breaker-token 2>/dev/null | wc -l)
  ERROR_BREAKERS=$(ls .EnjoyHarness/.circuit-breaker-task-* 2>/dev/null | wc -l)

  echo "熔断统计:"
  echo " - 迭代次数熔断: ${ITER_BREAKERS}个"
  echo " - Token消耗熔断: ${TOKEN_BREAKERS}个"
  echo " - 错误计数熔断: ${ERROR_BREAKERS}个"

  # 触发后续动作
  if [ "$ITER_BREAKERS" -gt 0 ] || [ "$TOKEN_BREAKERS" -gt 0 ]; then
    echo "触发: harness-handle-failure(先自动恢复;仍阻塞时再升级)"
  else
    echo "触发: harness-handle-failure(失败处理)"
  fi

  exit 1
fi

Step 5: 记录熔断事件

使用 Edit 工具追加内容到:.EnjoyHarness/EVENT_LOG.md

{当前时间} | CIRCUIT_BREAKER_CHECK | harness-enable-circuit-breaker | 执行熔断检查 | {SUCCESS/WARNING}
{当前时间} | CIRCUIT_BREAKER_TRIGGERED | harness-enable-circuit-breaker | 熔断类型: {类型} | FAILURE

Step 6: 生成熔断报告

如果触发熔断,使用 Write 工具创建文件:.EnjoyHarness/CIRCUIT_BREAKER_REPORT.md

内容:

---
generated_at: {当前时间}
breaker_type: {ITERATION/TOKEN/ERROR}
severity: {HIGH/MEDIUM/LOW}
action_required: {AUTOMATIC_RECOVERY/BLOCKER_ESCALATION}
---

# Circuit Breaker Report

## 熔断概况
- 触发时间: {当前时间}
- 熔断类型: {迭代次数/Token消耗/错误计数}
- 严重程度: {HIGH/MEDIUM/LOW}
- 需要动作: {自动恢复/真实阻塞升级}

## 熔断详情

### 迭代次数熔断
- 当前迭代: {current_iteration}
- 最大限制: {max_iterations}
- 超出比例: {超出百分比}

### Token消耗熔断
- 已用Token: {已用}
- 上限: 10000
- 超出数量: {超出}

### 错误计数熔断
- 任务ID: {task-id}
- 错误次数: {error_count}/3
- 错误类型: {错误类型分布}

## 建议操作

### 立即操作
- [ ] 停止所有正在执行的技能
- [ ] 保存当前状态到 .trace/ARCHIVE/
- [ ] 触发自动失败处理与恢复

### 根因分析
- [ ] 检查是否存在无限循环(迭代熔断)
- [ ] 检查上下文加载是否过大(Token熔断)
- [ ] 检查任务是否过于复杂(错误熔断)

### 恢复策略
- [ ] 调整max_iterations上限(需要配置更新)
- [ ] 优化上下文加载策略(P0-P3优先级)
- [ ] 拆分任务为更小的子任务

## 自动恢复
如果严重程度为 MEDIUM 或 LOW,可尝试:
1. 重置迭代计数器: `Edit ITERATION_COUNTER.md → current_iteration: 0`
2. 重置错误计数: `Edit .task-{id}.md → error_count: 0`
3. 优化上下文加载: 减少 P1-P3 级文件加载

## 真实阻塞升级
如果严重程度为 HIGH 且自动恢复无法继续,才升级真实阻塞处理:
1. 检查 EVENT_LOG.md 了解执行历史
2. 检查 .trace/ERROR_TRACE.md 了解错误详情
3. 决定是继续执行还是终止任务
4. 由恢复链路统一移除或归档熔断文件

Step 7: 更新全局状态

使用 Edit 工具更新:.EnjoyHarness/GLOBAL_STATE.md

circuit_breaker_status: {TRIGGERED/NORMAL}
last_breaker_check: {当前时间}
breaker_type: {ITERATION/TOKEN/ERROR/NONE}

Step 8: 更新事件计数

使用 Edit 工具更新:.EnjoyHarness/EVENT_LOG.md

old_string: total_events: N new_string: total_events: N+2

Step 9: 更新技能注册表

使用 Edit 工具更新:.EnjoyHarness/SKILL_REGISTRY.md

old_string: - [ ] harness-enable-circuit-breaker - 熔断机制技能 new_string: - [x] harness-enable-circuit-breaker - 熔断机制技能 ✅

Step 10: 输出完成信息

使用 Bash 工具输出:

echo ""
echo "✅ harness-enable-circuit-breaker 完成!"
echo ""
echo "🔒 熔断检查:"
echo " - 迭代次数: {current_iteration}/{max_iterations}"
echo " - Token消耗: {已用}/10000"
echo " - 任务错误: {错误任务列表}"
echo ""
echo "📊 熔断状态:"
echo " - 迭代熔断: {已触发/未触发}"
echo " - Token熔断: {已触发/未触发}"
echo " - 错误熔断: {已触发/未触发}"
echo ""
if [ {熔断触发} ]; then
  echo "❌ 熔断已触发!"
  echo "📋 报告: .EnjoyHarness/CIRCUIT_BREAKER_REPORT.md"
  echo ""
  echo "🎯 下一步:"
  echo " - 默认: harness-handle-failure(自动恢复)"
  echo " - 高严重度且无法恢复: harness-escalate-to-human"
else
  echo "✅ 无熔断触发,可继续执行"
  echo ""
  echo "🎯 下一步:"
  echo " - 继续执行当前任务"
fi
echo ""

成功标准

  • 读取全局迭代计数器
  • 检查三层熔断条件
  • 判断是否需要触发熔断
  • 记录熔断事件
  • 生成熔断报告(如果触发)
  • 更新全局状态
  • 更新事件日志
  • 技能注册表已更新

失败兜底

  • harness-init 未完成 → 终止执行,提示运行前置技能
  • ITERATION_COUNTER.md 不存在 → 终止执行,提示运行 harness-init
  • 熔断触发 → 默认触发 harness-handle-failure;仅真实阻塞时升级 harness-escalate-to-human

联动关系

  • 前置: harness-init
  • 自动触发: 无(在每个技能执行前主动检查)
  • 熔断触发: harness-handle-failure(默认)或 harness-escalate-to-human(真实阻塞)

迭代计数

本技能执行预计迭代次数: 约 8 次(Read 2次 + Write 1次 + Edit 3次 + Bash 2次)

测试用例

测试 1: 前置条件检查

输入: 在系统未初始化时运行 期望输出: 错误提示"系统未初始化" 验证方式: 删除 ITERATION_COUNTER.md 后运行

测试 2: 迭代次数熔断检测

输入: current_iteration ≥ max_iterations 期望输出: 创建 .circuit-breaker-iteration 文件 验证方式: 手动设置 current_iteration=100 后运行

测试 3: Token消耗熔断检测

输入: Token消耗 > 10000 期望输出: 创建 .circuit-breaker-token 文件 验证方式: 手动设置 GLOBAL_STATE.md 中的 token_used=11000

测试 4: 错误计数熔断检测

输入: 任务错误计数 ≥ 3 期望输出: 创建 .circuit-breaker-task-{id} 文件 验证方式: 创建 .task-test.md,设置 error_count=3

测试 5: 熔断报告生成

输入: 触发任意熔断 期望输出: 生成 CIRCUIT_BREAKER_REPORT.md 验证方式: ls .EnjoyHarness/CIRCUIT_BREAKER_REPORT.md

测试 6: 全局状态更新

输入: 读取 GLOBAL_STATE.md 期望输出: circuit_breaker_status 为 TRIGGERED 或 NORMAL 验证方式: grep "circuit_breaker_status" .EnjoyHarness/GLOBAL_STATE.md

测试 7: 事件日志记录

输入: 读取 EVENT_LOG.md 期望输出: 包含 CIRCUIT_BREAKER_CHECK 事件 验证方式: grep "CIRCUIT_BREAKER" .EnjoyHarness/EVENT_LOG.md

测试 8: 无熔断触发

输入: 所有条件正常 期望输出: 输出"无熔断触发,可继续执行" 验证方式: 确保迭代次数、Token、错误计数均正常

三层熔断机制详解

层级1: 全局迭代次数熔断

目的: 防止AI无限循环,控制成本
触发条件: current_iteration ≥ max_iterations(默认100次)
优先级: 最高(全局保护)
检查频率: 每个技能执行前
动作:
- 创建熔断文件: .circuit-breaker-iteration
- 停止所有执行
- 触发: 先进入 `harness-handle-failure`,确认真实阻塞后再升级

优势:
- 全局保护,防止失控
- 参考机制,成熟稳定
- 可配置上限(根据任务复杂度调整)

示例:
- 任务: 复杂功能开发
- 预期迭代: 50次
- 实际迭代: 105次
- 触发熔断: 是
- 建议: 人工检查是否存在逻辑错误或无限循环

层级2: Token消耗熔断

目的: 防止Token成本失控
触发条件: 单任务Token消耗 > 10000
优先级: 中等(任务级保护)
检查频率: 每个技能执行前
动作:
- 创建熔断文件: .circuit-breaker-token
- 停止当前任务
- 触发: harness-handle-failure;仅真实阻塞时再升级

优势:
- 精确控制成本
- 及时发现问题
- 避免资源浪费

示例:
- 任务: 大规模重构
- Token预算: 10000
- 实际消耗: 12000
- 触发熔断: 是
- 建议: 优化上下文加载,减少P1-P3级文件加载

层级3: 任务级错误计数熔断

目的: 防止错误扩散,避免无效重试
触发条件: 同一任务错误次数 ≥ 3次
优先级: 较低(任务级保护)
检查频率: 每次任务失败后
动作:
- 创建熔断文件: .circuit-breaker-task-{id}
- 停止当前任务
- 触发: harness-handle-failure

优势:
- 快速失败,避免浪费时间
- 指导改进方向
- 防止陷入死循环

示例:
- 任务: fix-feishu-api
- 错误次数: 3/3
- 错误类型: API调用失败
- 触发熔断: 是
- 建议: 查阅API文档,或调整方案

熔断恢复策略

策略 1: 自动恢复(低严重度)

适用场景:
- 迭代次数接近上限但未超出
- Token消耗可控
- 错误次数 < 3次

恢复动作:
1. 重置计数器:
   - Edit ITERATION_COUNTER.md → current_iteration: 0
   - Edit .task-{id}.md → error_count: 0
2. 优化上下文:
   - 减少P1-P3级文件加载
   - 使用精准上下文索引
3. 继续执行:
   - 重新执行失败的任务
   - 监控新的计数

策略 2: 自动复盘与参数调整(中严重度)

适用场景:
- 迭代次数略微超出(100-110次)
- Token消耗略微超限(10000-12000)
- 错误次数达到上限但错误类型可修复

审查流程:
1. 人工检查熔断报告
2. 分析根因:
   - 迭代超限 → 是否存在无限循环?
   - Token超限 → 上下文是否过大?
   - 错误超限 → 任务是否过于复杂?
3. 决定:
   - 调整参数后继续(如提高max_iterations)
   - 修改任务拆分策略
   - 终止任务
4. 由恢复链路移除或归档熔断文件

策略 3: 真实阻塞升级(高严重度)

适用场景:
- 迭代次数严重超出(>120次)
- Token消耗严重超限(>15000)
- 系统级错误(核心文件损坏)

介入流程:
1. 触发: harness-escalate-to-human
2. 输出紧急报告:
   - 任务ID
   - 熔断原因
   - 执行历史
   - 建议操作
3. 人工决策:
   - 回滚到稳定状态
   - 终止任务
   - 调整架构设计
4. 记录经验:
   - 更新 ERROR_HANDBOOK.md
   - 更新 .learnings/ERRORS.md

熔断流程图

[开始熔断检查]
↓
[读取迭代计数器]
↓
[检查迭代次数]
判断: current_iteration ≥ 100?
├─ 是 → [触发迭代熔断] → [生成报告] → [失败处理/真实阻塞升级]
└─ 否 ↓
    [检查Token消耗]
    判断: Token > 10000?
    ├─ 是 → [触发Token熔断] → [生成报告] → [失败处理/真实阻塞升级]
    └─ 否 ↓
        [检查错误计数]
        判断: error_count ≥ 3?
        ├─ 是 → [触发错误熔断] → [生成报告] → [失败处理]
        └─ 否 ↓
            [无熔断触发]
            [继续执行]

使用示例

示例 1: 正常执行(无熔断)

检查迭代次数: 50/100 → ✅ 正常
检查Token消耗: 6000/10000 → ✅ 正常
检查错误计数: 0/3 → ✅ 正常

结果: 无熔断触发,继续执行
输出: "✅ 无熔断触发,可继续执行"

示例 2: 迭代次数熔断

检查迭代次数: 105/100 → ❌ 超限
触发熔断: 迭代次数达到上限

动作:
1. 创建 .circuit-breaker-iteration
2. 生成 CIRCUIT_BREAKER_REPORT.md
3. 更新 GLOBAL_STATE.md: circuit_breaker_status: TRIGGERED
4. 记录事件到 EVENT_LOG.md
5. 触发 harness-escalate-to-human

建议: 人工检查是否存在无限循环

示例 3: Token消耗熔断

检查Token消耗: 12000/10000 → ❌ 超限
触发熔断: Token消耗超限

动作:
1. 创建 .circuit-breaker-token
2. 生成 CIRCUIT_BREAKER_REPORT.md
3. 更新 GLOBAL_STATE.md
4. 记录事件
5. 触发 harness-handle-failure(可自动恢复)

建议: 优化上下文加载,减少P1-P3级文件

示例 4: 错误计数熔断

任务: fix-feishu-api-20260328-140000
错误计数: 3/3 → ❌ 达到上限
触发熔断: 错误次数达到上限

动作:
1. 创建 .circuit-breaker-task-fix-feishu-api-20260328-140000
2. 生成 CIRCUIT_BREAKER_REPORT.md
3. 更新任务状态: CIRCUIT_BREAKER_TRIGGERED
4. 记录事件
5. 触发 harness-handle-failure

建议: 查阅API文档,或调整方案

与其他技能的协作

协作流程

harness-init(初始化)→ 创建 ITERATION_COUNTER.md
↓
所有技能执行前 → harness-enable-circuit-breaker(检查熔断)
↓
判断: 是否触发熔断?
├─ 是 → 判断严重程度?
│   ├─ 高严重度 → harness-escalate-to-human
│   └─ 中低严重度 → harness-handle-failure
└─ 否 → 继续执行技能

协作示例

场景: 执行复杂功能开发

阶段1: 初始化
- harness-init → 初始化系统,创建 ITERATION_COUNTER.md

阶段2: 执行任务(每个技能前检查)
- harness-build-core-manifest → 熔断检查: 1/100迭代 ✅
- harness-build-context-index → 熔断检查: 2/100迭代 ✅
- harness-spawn-subharness-agent → 熔断检查: 3/100迭代 ✅
- ...

阶段3: 熔断触发
- 第101次迭代 → 熔断检查: 101/100迭代 ❌
- 触发: harness-handle-failure;仅真实阻塞时再升级

阶段4: 自动恢复 / 真实阻塞升级
- 检查执行历史: EVENT_LOG.md
- 检查错误详情: ERROR_TRACE.md
- 决定: 调整max_iterations或终止任务
- 由恢复链路统一归档或移除熔断文件
- 继续执行或终止

性能优化建议

优化 1: 增量熔断检查

策略: 不是每次执行完整检查,而是增量检查
实现:
- 迭代次数: 每次技能执行后 +1,在阈值附近才完整检查
- Token消耗: 使用估算而非精确计算,减少开销
- 错误计数: 失败时才检查,成功时跳过

优势: 减少熔断检查的Token消耗

优化 2: 预警机制

策略: 在接近熔断阈值时提前警告
实现:
- 迭代次数 > 80% → 输出警告
- Token消耗 > 80% → 输出警告
- 错误次数 ≥ 2次 → 输出警告

优势: 提前发现问题,避免熔断触发

优化 3: 智能熔断恢复

策略: 根据历史数据自动调整恢复策略
实现:
- 分析历史熔断类型
- 自动选择最合适的恢复策略
- 记录恢复成功率

优势: 提高自动恢复成功率,减少阻塞升级

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.