harness-enable-circuit-breaker

name	harness-enable-circuit-breaker
description	熔断机制技能，实现三层熔断保护（迭代次数+Token+错误计数），防止AI无限循环、成本失控、错误扩散
trigger_words	["harness-enable-circuit-breaker","熔断机制","circuit-breaker","熔断保护"]
priority	HIGHEST
dependencies	["harness-init"]
version	v3.0.0

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: 智能熔断恢复

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

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