# Harness Handle Failure

> 失败处理技能，包含错误分类、自动回滚、重试策略，失败时触发熔断机制，防止错误扩散

- Skill: `konglong87/harness-handle-failure` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-handle-failure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-handle-failure/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-handle-failure

---


# harness-handle-failure 失败处理技能

## 核心能力
1. 检查前置条件（harness-enable-circuit-breaker已完成）
2. 错误分类（代码错误、架构错误、流程错误）
3. 失败上下文记录
4. 自动回滚机制
5. 重试策略决策
6. 熔断触发检查
7. 更新错误计数
8. 遵循自治执行契约，仅在真实阻塞时升级 `harness-escalate-to-human`

## 前置条件
- harness-init 已完成
- harness-enable-circuit-breaker 已完成
- ERROR_TRACE.md 文件存在
- `.EnjoyHarness/EXECUTION_CONTRACT.md` 可读

## 执行步骤

### Step 1: 检查前置条件

使用 Read 工具读取：`.EnjoyHarness/SKILL_REGISTRY.md`
使用 Read 工具读取：`.EnjoyHarness/EXECUTION_CONTRACT.md`

检查条件：
- harness-enable-circuit-breaker 已标记为完成

如果未完成：
```
❌ 错误: 熔断机制未启用
💡 请先运行: harness-enable-circuit-breaker
```

### Step 2: 接收失败事件

失败事件来源：
- harness-enable-circuit-breaker 熔断触发
- 技能执行失败（Write/Edit/Bash失败）
- 验证失败（harness-validate-output）
- 目标验证失败（harness-goal）

失败事件格式：
```markdown
{TIMESTAMP} | FAILURE | {技能名} | {任务ID} - {错误详情} | FAILURE
```

### Step 3: 错误分类

使用 Read 工具读取：`.trace/ERROR_TRACE.md`

分析错误类型：

#### 3.1 代码错误（Code Error）
特征：
- 语法错误
- 类型错误
- 导入错误
- 运行时错误

处理策略：
- 记录错误详情
- 标记为代码级错误
- 触发自动修复（如果简单）
- 或触发harness-diagnose-and-improve

#### 3.2 架构错误（Architecture Error）
特征：
- 违反分层架构
- 跨层调用
- 循环依赖
- 违反命名规范

处理策略：
- 记录架构违规
- 标记为架构级错误
- 触发架构修复
- 回滚到上一个稳定版本

#### 3.3 流程错误（Process Error）
特征：
- 前置条件未满足
- 依赖技能失败
- 资源不可用
- 权限问题

处理策略：
- 记录流程问题
- 标记为流程级错误
- 自动刷新依赖状态、重排执行顺序或进入恢复链路
- 或在确认属于真实阻塞时触发阻塞升级

### Step 4: 记录失败上下文

使用 Bash 工具获取失败上下文：

```bash
TIMESTAMP=$(date -Iseconds)
TASK_ID={当前任务ID}
SKILL_NAME={失败的技能}
ERROR_TYPE={代码/架构/流程}

echo "失败时间: $TIMESTAMP"
echo "任务ID: $TASK_ID"
echo "技能: $SKILL_NAME"
echo "错误类型: $ERROR_TYPE"
```

使用 Write 工具创建失败记录：`.trace/ERROR_TRACE.md`

追加内容：
```markdown
## 失败记录 #{N}

### 基本信息
- 时间: {TIMESTAMP}
- 任务ID: {TASK_ID}
- 技能: {SKILL_NAME}
- 错误类型: {ERROR_TYPE}

### 错误详情
{详细错误信息}

### 上下文
- 当前迭代: {N}/100
- 当前Token消耗: {N}
- 错误计数: {N}/3

### 影响范围
- 影响文件: {文件列表}
- 影响技能: {技能列表}

### 失败原因分析
{AI分析失败原因}
```

### Step 5: 错误计数更新

使用 Read 工具读取：`.EnjoyHarness/GLOBAL_STATE.md`

获取当前错误计数：
```yaml
技能错误计数:
  {技能名}: {当前计数}
```

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

增加错误计数：
```yaml
技能错误计数:
  {技能名}: {当前计数}+1
```

检查是否达到熔断阈值：
- 如果 {技能名} 错误计数 ≥ 3 → 触发HIGH级熔断

### Step 6: 自动回滚决策

#### 6.1 回滚条件判断

满足以下条件之一则回滚：
- 错误类型为架构错误
- 同一技能错误计数 ≥ 2
- 文件修改导致系统不稳定

#### 6.2 执行回滚

使用 Bash 工具执行Git回滚：

