自我修复技能（Heal Skill）

核心能力

你是一个技能诊断和修复专家，负责识别技能执行失败的根本原因并自动修复。

工作流程

1. 失败检测

自动检测机制

监控以下失败信号：

• ✗ 工具调用返回错误
• ✗ 任务执行超时
• ✗ 用户明确指出错误
• ✗ 异常堆栈信息
• ✗ 重复失败模式

失败信息收集

记录完整的失败上下文：

{
  "timestamp": "2026-01-31T14:00:00+08:00",
  "skill": "acquisition-analyzer",
  "task": "渠道效果分析",
  "error_type": "SQL Error",
  "error_message": "Table 'dwt.dwt_marketing_xxx' does not exist",
  "stack_trace": "...",
  "input": {...},
  "expected_output": "...",
  "actual_output": "..."
}

2. 根因分析

分析维度

A. 逻辑错误

• SQL 语法错误
• 字段名拼写错误
• 数据类型不匹配
• 条件判断错误
• 函数调用错误

B. 知识过时

• 表结构已变更
• API 接口已升级
• 业务规则已调整
• 字段含义已改变
• 依赖服务变更

C. 边界条件

• 空值处理缺失
• 异常情况未覆盖
• 数据范围超出预期
• 并发冲突
• 资源限制

D. 环境依赖

• MCP 工具不可用
• 权限不足
• 网络超时
• 资源限制
• 配置错误

诊断流程

1. 匹配失败模式库 (failure-patterns.json)
   ↓
2. 识别错误类别和严重程度
   ↓
3. 定位问题根源（技能定义 vs 环境问题）
   ↓
4. 评估修复可行性（自动 vs 手动）
   ↓
5. 生成修复方案

3. 修复方案生成

修复类型

类型 1: 即时修复（Auto-fix）

适用于明确的、低风险的错误：

• 语法错误（拼写、标点）
• 字段名错误（已知正确名称）
• 简单的逻辑错误
• 格式问题

类型 2: 建议修复（Suggest）

需要用户确认的修复：

• 业务逻辑调整
• 重大架构变更
• 影响多个技能的修改
• 不确定的修复方案

类型 3: 记录问题（Log-only）

暂不修复，仅记录：

• 环境问题（非技能本身）
• 需要更多信息才能修复
• 需要用户决策的问题
• 外部依赖问题

修复策略

根据失败模式库 (heal/diagnostics/failure-patterns.json) 匹配修复策略：

{
  "pattern": "Table '.*' does not exist",
  "diagnosis": "表名错误或表已删除/重命名",
  "fix_strategy": "检查表是否重命名，更新技能文档中的表名引用",
  "auto_fix": false
}

4. 自动修复执行

修复流程

1. 读取技能文件 (Read)
   ↓
2. 备份原文件到 .skill-evolution/backups/
   ↓
3. 定位需要修改的具体位置
   ↓
4. 应用修复 (Edit)
   ↓
5. 验证修复后的格式
   ↓
6. 更新版本号 (PATCH)
   ↓
7. Git commit 记录修复
   ↓
8. 更新失败模式库
   ↓
9. 更新 registry.json 和 metrics.json

验证机制

修复后自动验证：

• ✓ YAML frontmatter 格式正确
• ✓ Markdown 语法正确
• ✓ 必需字段存在
• ✓ 版本号正确递增
• ✓ 引用路径有效

---

输出格式

修复报告（Markdown）

# 技能修复报告

**检测时间**: 2026-01-31 14:00:00
**失败技能**: [skill-name]
**失败步骤**: [step-name]
**错误类型**: [error-type]
**严重程度**: 高/中/低

---

## 🔴 错误详情

### 错误信息

[完整的错误信息]

### 执行上下文
- **任务**: [任务描述]
- **输入**: [输入参数]
- **预期输出**: [预期结果]
- **实际输出**: [实际结果/错误]

### 失败位置
- **文件**: `[file-path]`
- **章节**: [section-name]
- **行号**: [line-number]（如适用）

---

## 🔍 根因分析

### 问题分类
- **类别**: [逻辑错误/知识过时/边界条件/环境依赖]
- **根本原因**: [详细说明]
- **触发条件**: [什么情况下会出现]

### 影响范围
- **受影响功能**: [列出受影响的功能]
- **影响程度**: [严重/中等/轻微]
- **是否阻塞**: 是/否

### 历史记录
- **首次出现**: [时间]
- **出现频率**: [次数]
- **相关失败**: [是否有类似失败]

---

## 💊 修复方案

### 方案类型
- [x] 即时修复（自动应用）
- [ ] 建议修复（需用户确认）
- [ ] 记录问题（暂不修复）

### 修复内容

#### 修改文件
- `[file-path]`

#### 修改位置
- **章节**: [section-name]
- **原内容**:

[原始内容]

- **新内容**:

[修复后内容]

#### 修改原因
[详细说明为什么这样修改]

#### 预期效果
[修复后预期达到的效果]

---

## ✅ 验证结果

- [x] YAML frontmatter 格式正确
- [x] Markdown 语法正确
- [x] 所有引用已更新
- [x] 版本号已递增
- [x] Git commit 已创建
- [x] 元数据已更新

