name: 错误解决器 description: 使用第一性原理分析的系统化错误诊断和解决。当遇到任何错误消息、堆栈跟踪或意外行为时使用。支持回放功能来记录和重用解决方案。

错误解决器

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

核心哲学

5步错误解决流程：

1. 分类  ->  2. 解析  ->  3. 匹配  ->  4. 分析  ->  5. 解决
     |            |           |           |           |
  什么类型？   提取关键   已知模式？   根因分析   修复 +
               信息                    预防

快速开始

当遇到错误时：

粘贴完整错误（包括堆栈跟踪，如果可用）
提供上下文（您正在尝试做什么？）
分享相关代码（涉及的文件/函数）

错误分类框架

主要类别

类别	指标	常见原因
语法	解析错误，意外标记	拼写错误，缺少括号，无效语法
类型	TypeError，类型不匹配	错误数据类型，空/未定义访问
引用	ReferenceError，NameError	未定义变量，作用域问题
运行时	RuntimeError，异常	逻辑错误，无效操作
网络	ECONNREFUSED，超时，4xx/5xx	连接问题，错误URL，服务器宕机
权限	EACCES，PermissionError	文件/目录访问，需要sudo
依赖	ModuleNotFound，找不到模块	缺少包，版本不匹配
配置	配置错误，环境变量缺失	错误设置，缺少环境变量
数据库	连接拒绝，查询错误	数据库宕机，错误凭据，错误查询
内存	OOM，堆内存不足	内存泄漏，大数据处理

次要属性

严重性: 致命 / 错误 / 警告 / 信息
范围: 构建时 / 运行时 / 测试时
来源: 用户代码 / 框架 / 第三方 / 系统

分析工作流程

步骤1: 分类

通过检查识别错误类别：

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

步骤2: 解析

提取关键信息：

- 错误代码: [如果有]
- 文件路径: [错误起源的地方]
- 行号: [如果可用]
- 函数/方法: [错误的上下文]
- 变量/值: [涉及的内容]
- 堆栈跟踪深度: [调用堆栈深度]

步骤3: 匹配模式

检查已知错误模式：

查看patterns/目录获取语言特定模式
匹配错误签名到已知解决方案
检查回放历史以获取先前解决方案

步骤4: 根因分析

应用5 Whys技术：

错误: 无法读取未定义的属性'name'
  为什么1？ -> 用户对象未定义
  为什么2？ -> API调用返回null
  为什么3？ -> 数据库中用户ID不存在
  为什么4？ -> ID来自陈旧缓存
  为什么5？ -> 未实现缓存失效逻辑

根因: 缺少缓存失效逻辑

步骤5: 解决

生成可操作解决方案：

即时修复 - 立即让它工作
正确修复 - 正确解决的方法
预防 - 如何避免未来发生

输出格式

解决错误时，提供：

## 错误诊断

**分类**: [类别] / [严重性] / [范围]

**错误签名**:
- 代码: [错误代码]
- 类型: [错误类型]
- 位置: [文件:行]

## 根因

[解释为什么发生此错误]

**贡献因素**:
1. [因素1]
2. [因素2]

## 解决方案

### 即时修复
[快速解决步骤]

### 代码变更
[要添加/修改的特定代码]

### 验证
[如何验证修复工作]

## 预防

[如何预防此错误未来发生]

## 回放标签

[此解决方案的唯一标识符 - 供未来参考]

回放系统

回放系统记录成功解决方案供未来参考。

记录解决方案

解决错误后，记录它：

# 在项目中创建解决方案记录
mkdir -p .claude/error-solutions

# 解决方案文件格式: [错误类型]-[哈希].yaml

解决方案记录格式

# .claude/error-solutions/[错误签名].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项目，缺少依赖"

diagnosis:
  root_cause: "包未安装或node_modules损坏"
  factors:
    - "克隆git后缺少npm install"
    - "node_modules目录损坏"
    - "包不在package.json中"

solution:
  immediate:
    - "运行: npm install express"
  proper:
    - "检查package.json是否列出express"
    - "运行: rm -rf node_modules && npm install"
  code_change: null

verification:
  - "再次运行应用程序"
  - "检查express是否在node_modules中"

prevention:
  - "在项目设置文档中添加npm install"
  - "在CI/CD管道中使用npm ci"

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

回放查找

遇到错误时：

从错误消息生成错误签名
搜索.claude/error-solutions/以匹配模式
如果找到，应用记录的解决方案
如果新，进行完整分析并记录解决方案

错误签名生成

signature = hash(
  错误类型 +
  错误代码 +
  规范化消息 +  # 移除特定值
  语言 +
  框架
)

示例转换：

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

调试命令

调试期间有用命令：

Node.js

# 详细错误输出
NODE_DEBUG=* node app.js

# 内存调试
node --inspect app.js

# 检查已安装包
npm ls [包名]

# 验证package.json
npm ls --depth=0

Python

# 调试模式
python -m pdb script.py

# 检查已安装包
pip show [包名]
pip list

通用

# 检查文件权限
ls -la [文件]

# 检查端口使用
lsof -i :[端口]
netstat -an | grep [端口]

# 检查环境变量
env | grep [变量名]
printenv [变量名]

# 检查磁盘空间
df -h

# 检查内存
free -m  # Linux
vm_stat  # macOS

常见调试模式

模式1: 二分查找

当错误位置不清楚时：

注释掉一半代码
如果错误持续，在剩余一半中
重复直到找到确切行

模式2: 最小重现

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

从空文件开始
逐段添加代码
当错误出现时停止
那就是最小重现案例

模式3: 橡皮鸭调试

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

应该发生什么？
实际发生什么？
最近改变了什么？
我正在做什么假设？

模式4: Git二分法

查找哪个提交引入了错误：

git bisect start
git bisect bad  # 当前提交是坏的
git bisect good [最后一个已知好的提交]
# Git将为您检出提交以测试
git bisect good/bad  # 标记每个为好或坏
git bisect reset  # 完成后

参考文件

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 - 记录解决方案的模板