name: 根本原因追溯 description: 系统地向后追溯调用栈中的bug，以找到原始触发点 when_to_use: 当错误在深层执行时，需要追溯回找到原始触发点时使用 version: 2.0.0 languages: all progressive_disclosure: entry_point: summary: “通过调用链向后追溯bug，找到原始触发点，而不是修复症状” when_to_use: “当错误在深层执行时出现、数据来源不明确或调用链较长时。在系统调试第一阶段后使用。” quick_start: “1. 观察症状 2. 找到直接原因 3. 询问什么调用了这个 4. 继续向上追溯 5. 在源头修复+添加防御” references: - tracing-techniques.md - examples.md - advanced-techniques.md - integration.md context_limit: 800 tags:

调试
根因
追溯
调用栈

根本原因追溯

概述

Bug通常深层次地出现在调用栈中（例如在错误目录中执行git init、文件创建在错误位置、数据库以错误路径打开）。本能是修复错误出现的地方，但这是在处理症状。

核心原则： 通过调用链向后追溯，直到找到原始触发点，然后在源头修复。

这个技能是系统调试工作流中的一个专门技术，通常在处理深层调用栈时应用于第一阶段（根因调查）。

何时使用此技能

在以下情况使用根因追溯：

错误发生在深层执行时（非入口点）
堆栈跟踪显示长调用链
不清楚无效数据从哪里来
需要找到哪个测试/代码触发了问题
症状远离实际原因出现

与系统调试的关系：

系统调试：整体框架（第一阶段至第四阶段）
根因追溯：第一阶段调查的具体技术
在系统调试的第一阶段内使用根因追溯

铁律

绝不只修复错误出现的地方
总是追溯回找到原始触发点

修复症状会创造创可贴式解决方案，掩盖根本问题。

核心原则

向后追溯： 从症状到源头的调用链
找到原始触发点： 识别坏数据/状态的起源
在源头修复： 处理根因，而非症状
深度防御： 在修复源头后在每一层添加验证

快速开始

五步追溯过程

观察症状： 错误消息是什么？哪个操作失败了？
找到直接原因： 什么代码直接导致了此错误？
询问什么调用了这个： 追溯调用栈的一层向上
继续向上追溯： 持续直到找到原始触发点
在源头修复+防御： 修复根因并添加层验证

决策树

错误出现在深层堆栈？
  → 是：开始向后追溯
    → 能识别调用者？ → 追溯一层向上 → 重复
    → 不能识别调用者？ → 添加仪器化（见高级技术）
  → 否：可能不需要追溯（错误在入口点）

追溯过程

示例：在错误目录中执行git init

错误症状 → execFileAsync('git', ['init'], { cwd: '' })
  ← WorktreeManager.createSessionWorktree(projectDir='')
  ← Session.create() → Project.create() → 测试代码
  ← 根原因：setupCoreTest() 在beforeEach之前返回 { tempDir: '' }

在每一层询问： 这个值从哪里来？这是起源吗？

详细追溯方法论，见追溯技术 完整现实示例，见示例

找到根因后

在源头修复（如果访问前未初始化则抛出异常）+ 添加深度防御（在Project.create、WorkspaceManager、环境防护、仪器化处验证）。

这防止类似bug并更早捕获问题。

关键提醒

绝不只修复错误出现的地方
总是追溯回找到原始触发点
在测试中使用 console.error() 进行调试（日志记录器可能被抑制）
在危险操作前记录，而不是在失败后
包含上下文：目录、cwd、环境、时间戳
在修复源头后添加深度防御
记录追溯过程（写下调用链）

红旗 - 停止

如果你发现自己想：

“我只是在这里添加验证”（未找到源）
“这会防止错误”（症状修复）
“追溯太难”（改为添加仪器化）
“现在快速修复”（创造技术债务）

所有这些意味着：继续追溯以找到根因。

与其他技能的集成

系统调试： 在第一阶段使用根因追溯
深度防御： 找到根因后添加
完成前验证： 在源头验证修复是否有效
测试驱动开发： 为根因编写测试，而非症状

见集成获取完整工作流示例。

现实影响

从调试会话（2025-10-03）：

通过五级追溯找到根因
在源头修复（获取器验证）
添加4层防御
1847个测试通过，零污染
节省时间：比症状修复方法节省3+小时

底线： 追溯花费15-30分钟。症状修复花费数小时打地鼠式工作。

根本原因追溯Skill RootCauseTracing