Index of every page on this site: llms.txt
All skills
victory-hugo avatar

/systematic-debugging

@0b19307
Run it yourself

遇到任何 bug、测试失败或异常行为时使用,在提出修复方案之前执行

  • 11 files
  • 39.9 KB
  • Updated 5 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/victory-hugo/s2-agent-skill/systematic-debugging

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

root-cause-tracing.md

≈1.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

根因追踪

概述

Bug 通常表现在调用栈深处(在错误目录执行 git init、在错误位置创建文件、用错误路径打开数据库)。你的本能是在错误出现的地方修复,但那只是治标。

核心原则: 沿着调用链反向追踪,直到找到最初的触发点,然后在源头修复。

何时使用

digraph when_to_use {
    "Bug 出现在调用栈深处?" [shape=diamond];
    "能反向追踪吗?" [shape=diamond];
    "在症状处修复" [shape=box];
    "追踪到最初的触发点" [shape=box];
    "更好的做法:同时添加纵深防御" [shape=box];

    "Bug 出现在调用栈深处?" -> "能反向追踪吗?" [label="是"];
    "能反向追踪吗?" -> "追踪到最初的触发点" [label="是"];
    "能反向追踪吗?" -> "在症状处修复" [label="否——死胡同"];
    "追踪到最初的触发点" -> "更好的做法:同时添加纵深防御";
}

适用场景:

  • 错误发生在执行深处(不在入口点)
  • 堆栈跟踪显示很长的调用链
  • 不清楚无效数据从哪里来
  • 需要找到是哪个测试/代码触发了问题

追踪流程

1. 观察症状

Error: git init failed in /Users/jesse/project/packages/core

2. 找到直接原因

哪段代码直接导致了这个错误?

await execFileAsync('git', ['init'], { cwd: projectDir });

3. 问:谁调用了它?

WorktreeManager.createSessionWorktree(projectDir, sessionId)
  → 被 Session.initializeWorkspace() 调用
  → 被 Session.create() 调用
  → 被测试中的 Project.create() 调用

4. 继续向上追踪

传入了什么值?

  • projectDir = ''(空字符串!)
  • 空字符串作为 cwd 会解析为 process.cwd()
  • 那就是源代码目录!

5. 找到最初的触发点

空字符串从哪里来的?

const context = setupCoreTest(); // 返回 { tempDir: '' }
Project.create('name', context.tempDir); // 在 beforeEach 之前就访问了!

添加堆栈跟踪

当无法手动追踪时,添加诊断埋点:

// 在有问题的操作之前
async function gitInit(directory: string) {
  const stack = new Error().stack;
  console.error('DEBUG git init:', {
    directory,
    cwd: process.cwd(),
    nodeEnv: process.env.NODE_ENV,
    stack,
  });

  await execFileAsync('git', ['init'], { cwd: directory });
}

重要: 在测试中使用 console.error()(而非 logger——可能不会显示)

运行并捕获:

npm test 2>&1 | grep 'DEBUG git init'

分析堆栈跟踪:

  • 找测试文件名
  • 找触发调用的行号
  • 识别模式(同一个测试?同一个参数?)

找出导致污染的测试

如果某些现象在测试期间出现,但你不知道是哪个测试造成的:

使用本目录下的二分查找脚本 find-polluter.sh:

./find-polluter.sh '.git' 'src/**/*.test.ts'

逐个运行测试,在第一个"污染者"处停止。详见脚本中的使用说明。

真实案例:空的 projectDir

症状: .git 被创建在 packages/core/(源代码目录)中

追踪链:

  1. git init 在 process.cwd() 中执行 ← cwd 参数为空
  2. WorktreeManager 被传入空的 projectDir
  3. Session.create() 传递了空字符串
  4. 测试在 beforeEach 之前访问了 context.tempDir
  5. setupCoreTest() 初始返回 { tempDir: '' }

根本原因: 顶层变量初始化时访问了空值

修复: 将 tempDir 改为 getter,在 beforeEach 之前访问时抛出异常

同时添加了纵深防御:

  • 第 1 层:Project.create() 校验目录
  • 第 2 层:WorkspaceManager 校验非空
  • 第 3 层:NODE_ENV 守卫拒绝在 tmpdir 之外执行 git init
  • 第 4 层:git init 前记录堆栈跟踪

关键原则

digraph principle {
    "找到了直接原因" [shape=ellipse];
    "能向上追踪一层吗?" [shape=diamond];
    "反向追踪" [shape=box];
    "这就是源头吗?" [shape=diamond];
    "在源头修复" [shape=box];
    "在每一层添加校验" [shape=box];
    "Bug 不可能再发生" [shape=doublecircle];
    "绝不只修症状" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    "找到了直接原因" -> "能向上追踪一层吗?";
    "能向上追踪一层吗?" -> "反向追踪" [label="是"];
    "能向上追踪一层吗?" -> "绝不只修症状" [label="否"];
    "反向追踪" -> "这就是源头吗?";
    "这就是源头吗?" -> "反向追踪" [label="否——继续追踪"];
    "这就是源头吗?" -> "在源头修复" [label="是"];
    "在源头修复" -> "在每一层添加校验";
    "在每一层添加校验" -> "Bug 不可能再发生";
}

绝不只在错误出现的地方修复。 反向追踪,找到最初的触发点。

堆栈跟踪技巧

在测试中: 使用 console.error() 而非 logger——logger 可能被抑制 操作之前: 在危险操作之前记录日志,而不是在失败之后 包含上下文: 目录、cwd、环境变量、时间戳 捕获堆栈: new Error().stack 能显示完整的调用链

实际效果

来自调试实践(2025-10-03):

  • 通过 5 层追踪找到了根本原因
  • 在源头修复(getter 校验)
  • 添加了 4 层纵深防御
  • 1847 个测试通过,零污染

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 0b19307. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 5 months ago

README badge

README badge for victory-hugo/s2-agent-skill/systematic-debugging