code-error-handler-skill

生产级代码错误分析与修复助手 - 基于真实错误日志、官方文档和社区最佳实践

---

📖 技能描述

本技能专注于生产环境代码错误分析、诊断和修复。不同于教学式错误示例，我们提供：

• ✅ 真实错误日志分析 - 来自 GitHub Issues、Stack Overflow、生产环境
• ✅ 完整调用链追踪 - 错误如何在多层调用中传播
• ✅ 版本差异兼容 - 同一错误在不同框架/库版本的表现
• ✅ 隐性错误模式 - 不抛出异常但行为错误的场景
• ✅ 性能/并发问题 - 只在高负载下出现的错误
• ✅ 根因分析 (RCA) - 深入分析错误的根本原因
• ✅ 修复风险评估 - 每个修复方案的副作用和回归风险
• ✅ 监控告警建议 - 如何预防和早期发现

---

🎯 使用场景

适合的场景

1. 生产错误调试

   用户：我的 Django 应用在生产环境出现 "OperationalError: too many connections"
   
   AI: 分析完整堆栈 → 根因分析 → 3 种修复方案 → 验证步骤 → 监控配置

2. 复杂调用链错误

   用户：React 组件报错 "Cannot read property 'map' of undefined"
   
   AI: 追踪数据流 → 定位异步加载问题 → 修复方案（可选链/条件渲染/状态初始化）

3. 并发/竞态条件

   用户：Go 服务偶尔出现 "race condition: map read/write"
   
   AI: 分析并发模式 → 识别竞态点 → sync.Map/mutex/channel 方案对比

4. 性能相关错误

   用户：Node.js 服务内存泄漏，OOM killed
   
   AI: 内存分析 → 常见泄漏点 → heap dump 分析 → 修复方案

不适合的场景

• ❌ 语法教学（"for 循环怎么写"）
• ❌ 基础概念解释（"什么是 Promise"）
• ❌ 代码生成请求（"帮我写个登录功能"）

---

📚 支持的语言/框架

后端语言

语言/框架	错误类型覆盖	知识库	版本覆盖
Python	50+ 错误类型	references/python/	3.8-3.13
Python Web	80+ 错误类型	references/python-web/	Django 3-5, Flask 2-3, FastAPI 0.90+
Java	60+ 错误类型	references/java/	8-21
Go	40+ 错误类型	references/go/	1.18-1.22
Node.js	70+ 错误类型	references/nodejs/	16-22 LTS
C# / .NET	50+ 错误类型	references/csharp/	.NET 6-8

前端框架

语言/框架	错误类型覆盖	知识库	版本覆盖
JavaScript	60+ 错误类型	references/javascript/	ES6-ES2024
TypeScript	80+ 错误类型	references/typescript/	4.5-5.3
Vue.js	50+ 错误类型	references/vuejs/	2.7-3.4
React	60+ 错误类型	references/reactjs/	16-18
Next.js	50+ 错误类型	references/nextjs/	12-14 (App/Pages Router)

数据库/运维

语言/框架	错误类型覆盖	知识库	版本覆盖
SQL	60+ 错误类型	references/sql/	MySQL 5.7-8, PostgreSQL 12-16
Shell/Bash	40+ 错误类型	references/shell/	Bash 4-5
Docker	30+ 错误类型	references/docker/	20-25

---

🛠️ 核心功能

1. 错误日志解析

# 自动识别错误类型
python scripts/parse_error_log.py --input error.log --language python

# 输出结构化分析
{
  "error_type": "OperationalError",
  "error_message": "too many connections",
  "stack_trace": [...],
  "root_cause": "数据库连接池配置过小",
  "severity": "high",
  "similar_issues": [...]
}

2. 根因分析 (RCA)

每个错误提供 5 Why 分析：

1. Why: 为什么连接数过多？
   → 连接池大小设置为 10

2. Why: 为什么连接池这么小？
   → 默认配置未调整

3. Why: 为什么连接不释放？
   → 部分代码未正确关闭连接

4. Why: 为什么没有检测到？
   → 缺少连接数监控

5. Why: 为什么没有告警？
   → 未配置阈值告警

3. 修复方案分级

级别	名称	适用场景	风险
L1	Hotfix	生产紧急修复	中 - 需快速验证
L2	Proper Fix	正常迭代修复	低 - 标准流程
L3	Architectural	长期架构优化	低 - 需规划

4. 验证步骤

每个修复方案包含：

• ✅ 单元测试用例
• ✅ 集成测试场景
• ✅ 回归测试清单
• ✅ 性能基准对比

5. 监控告警配置

# Prometheus 告警示例
alerts:
  - alert: DatabaseConnectionHigh
    expr: db_pool_active_connections / db_pool_max_connections > 0.8
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "数据库连接池使用率超过 80%"

