系统化诊断和修复各类代码错误的工作流。遵循 复现 → 定位 → 理解 → 修复 → 验证 五步法，避免凭直觉猜测式改代码。
用户报错 → [Step 1 复现] → [Step 2 定位] → [Step 3 理解] → [Step 4 修复] → [Step 5 验证] → 结案
↑_____________ 证据不足时回到 Step 1 _____________↓
目标：稳定复现问题，收集完整错误上下文。
必须收集的信息（缺一不可，逐项核对）：
执行动作：
node --version, python --version, go version 等）产出： 清晰的错误描述 + 可复现的步骤
目标：缩小问题范围，找到根因所在的精确位置。
定位策略（优先级从高到低）：
| 策略 | 适用场景 | 方法 |
|---|---|---|
| ------ | --------- | ------ |
| 二分法 | 大段代码/多文件 | 注释掉一半代码，看错误是否消失；重复直到定位 |
| 堆栈追踪 | 运行时异常/崩溃 | 从栈顶往栈底读，找到第一个你自己的代码 |
| 差异对比 | 之前能工作现在不行 | git diff，git blame 找到最近修改 |
| 最小化输入 | 输入数据导致异常 | 逐步缩小输入，找到触发异常的精确数据 |
| 断言/日志 | 逻辑错误/静默失败 | 在关键路径插入临时日志或断言 |
| 依赖分析 | 编译/运行时依赖错误 | 检查 package.json / go.mod / requirements.txt 版本约束 |
执行动作：
console.log / print / fmt.Println🔴 铁律：在没有定位到具体哪一行/哪个变量前，禁止进行修复。
目标：彻底理解根因——回答"为什么会产生这个错误"。
🔴 铁律：不能解释根因，就不能开始修复。
目标：最小改动、精准修复。
目标：确认修复有效且没有引入新问题。
如果验证失败 → 回到 Step 1。
| 类型 | 快速定位技巧 |
|---|---|
| ------ | ------------- |
| 类型错误 (TypeScript) | 从第一个错误开始修复（后续往往只是级联） |
| 语法错误 | 检查括号/引号/逗号配对，模板字符串中的反引号 |
| 导入错误 | ImportError / ModuleNotFoundError — 检查路径、大小写、__init__.py |
| 链接错误 | 检查库版本、ABI 兼容性、链接库路径 |
| 异常 | 常见根因 |
|---|---|
| ------ | --------- |
NullPointerException / Cannot read property of undefined | 异步数据未加载、可选链缺失、初始值未设 |
TypeError: X is not a function | 导入错误、变量覆盖、调用时机过早 |
IndexError / IndexOutOfBounds | off-by-one 错误、空列表、边界条件 |
StackOverflow | 无限递归、事件循环、循环依赖 |
OutOfMemoryError | 内存泄漏、大对象未释放、数据量超出预期 |
| 类型 | 诊断方法 |
|---|---|
| ------ | --------- |
| 条件分支错误 | 列出所有分支 + 输入组合，逐一验证 |
| 循环/遍历错误 | 追踪循环变量变化，检查边界条件 |
| 异步/并发错误 | 检查 race condition，添加锁或原子操作 |
| 状态管理错误 | 追踪状态变更链路，检查不可变性 |
| 浮点精度 | 不直接比较浮点数，使用 epsilon 或 Decimal |
| 问题 | 诊断方法 |
|---|---|
| ------ | --------- |
| 版本冲突 | npm ls , go mod graph, pipdeptree |
| 环境差异 | 对比开发/测试/生产环境的 .env 和配置文件 |
| 缓存问题 | 清除缓存：node_modules, pip cache, Go build cache |
| 平台差异 | 路径分隔符、换行符（CRLF vs LF）、文件权限 |
| 问题 | 诊断方法 |
|---|---|
| ------ | --------- |
| API 返回值异常 | curl / 浏览器检查真实响应，验证接口文档 |
| 数据格式不对 | 检查 JSON Schema、边界类型（空数组/null/缺失字段） |
| 编码问题 | UTF-8 vs GBK、BOM、特殊字符转义 |
不要同时修复多个无关问题。每个修复独立验证，否则无法确定哪个改动有效。
每个结论必须由数据支持：堆栈、日志、变量值、测试结果。禁止脑补根因。
如果能构造最小复现（Minimal Reproducible Example），优先用它调试。MRE 本身往往就已经揭示了根因。
如果问题复杂且时间紧迫，回退到上次正常工作的版本好过胡乱修复引入更多问题。
# 检查 Node 版本和类型定义
node --version && npx tsc --version
# 检查依赖版本冲突
npm ls <package-name> # 已安装的版本树
npm outdated # 可更新的包
npx synp --source-file # yarn.lock ↔ package-lock.json 转换检查
# 清除缓存
rm -rf node_modules && npm install
# 或
npm cache clean --force
# 检查 Python 版本和虚拟环境
python --version && which python
pip list | grep <package>
# 依赖树
pipdeptree -p <package>
# 重新安装
pip install --force-reinstall <package>
go version
go env GOPATH GOROOT
go mod graph | grep <package>
go mod tidy
rustc --version && cargo --version
cargo tree -p <crate>
cargo clean && cargo build
当用户报告错误时，按以下结构回复：
共 1 个版本