# Error Explain Zh

> 粘贴任意语言的报错/堆栈/panic/exception,给中文根因分析与可操作修复建议。当用户说「帮我看这个报错/分析这个错误/这个 panic 是什么意思/帮我 debug」时触发。

- Skill: `yuaicode/error-explain-zh` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yuaicode/error-explain-zh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuaicode/error-explain-zh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: YuAICode (https://skillmd.com/u/yuaicode)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuaicode/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 等)

## 输出模板

```markdown
## 错误类型

<语言/运行时> — <错误大类>(如: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 补充后再分析。