Error explain zh

error-explain-zh — 通用报错中文诊断

把任意语言的错误信息/堆栈/panic/exception 解读成"为什么报这个错 + 具体怎么改", 不用再对着英文错误文档反复猜。跨语言通用:Go / JavaScript / Python / Java / Rust / Flutter / Dart / Shell / …

何时触发

• 用户说"帮我看这个报错"、"这个错误是什么意思"、"这个 panic 怎么回事"、"帮我 debug"
• 用户粘贴了错误日志、stack trace、panic 输出、exception 信息
• 用户贴了 stderr / logcat / Xcode 日志并问"为什么"

与 lambda-logs-zh 的区别:lambda-logs-zh 专门处理 AWS CloudWatch 多条日志的聚类分析; error-explain-zh 是通用单次报错诊断,不限运行时和平台。

工作流

1. 识别语言 / 运行时与错误类型

• 从错误格式、关键词、文件扩展名推断语言和运行时:
  • goroutine / panic: → Go
  • Traceback (most recent call last) → Python
  • at Object.<anonymous> / UnhandledPromiseRejection → Node.js/JavaScript
  • Exception in thread "main" / at com. → Java/Kotlin JVM
  • thread 'main' panicked at → Rust
  • flutter: Error / DartError / ══╡ EXCEPTION CAUGHT BY FLUTTER FRAMEWORK → Flutter/Dart
  • Caused by: → Java 链式异常,需向内展开到最内层
• 识别错误大类:空指针 / 类型错误 / 连接失败 / 权限拒绝 / 断言失败 / OOM / 配置缺失 / 依赖冲突 / 并发竞争 等
• 若有多种错误混在一起,先按"最先触发的 / 最内层的"排序

2. 定位最关键的那一行(真正根因常不在栈顶)

• 栈跟踪逻辑:从 Caused by:、最内层 goroutine、caused by、Source error: 等向内找真实根因帧
• 区分用户代码与库代码:
  • 用户代码帧:文件路径不含 node_modules/、site-packages/、GOROOT、vendor/、jdk/、android.jar 等
  • 优先指出用户代码中的最近帧——那通常是修复入口
  • 若根因在库内部,说明是库的哪个调用/参数触发的
• 若错误信息里有行号,仅基于行号做分析;没有源码时不臆断行号外的代码

3. 中文讲清"为什么报这个错"

用白话解释这个错误的直接触发机制,例如:

• "这行代码对 nil 指针做了方法调用,Go 运行时无法找到方法接收者"
• "ECONNREFUSED 表示目标端口没有进程在监听,通常是服务未启动或端口配置错误"
• "Python 在 json.loads 时遇到了非 UTF-8 字节,说明输入不是合法 JSON 字符串"

区分两类陈述:

• "确定的根因":错误信息直接说明的,不加"可能"
• "可能原因":需要更多上下文才能确认的,明确标注"可能"/"待确认"

4. 给可操作的修复方向

• 主要修复(最可能解决问题的):优先级最高,给具体步骤或代码片段
• 次要修复(其他可能路径):在主要修复之后列出
• 每条建议附验证方法:如何确认修复成功(看哪个输出、跑什么命令、观察什么现象)
• 涉及配置/依赖/版本时,给出检查命令而非凭空猜版本号

5. 信息不足时明确追问

若以下信息缺失且影响判断,不臆造,直接问:

• 相关业务代码(堆栈里指向的那几行)
• 运行时/框架版本(go version / node --version / python --version / 依赖版本)
• 触发步骤 / 复现方式
• 上下文配置(环境变量、配置文件、数据库 schema 等)

输出模板

## 错误类型

<语言/运行时> — <错误大类>(如:Go — 空指针 panic / Python — JSON 解析错误 / Java — 链式 IOException)

## 根因

<用白话讲:直接触发机制 + 关键帧指向>

**关键帧**:
- `<文件:行号>` — 用户代码,触发点
- `<文件:行号>` — 库内部(`<库名>`)

**确定的根因**:<直接说明的原因>
**可能原因**:<需进一步确认的因素,或"无"表示根因已明确>

## 修复建议

### 主要修复
1. <具体步骤或修改点>
   - 验证方法:<如何确认成功>

### 次要修复(可选)
2. <其他可能路径>
   - 验证方法:<…>

## 还需补充

<若信息不足,列出需要用户提供的内容;若信息已充分,此节省略或写"无">

硬规则

1. 不臆断行号外的代码:没有对应源码时,只基于错误信息和帧路径分析,不编造逻辑。
2. 区分"确定"vs"可能":错误信息直接说明的用肯定句;需要更多上下文的明确加"可能"/"待确认"。
3. 栈跟踪必须指出帧归属:用户代码帧 vs 库/运行时帧须分开标注,给出修复入口。
4. 密钥/PII 提醒打码:若报错里含数据库密码、API key、用户 ID、手机号等敏感信息,立即提示用户打码后再分享,不在分析中复述敏感值。
5. 多层异常展开到最内层:Java Caused by:、Python During handling…、Go wrap error 链,都要展开找真正根因,不停在表层。
6. 不保证修复能 100% 解决:建议带验证方法,由用户确认后决定是否继续追查。
7. 不做任何写操作:只分析、建议;不修改文件、不执行命令、不推送代码。

边界

• 适用所有语言/运行时的文本格式报错;二进制 core dump 无法解读。
• 若报错只是警告(非致命),说明这是警告而非错误,不过度渲染成"崩溃"。
• 不替代调试器;若需运行时状态(变量值/内存),提示用户用 debugger/print 补充后再分析。