全部指南
指南指南更新于

用可比较的修复前后证据排查缺陷

复现本地缺陷,保留失败基线,并在最小修复后比较同样检查。通过命令结果与被监测文件哈希说明实际验证范围。

快速开始

让 AI 助手帮你完成

将这段提示粘贴到你正在使用的 AI 助手中:

使用 Debug Evidence Kit 排查明确限定范围的本地缺陷。先询问预期行为、实际行为、有限复现命令及相关源码和测试。采集失败基线,做最小修复,保持被监测测试不变并重新运行同样命令。生成到新目录前,检查被采集进程的退出码、完整日志与哈希。缺失证据标记为未知,分享前审核私有日志。

修复报告怎样才有可信依据?

Debug Evidence Kit 在改动前后采集有限本地命令,再生成证据报告。可比较命令、完整日志、稳定输入与保留测试至关重要。检查通过支持该复现路径,并不证明所有功能或生产服务正常。

修改代码前定义复现方式

  • 说明预期行为、实际行为、最小输入与相关源码和测试。阅读 references/diagnosis.md,并使用目标项目实际运行环境。
  • 使用明确的有限命令、固定工作目录及被监测源码和测试路径。采集工具不经 shell 执行参数,并限制时间与输出。
  • 修复前保存失败基线。保持被监测测试文件不变,并检查采集结果中的 exitCode,不依赖采集包装器的退出状态。

区分证据保存与检查通过

各类观察结果能说明什么
观察结果支持的结论下一项检查
采集包装器以零退出证据文件已写入检查被采集状态、exitCode 与截断情况
同一失败检查现在以零退出限定范围的复现现在通过比较源码及未改动测试哈希,运行相邻检查
命令不同或日志不完整比较需要更多证据重新采集可比较结果,不要宣称已验证修复

运行隔离的修复前后练习

从内容包目录,使用 Python 3.10 及以上可执行 references/first-run.md 中仅依赖标准库的练习。它复制虚构数值排序函数,运行实际失败测试,只修复复制后的源码,再运行未改动测试,保留安装包不变。打开 practice-debug/report/index.html 及其私有证据文件。

python3 scripts/run-example.py --output ./practice-debug

不自动修复,亲手练习排查过程

单命令示例是引导演示。若要亲手练习排查,在安装包目录创建新副本。以下命令采集失败测试,不修改已安装示例。即使被采集测试失败,采集命令也可能因证据保存成功而以零退出。检查 practice-manual-evidence/before.json,其中 exitCode 应为非零。

cp -R examples/fixture ./practice-manual-project
python3 -B scripts/capture-check.py --cwd ./practice-manual-project --watch sort_prices.py --watch test_sort_prices.py --label baseline --output ./practice-manual-evidence/before.json -- python3 -B -m unittest test_sort_prices

修改一个表达式,再运行未改动测试

先阅读断言并解释原因:将数字当作字符串排序,会让 10 排在 2 前面。仅在 practice-manual-project/sort_prices.py 中,将 sorted(values, key=str) 替换为 sorted(values)。保持 practice-manual-project/test_sort_prices.py 不变,再执行以下命令。打开 practice-manual-report/index.html。可信结果应包含修复前非零 exitCode、修复后零 exitCode、变化的源码哈希、不变的测试哈希与八项通过比较。

作为反向对照,将 after.json 复制为新证据文件,改变其中 argv,再用该文件生成另一份报告。结果应为 needs-evidence。这验证比较完整性,不证明任意真实修复正确。不要修改原始采集文件。

python3 -B scripts/capture-check.py --cwd ./practice-manual-project --watch sort_prices.py --watch test_sort_prices.py --label post-fix --output ./practice-manual-evidence/after.json -- python3 -B -m unittest test_sort_prices
python3 -B scripts/build-case.py --input examples/case.json --before ./practice-manual-evidence/before.json --after ./practice-manual-evidence/after.json --output ./practice-manual-report

核对比较过程,不只看绿色标签

  • 检查 evidence/before.json 与 evidence/after.json:同样命令应在修复前失败、修复后通过,每次运行日志完整且被监测文件稳定。
  • 示例报告应显示 reproduction-now-passing 与八项通过比较。源码哈希应变化,被监测测试哈希应相同。这是针对虚构示例代码的实际执行。
  • 实际项目先增加有意义的回归测试,再用同一被监测测试采集约定基线与修复后检查。运行相关相邻测试,分别记录验证范围。

用审核后的日志说明限定范围的修复

说明缺陷、改动与观察结果,不将通过检查直接当作根因证明。缺失或不可比较证据保持未知。私有采集文件可能包含路径、日志与敏感值;脱敏尽力而为,分享前应审核。生产部署与线上验证仍需另行完成。

全部指南