---

📋 文档结构

每个错误类型的文档包含：

# 错误名称

## 🔴 真实错误日志 (Real Production Logs)
- 错误堆栈（来自真实项目）
- 环境信息（语言版本、框架版本、OS）
- 触发场景

## 🔍 根因分析 (Root Cause Analysis)
- 直接原因
- 深层原因
- 触发条件
- 5 Why 分析

## 🧪 复现步骤 (Reproduction)
- 最小复现代码
- 环境要求
- 触发条件
- 预期 vs 实际行为

## 🛠️ 修复方案 (Fix Solutions)

### 方案 A: Hotfix (L1)
- 适用场景：生产紧急修复
- 代码修改
- 验证步骤
- 风险评估

### 方案 B: Proper Fix (L2)
- 适用场景：正常迭代
- 代码修改
- 测试用例
- 回归检查

### 方案 C: Architectural Fix (L3)
- 适用场景：长期优化
- 重构建议
- 架构调整
- 迁移路径

## 🧪 验证步骤 (Verification)
- 单元测试
- 集成测试
- 回归测试
- 性能基准

## 📊 监控告警 (Monitoring)
- 关键指标
- 告警阈值
- 日志埋点
- Dashboard 配置

## 🔗 相关资源 (References)
- 官方文档链接
- GitHub Issues
- Stack Overflow
- 社区文章
- 相关 CVE（如适用）

---

🚀 快速开始

安装

# 从 ClawHub 安装
clawhub install code-error-handler-skill

# 或克隆源码
git clone https://github.com/your-org/code-error-handler-skill.git
cd code-error-handler-skill
npm install

使用示例

示例 1: Python 数据库连接错误

用户：
File "/app/db.py", line 45, in get_connection
    return pool.getconn()
sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) FATAL:  sorry, too many clients already

AI:
🔴 错误类型：数据库连接池耗尽

🔍 根因分析:
1. 连接池大小 (pool_size=5) 不足以应对当前负载
2. 部分连接未正确释放（缺少 conn.close()）
3. 长查询占用连接时间过长

🛠️ 修复方案:

【L1 Hotfix】
- 临时增加连接池大小
- 重启服务释放泄漏连接

【L2 Proper Fix】
- 添加连接超时配置
- 使用上下文管理器确保连接释放

【L3 Architectural】
- 引入 PgBouncer 连接池代理
- 实施读写分离

📊 监控配置:
- 告警：连接池使用率 > 80%
- 指标：active_connections, idle_connections, wait_time

示例 2: React 渲染错误

用户：
TypeError: Cannot read properties of undefined (reading 'map')
at UserList (UserList.js:23:15)

AI:
🔴 错误类型：异步数据加载竞态

🔍 根因分析:
1. 组件挂载时 users 为 undefined
2. useEffect 中的数据加载尚未完成
3. 渲染时未处理 loading 状态

🛠️ 修复方案:

【L1 Hotfix】
- 添加可选链：users?.map()
- 添加条件渲染：{users && ...}

【L2 Proper Fix】
- 初始化状态为空数组：useState([])
- 添加 loading/error 状态

【L3 Architectural】
- 使用 React Query 管理异步状态
- 实施 Suspense + Error Boundaries

📊 监控配置:
- React Error Boundary 捕获率
- 组件渲染错误率

---

🧪 测试

# 运行测试套件
npm test

# 测试错误解析器
python scripts/parse_error_log.py --test

# 验证文档完整性
python scripts/validate_docs.py

---

📊 错误覆盖率

语言	错误类型数	真实案例数	覆盖率
Python	50+	200+	85%
Python Web	80+	350+	80%
JavaScript	60+	250+	85%
TypeScript	80+	300+	80%
Vue.js	50+	200+	75%
React	60+	280+	85%
Next.js	50+	180+	75%
Java	60+	240+	80%
Go	40+	150+	70%
Node.js	70+	300+	85%
C#	50+	180+	75%
SQL	60+	220+	80%
Shell	40+	120+	70%

总计: 750+ 错误类型，3000+ 真实案例

---

🔄 更新策略

版本同步

• 每月 检查官方文档更新
• 每季度 收集 GitHub Issues 新错误模式
• 每版本 更新框架 breaking changes

社区贡献

欢迎提交：

• 新的错误案例
• 修复方案改进
• 监控配置优化

---

📚 参考资源

官方文档

• Python Exceptions
• React Error Handling
• Go Error Handling
• TypeScript Errors

社区资源

• Stack Overflow Error Tags
• GitHub Issues
• Sentry Error Patterns

---

📄 License

MIT License

---

版本: v2.0.0 (重构版)
最后更新: 2026-03-22
维护者: code-error-handler-skill team