```bash
# 检查当前状态
git status

# 如果有未提交的修改
if [ -n "$(git status --porcelain)" ]; then
    # 暂存当前修改（以防需要恢复）
    git stash push -m "failure-backup-{TASK_ID}-{TIMESTAMP}"

    # 记录暂存信息
    echo "✅ 已暂存当前修改: failure-backup-{TASK_ID}-{TIMESTAMP}"
fi

# 回滚到上一个稳定版本
git log --oneline -5

# 按最近一次成功提交、稳定标签或预设规则自动选择稳定提交
STABLE_COMMIT={上一个稳定提交hash}

# 执行回滚
git reset --hard $STABLE_COMMIT

echo "✅ 已回滚到稳定版本: $STABLE_COMMIT"
```

#### 6.3 记录回滚事件

使用 Edit 工具追加到：`.EnjoyHarness/EVENT_LOG.md`

```markdown
{TIMESTAMP} | ROLLBACK | harness-handle-failure | 回滚到 {STABLE_COMMIT} | SUCCESS
```

### Step 7: 重试策略决策

#### 7.1 重试条件判断

满足以下条件可重试：
- 错误类型为代码错误
- 错误计数 < 3
- 已回滚到稳定版本
- 有明确的修复方案

#### 7.2 重试策略

**策略A：自动重试**
- 适用：简单代码错误、明确修复方案
- 执行：应用修复方案后重试
- 次数：最多2次

**策略B：调整后重试**
- 适用：流程错误、依赖问题
- 执行：调整执行顺序或等待依赖完成
- 次数：最多1次

**策略C：不继续重试，进入真实阻塞升级**
- 适用：架构错误、错误计数≥3、多次重试失败
- 执行：记录阻塞原因并触发 `harness-escalate-to-human`
- 不重试

**自治模式附加规则**：
- 当 `human_escalation_policy: true_blockers_only` 时，不得为了普通失败询问用户下一步怎么做。
- 先执行自动回滚、自动重试、自动恢复。
- 只有在“无法自动恢复 + 继续执行会持续失败或破坏状态”时，才进入人工升级。

#### 7.3 执行重试

如果决定重试：

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

```markdown
{TIMESTAMP} | RETRY | harness-handle-failure | 重试 {技能名} (第{N}次) | STARTING
```

重新执行失败的技能。

### Step 8: 熔断触发检查

#### 8.1 任务级熔断（优先级：HIGH）

触发条件：
- 同一任务错误计数 ≥ 3
- 或同一技能错误计数 ≥ 3

执行动作：
- 停止当前任务
- 触发熔断文件创建
- 记录熔断事件

使用 Write 工具创建熔断文件：`.EnjoyHarness/.circuit-breaker-task-{TASK_ID}`

内容：
```markdown
---
triggered_at: {TIMESTAMP}
trigger_type: TASK_LEVEL
task_id: {TASK_ID}
skill_name: {技能名}
error_count: {N}
max_retries: 3
---

# 任务级熔断触发

## 触发原因
同一任务失败次数达到阈值：{N}/3

## 建议
1. 检查错误日志：.trace/ERROR_TRACE.md
2. 分析失败原因
3. 优先执行自动诊断、自动回滚或自动拆分方案

## 后续行动
- 默认触发 harness-handle-failure / harness-diagnose-and-improve
- 仅在真实阻塞时升级，不等待普通任务级人工决策
```

使用 Edit 工具追加到：`.EnjoyHarness/EVENT_LOG.md`

```markdown
{TIMESTAMP} | CIRCUIT_BREAKER_TRIGGERED | harness-handle-failure | 任务级熔断 (任务: {TASK_ID}, 错误: {N}/3) | CRITICAL
```

#### 8.2 全局熔断检查

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

检查：
- 如果 current_iteration ≥ max_iterations → 触发全局熔断

### Step 9: 生成失败处理报告

使用 Write 工具创建报告：`.trace/FAILURE_REPORT_{TASK_ID}.md`

内容：
```markdown
---
generated_at: {TIMESTAMP}
task_id: {TASK_ID}
status: FAILED
---

# 失败处理报告

## 执行摘要
- 失败时间: {TIMESTAMP}
- 任务ID: {TASK_ID}
- 失败技能: {SKILL_NAME}
- 错误类型: {ERROR_TYPE}

## 错误详情
{详细错误信息}

## 处理措施
- [x] 错误分类完成
- [x] 失败上下文已记录
- [x] 错误计数已更新: {N}/3
- [x] 回滚决策: {是/否}
- [x] 重试决策: {策略A/B/C}

## 回滚信息
- 是否回滚: {是/否}
- 回滚到: {COMMIT_HASH}
- 暂存备份: {STASH_NAME}

## 重试信息
- 重试策略: {A/B/C/无}
- 重试次数: {N}
- 重试结果: {成功/失败/进行中}

## 熔断状态
- 任务级熔断: {触发/未触发}
- 错误计数: {N}/3

## 下一步建议
1. {建议1}
2. {建议2}
3. {建议3}
```

### Step 10: 触发后续技能

