SuperAPI AI 工具集

root-cause-tracing

通用与其它

查看项目

更新于 10-16 08:49

技能介绍

用途:当错误发生在执行深层而非入口处、栈追踪显示较长的调用链、无法确定无效数据来源、或需要找出是哪个测试或代码触发问题时,可借助本技能系统地反向追溯 bug,定位原始触发点并在源头修复,而非只修复报错处。

主要能力与做法:先观察症状(例如 git init 在错误目录失败),找到直接原因的代码,再逐层追问“是谁调用了它”,沿着 WorktreeManager、Session、测试等调用链向上追踪,检查传入的值(如 projectDir 为空字符串,空 cwd 会解析为 process.cwd()),最终定位原始触发点。无法手动追踪时,可在危险操作前加入插桩:用 new Error().stack 打印调用链,记录目录、cwd、环境变量、时间戳等上下文;测试中用 console.error() 而非 logger,因为 logger 可能被抑制。可用 npm test 2>&1 | grep 'DEBUG git init' 捕获输出,再分析栈追踪中的测试文件名、行号和参数模式。若不清楚哪个测试造成污染,可使用随附的 @find-polluter.sh 逐一运行测试并在第一个污染者处停止,例如 ./find-polluter.sh '.git' 'src/**/*.test.ts'。

示例与原则:资料给出的真实案例中,.git 被创建到源码目录,经五层追踪发现是测试在 beforeEach 之前访问了空的 context.tempDir;修复方式是让 tempDir 改为 getter 并在过早访问时抛错,同时增加四层防御:Project.create() 校验目录、WorkspaceManager 校验非空、NODE_ENV 守卫拒绝在 tmpdir 外执行 git init、git init 前记录栈追踪。关键原则:绝不只是修复错误出现的位置,要回溯到原始触发点,并在每一层补充校验,使 bug 不可能发生。

适用场景与限制:适用于调试具有明确调用链的错误、测试污染定位和参数来源追查。资料未提供安装命令、收费或平台支持信息;部分脚本用法需参考随附脚本本身,本技能不替代对具体代码库的理解。