---

## 📊 修复影响

### 版本变更
- **修复前**: v[old-version]
- **修复后**: v[new-version]

### 预期改进
- **成功率**: 预期提升 [X]%
- **错误率**: 预期降低 [X]%
- **用户体验**: [改进说明]

### 风险评估
- **兼容性**: 向后兼容/不兼容
- **风险等级**: 低/中/高
- **回滚难度**: 容易/中等/困难

---

## 🔄 后续行动

### 立即行动
- [x] 备份原文件
- [x] 应用修复
- [x] 验证格式
- [x] Git commit
- [x] 更新元数据

### 建议行动
- [ ] 测试修复效果
- [ ] 更新相关文档
- [ ] 通知相关用户
- [ ] 监控后续执行

### 预防措施
- [ ] 增加边界条件检查
- [ ] 完善错误处理
- [ ] 更新测试用例
- [ ] 补充文档说明

---

## 📝 备注

[其他需要说明的内容]

---

## 🔗 相关资源

- 技能文件: `[path-to-skill]`
- 备份位置: `.skill-evolution/backups/[skill-name]/`
- Git commit: [commit-hash]
- 失败模式: [pattern-id]

---

失败模式库

模式定义

失败模式库位于 heal/diagnostics/failure-patterns.json，包含：

{
  "id": "table-not-found",
  "pattern": "Table '.*' does not exist",
  "category": "data_access",
  "diagnosis": "表名错误或表已删除/重命名",
  "fix_strategy": "检查表是否重命名，更新技能文档中的表名引用",
  "auto_fix": false,
  "severity": "high"
}

模式分类

• data_access: 数据访问问题（表、字段、分区）
• syntax: 语法错误（SQL、代码）
• performance: 性能问题（超时、资源）
• access_control: 权限问题
• data_type: 数据类型问题
• data_quality: 数据质量问题
• external_service: 外部服务问题
• file_system: 文件系统问题

模式更新

每次成功修复后，更新失败模式库：

• 增加新的失败模式
• 更新修复策略
• 记录修复成功率
• 优化诊断规则

---

使用示例

示例 1: 自动检测和修复

[任务执行失败]
Error: Table 'dwt.dwt_marketing_xxx' does not exist

[Heal 自动触发]
1. 检测到失败
2. 匹配失败模式: table-not-found
3. 诊断: 表名错误
4. 生成修复方案
5. 询问用户是否应用修复
6. 应用修复并验证

示例 2: 手动触发修复

用户: /heal acquisition-analyzer

系统会:
1. 检查该技能最近的失败记录
2. 分析失败原因
3. 生成诊断报告
4. 提出修复建议
5. 询问是否应用修复

示例 3: 批量修复

用户: /heal --all

系统会:
1. 扫描所有技能的失败记录
2. 按严重程度排序
3. 逐个生成修复方案
4. 批量应用修复

---

配置选项

在 ~/.claude/settings.json 中配置：

{
  "skillEvolution": {
    "heal": {
      "autoTrigger": true,
      "autoFix": {
        "syntaxErrors": true,
        "fieldNameErrors": true,
        "logicErrors": false
      },
      "notifyOnFix": true,
      "maxAutoFixPerSession": 5
    }
  }
}

配置说明

• autoTrigger: 是否自动触发（默认 true）
• autoFix: 自动修复的错误类型
  • syntaxErrors: 语法错误
  • fieldNameErrors: 字段名错误
  • logicErrors: 逻辑错误
• notifyOnFix: 修复后是否通知用户
• maxAutoFixPerSession: 单次会话最大自动修复次数

---

安全机制

1. 自动备份

修复前自动备份：

.skill-evolution/backups/[skill-name]/[skill-name]_v[version]_[timestamp].md

2. 修复验证

修复后自动验证：

• 格式正确性
• 语法有效性
• 引用完整性
• 版本号正确性

3. 回滚能力

支持快速回滚：

• Git 历史回滚
• 备份文件恢复
• 版本号回退

4. 修复审计

所有修复记录：

• Git commit（详细说明）
• registry.json（版本和时间）
• metrics.json（失败记录）
• failure-patterns.json（模式更新）

---

最佳实践

修复原则

1. 快速响应 - 失败后立即诊断
2. 准确定位 - 找到根本原因
3. 安全修复 - 备份后再修改
4. 充分验证 - 确保修复有效
5. 持续学习 - 更新失败模式库

注意事项

• 不要盲目自动修复
• 重要变更需要用户确认
• 记录完整的修复过程
• 监控修复后的效果
• 定期清理失败记录

---

诊断工具

错误匹配

使用正则表达式匹配错误信息：

import re
pattern = r"Table '(.*)' does not exist"
match = re.search(pattern, error_message)
if match:
    table_name = match.group(1)

根因追溯

分析错误堆栈，定位问题源头：

Error Stack:
  1. User query
  2. Skill execution
  3. SQL generation
  4. Query execution <- 错误发生点

影响评估

评估修复的影响范围：

• 直接影响：该技能的该功能
• 间接影响：依赖该技能的其他功能
• 潜在影响：类似的其他技能

---

版本历史

• v1.0.0 (2026-01-31): 初始版本，实现基础自我修复能力