根据处理结果，触发相应技能：

**错误计数 < 3 且 有修复方案**：
- 触发 harness-diagnose-and-improve（诊断错误）
- 或触发 harness-evolve（学习错误）

**错误计数 ≥ 3**：
- 先进行真实阻塞判定，再触发 `harness-escalate-to-human`

**架构错误**：
- 触发 harness-enforce-architecture-guardrails（重新检查架构）

### Step 11: 更新全局状态

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

```markdown
## 技能错误计数
- {技能名}: {N}/3

## 最近事件
- {TIMESTAMP} | harness-handle-failure | FAILURE_HANDLED | {任务ID} | {SUCCESS/FAILURE}
```

### Step 12: 更新迭代计数

使用 Edit 工具更新：`.EnjoyHarness/ITERATION_COUNTER.md`

增加计数（本技能约10次迭代）：
```markdown
current_iteration: N+10
```

### Step 13: 标记技能完成

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

```markdown
- [x] harness-handle-failure - 失败处理技能 ✅
```

### Step 14: 输出完成信息

使用 Bash 工具输出：

```bash
echo ""
echo "✅ harness-handle-failure 执行完成!"
echo ""
echo "📋 失败处理报告: .trace/FAILURE_REPORT_{TASK_ID}.md"
echo ""
echo "🔍 处理摘要:"
echo " - 错误类型: {ERROR_TYPE}"
echo " - 错误计数: {N}/3"
echo " - 回滚: {是/否}"
echo " - 重试: {策略A/B/C/无}"
echo " - 熔断: {触发/未触发}"
echo ""
echo "📌 下一步:"
if [ "$ERROR_COUNT" -lt 3 ]; then
    echo " - 触发 harness-diagnose-and-improve 诊断错误"
else
    echo " - 若确认为真实阻塞，则触发 harness-escalate-to-human"
fi
echo ""
```

## 成功标准
- [ ] 错误分类完成
- [ ] 失败上下文已记录到ERROR_TRACE.md
- [ ] 错误计数已更新到GLOBAL_STATE.md
- [ ] 回滚决策已执行（如需要）
- [ ] 重试策略已确定
- [ ] 熔断触发检查完成
- [ ] 失败处理报告已生成
- [ ] 后续技能已触发
- [ ] 事件已记录到EVENT_LOG.md
- [ ] 迭代计数已更新
- [ ] 技能已标记为完成

## 失败兜底
- 前置条件未满足 → 终止执行，提示运行前置技能
- 回滚失败 → 记录错误，触发阻塞评估；仅真实阻塞时升级
- 多次重试失败 → 触发熔断，进入自动恢复或真实阻塞升级

## 联动关系
- 前置技能: harness-enable-circuit-breaker
- 失败触发: harness-diagnose-and-improve, harness-evolve
- 熔断触发: harness-escalate-to-human
- 架构错误触发: harness-enforce-architecture-guardrails

## 迭代计数
本技能执行预计迭代次数: 约10次（Write 2次 + Edit 5次 + Read 3次 + Bash 3次）

## 测试用例

### 测试场景1：代码错误处理
**输入**：
```
错误: harness-validate-output 执行失败
原因: Go编译错误 - 未定义的变量
错误计数: 1/3
```

**预期输出**：
- 错误分类为代码错误
- 记录失败详情
- 错误计数更新为2/3
- 决策：自动重试（策略A）
- 触发 harness-diagnose-and-improve

### 测试场景2：架构错误处理
**输入**：
```
错误: harness-validate-output 执行失败
原因: 违反分层架构 - UI层直接调用Repo层
错误计数: 1/3
```

**预期输出**：
- 错误分类为架构错误
- 执行Git回滚到上一个稳定版本
- 错误计数更新为2/3
- 决策：不重试，需要架构修复
- 触发 harness-enforce-architecture-guardrails

### 测试场景3：任务级熔断
**输入**：
```
错误: harness-spawn-subharness-agent 执行失败
错误计数: 3/3（第三次失败）
```

**预期输出**：
- 创建熔断文件：`.EnjoyHarness/.circuit-breaker-task-{TASK_ID}`
- 停止当前任务
- 记录熔断事件（CRITICAL级别）
- 触发 harness-escalate-to-human

### 测试场景4：重试成功
**输入**：
```
第一次失败: 语法错误
回滚: 否
重试: 策略A（自动修复后重试）
```

**预期输出**：
- 应用修复方案
- 重新执行失败的技能
- 记录重试事件
- 如果成功，清除错误计数

### 测试场景5：多次重试失败
**输入**：
```
第一次失败: 代码错误
第二次失败: 代码错误（不同原因）
第三次失败: 流程错误
```

**预期输出**：
- 错误计数达到3/3
- 触发任务级熔断
- 生成失败处理报告
- 若判定为真实阻塞，则触发 `harness-escalate-to-human`