Error Resolver

错误解决器

一种第一性原理方法，用于诊断和解决所有语言与框架中的错误。

核心理念

5 步错误解决流程：

1. CLASSIFY  ->  2. PARSE  ->  3. MATCH  ->  4. ANALYZE  ->  5. RESOLVE
     |              |             |             |              |
  What type?    Extract key    Known       Root cause      Fix +
               information    pattern?     analysis       Prevent

快速开始

当你遇到错误时：

1. 粘贴完整错误（如果可用，包括堆栈追踪）
2. 提供上下文（你当时想做什么？）
3. 分享相关代码（涉及的文件/函数）

错误分类框架

主要类别

类别	指标	常见原因
语法	Parse error、Unexpected token	拼写错误、缺少括号、无效语法
类型	TypeError、类型不匹配	数据类型错误、访问 null/undefined
引用	ReferenceError、NameError	未定义变量、作用域问题
运行时	RuntimeError、Exception	逻辑错误、无效操作
网络	ECONNREFUSED、timeout、4xx/5xx	连接问题、URL 错误、服务器宕机
权限	EACCES、PermissionError	文件/目录访问、需要 sudo
依赖	ModuleNotFound、Cannot find module	缺少包、版本不匹配
配置	Config error、env missing	设置错误、缺少环境变量
数据库	Connection refused、query error	数据库宕机、凭据错误、查询错误
内存	OOM、heap out of memory	内存泄漏、大数据处理

次要属性

• 严重性：Fatal / Error / Warning / Info
• 范围：构建时 / 运行时 / 测试时
• 来源：用户代码 / 框架 / 第三方 / 系统

分析工作流

第 1 步：分类

通过检查以下内容识别错误类别：

• 错误名称/代码（例如 ENOENT、TypeError）
• 错误消息关键词
• 发生位置（编译、运行时、测试）

第 2 步：解析

提取关键信息：

- Error code: [specific code if any]
- File path: [where the error originated]
- Line number: [exact line if available]
- Function/method: [context of the error]
- Variable/value: [what was involved]
- Stack trace depth: [how deep is the call stack]

第 3 步：匹配模式

对照已知错误模式进行检查：

• 查看 patterns/ 目录以获取特定语言的模式
• 将错误特征与已知解决方案匹配
• 检查重放历史以查找先前的解决方案

第 4 步：根因分析

应用 5 Whys 技巧：

Error: Cannot read property 'name' of undefined
  Why 1? -> user object is undefined
  Why 2? -> API call returned null
  Why 3? -> User ID doesn't exist in database
  Why 4? -> ID was from stale cache
  Why 5? -> Cache invalidation not implemented

Root Cause: Missing cache invalidation logic

第 5 步：解决

生成可操作的解决方案：

1. 即时修复 - 先让它现在能运行
2. 正确修复 - 以正确的方式解决它
3. 预防 - 如何在将来避免

输出格式

解决错误时，提供：

## Error Diagnosis

**Classification**: [Category] / [Severity] / [Scope]

**Error Signature**:
- Code: [error code]
- Type: [error type]
- Location: [file:line]

## Root Cause

[Explanation of why this error occurred]

**Contributing Factors**:
1. [Factor 1]
2. [Factor 2]

## Solution

### Immediate Fix
[Quick steps to resolve]

### Code Change
[Specific code to add/modify]

### Verification
[How to verify the fix works]

## Prevention

[How to prevent this error in the future]

## Replay Tag

[Unique identifier for this solution - for future reference]

重放系统

重放系统会记录成功的解决方案以供将来参考。

记录解决方案

解决错误后，记录下来：

# Create solution record in project
mkdir -p .claude/error-solutions

# Solution file format: [error-type]-[hash].yaml

解决方案记录格式

# .claude/error-solutions/[error-signature].yaml
id: "nodejs-module-not-found-express"
created: "2024-01-15T10:30:00Z"
updated: "2024-01-20T14:22:00Z"

error:
  type: "dependency"
  category: "ModuleNotFound"
  language: "nodejs"
  pattern: "Cannot find module 'express'"
  context: "npm project, missing dependency"

diagnosis:
  root_cause: "Package not installed or node_modules corrupted"
  factors:
    - "Missing npm install after git clone"
    - "Corrupted node_modules directory"
    - "Package not in package.json"

solution:
  immediate:
    - "Run: npm install express"
  proper:
    - "Check package.json has express listed"
    - "Run: rm -rf node_modules && npm install"
  code_change: null

verification:
  - "Run the application again"
  - "Check express is in node_modules"

prevention:
  - "Add npm install to project setup docs"
  - "Use npm ci in CI/CD pipelines"

metadata:
  occurrences: 5
  last_resolved: "2024-01-20T14:22:00Z"
  success_rate: 1.0
  tags: ["nodejs", "npm", "dependency"]

重放查找

遇到错误时：

1. 从错误消息生成错误特征
2. 在 .claude/error-solutions/ 中搜索匹配模式
3. 如果找到，应用记录的解决方案
4. 如果是新错误，继续进行完整分析并记录解决方案

错误特征生成

signature = hash(
  error_type +
  error_code +
  normalized_message +  # remove specific values
  language +
  framework
)

转换示例：

• Cannot find module 'express' -> Cannot find module '{module}'
• TypeError: Cannot read property 'name' of undefined -> TypeError: Cannot read property '{prop}' of undefined

调试命令

调试期间有用的命令：

Node.js

# Verbose error output
NODE_DEBUG=* node app.js

# Memory debugging
node --inspect app.js

# Check installed packages
npm ls [package-name]

# Verify package.json
npm ls --depth=0

Python

# Debug mode
python -m pdb script.py

# Check installed packages
pip show [package-name]
pip list

通用

# Check file permissions
ls -la [file]

# Check port usage
lsof -i :[port]
netstat -an | grep [port]

# Check environment variables
env | grep [VAR_NAME]
printenv [VAR_NAME]

# Check disk space
df -h

# Check memory
free -m  # Linux
vm_stat  # macOS

常见调试模式

模式 1：二分查找

当错误位置不明确时：

1. 注释掉一半代码
2. 如果错误仍然存在，则它在剩余的一半中
3. 重复，直到找到确切的行

模式 2：最小复现

创建能复现错误的最小代码：

1. 从空文件开始
2. 逐段添加代码
3. 当错误出现时停止
4. 那就是你的最小复现案例

模式 3：小黄鸭调试法

大声解释问题（或向 Claude 解释）：

1. 应该发生什么？
2. 实际发生了什么？
3. 最近有什么变化？
4. 我在做什么假设？

模式 4：Git Bisect

找出引入 bug 的提交：

git bisect start
git bisect bad  # current commit is bad
git bisect good [last-known-good-commit]
# Git will checkout commits for you to test
git bisect good/bad  # mark each as good or bad
git bisect reset  # when done

参考文件

• patterns/ - 各语言的错误模式

  • nodejs.md - Node.js 常见错误
  • python.md - Python 常见错误
  • react.md - React/Next.js 错误
  • database.md - 数据库错误
  • docker.md - Docker/容器错误
  • git.md - Git 错误
  • network.md - 网络/API 错误

• analysis/ - 分析方法论

  • stack-trace.md - 堆栈跟踪解析指南
  • root-cause.md - 根因分析技巧

• replay/ - 重放系统

  • solution-template.yaml - 记录解决方案的模板