# Harness Enable Circuit Breaker

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

- Skill: `konglong87/harness-enable-circuit-breaker` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-enable-circuit-breaker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-enable-circuit-breaker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-enable-circuit-breaker

---


# 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: 全局迭代次数熔断

**检查条件**：
```yaml
触发条件: current_iteration ≥ max_iterations（默认100次）
优先级: 最高（全局保护）
目的: 防止AI无限循环，控制成本
```

**熔断动作**：
```bash
# 创建熔断文件
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消耗：

```bash
# 获取当前任务的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 工具检查任务错误计数：

```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 工具检查熔断文件：

```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`

```markdown
{当前时间} | 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`

内容：

```markdown
---
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`

```yaml
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 工具输出：

```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: 全局迭代次数熔断

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

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

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

### 层级2: Token消耗熔断

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

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

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

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

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

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

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

## 熔断恢复策略

### 策略 1: 自动恢复（低严重度）

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

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

### 策略 2: 自动复盘与参数调整（中严重度）

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

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

### 策略 3: 真实阻塞升级（高严重度）

```yaml
适用场景:
- 迭代次数严重超出（>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: 正常执行（无熔断）
```yaml
检查迭代次数: 50/100 → ✅ 正常
检查Token消耗: 6000/10000 → ✅ 正常
检查错误计数: 0/3 → ✅ 正常

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

### 示例 2: 迭代次数熔断
```yaml
检查迭代次数: 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消耗熔断
```yaml
检查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: 错误计数熔断
```yaml
任务: 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
└─ 否 → 继续执行技能
```

### 协作示例
```yaml
场景: 执行复杂功能开发

阶段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: 增量熔断检查
```yaml
策略: 不是每次执行完整检查，而是增量检查
实现:
- 迭代次数: 每次技能执行后 +1，在阈值附近才完整检查
- Token消耗: 使用估算而非精确计算，减少开销
- 错误计数: 失败时才检查，成功时跳过

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

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

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

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

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