changan-su/forsion/debugging-methodology

调试方法论

核心循环:复现 → 缩小范围 → 假设 → 验证

禁止跳过复现直接改代码。每轮循环只验证一个假设,改一处变量。

1. 复现

• 用 run_bash 实际跑出错误,拿到一手报错原文,不要只依赖用户转述。
• 记录精确复现步骤和环境(命令、参数、输入数据、Node/Python 版本)。
• 不能稳定复现的(疑似竞态/环境相关),先想办法提高复现率:循环跑 N 次、加并发、固定随机种子。
• 把复现固化成一条可重复执行的命令,后续每轮验证都跑它。

2. 缩小范围

• 二分定位:
• 代码维度:注释/短路一半逻辑,看错误是否还在,逐步逼近出错行。
• 历史维度:git log --oneline 找最近改动;怀疑回归时用 git bisect start && git bisect bad && git bisect good <sha>,每步跑复现命令。
• 数据维度:把触发输入裁剪到最小仍能复现的子集。
• 用 search_files 找错误信息的抛出点:search_files("错误文本关键词"),再沿调用链向上读。
• 先确认错误发生在哪一层(输入解析/业务逻辑/IO/第三方库),再深入。

3. 假设

• 基于证据写出明确假设:"我认为 X 导致 Y,因为观察到 Z"。
• 同时列 2-3 个候选假设,按可能性排序,先验证最廉价可证伪的。

4. 验证

• 设计一个假设为真则必然出现、为假则必然不出现的实验(加断言、构造输入、隔离最小用例)。
• 验证失败就回到第 2 步,不要在同一个假设上反复打转超过两轮。

加日志的位置选择

• 加在边界上:函数入口/出口、IO 调用前后、分支决策点——而不是随手散在中间。
• 打印值与类型,不要只打 "here1/here2":console.log('[dbg] userId=', userId, typeof userId)。
• 异步/并发问题带上时间戳和标识(请求 id、线程名)。
• 统一加 [dbg] 前缀,方便最后 search_files("\\[dbg\\]") 一键清理。

读 stack trace 的方法

1. 先读最底部的根因异常(caused by),再读顶部。
2. 自上而下找第一帧属于本项目代码的位置(跳过框架/node_modules 帧),那通常是切入点。
3. 报错信息里的值要当线索用:undefined is not a function → 是谁 undefined?ENOENT → 哪个路径?
4. 异步栈可能断裂:Promise 链中的报错栈不含发起方,需在调用处补 try/catch 或日志接回上下文。

症状 → 常见原因对照

环境类问题统一验证法:run_bash 打印实际生效的值——node -v、which python、echo $XXX、npm ls <pkg>,和预期逐项比对。

修复后的收尾(必做)

1. 重跑复现命令确认症状消失;再跑相关测试套件确认无回归。
2. 解释得通才算修好:能说清"为什么之前会错、为什么这个改动修好了"。只是症状消失但原因不明的,继续查,警惕掩盖式修复(如随手加 try/catch 吞错、sleep 绕过竞态)。
3. 清理调试代码:search_files("\\[dbg\\]") 找出所有调试日志删除;git diff 全量过一遍,确认 diff 里只剩真正的修复。
4. 如果是值得记录的坑,向用户提议补一个回归测试。