用可比较的修复前后证据排查缺陷
复现本地缺陷,保留失败基线,并在最小修复后比较同样检查。通过命令结果与被监测文件哈希说明实际验证范围。
快速开始
让 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 与八项通过比较。源码哈希应变化,被监测测试哈希应相同。这是针对虚构示例代码的实际执行。
- 实际项目先增加有意义的回归测试,再用同一被监测测试采集约定基线与修复后检查。运行相关相邻测试,分别记录验证范围。
检查当前示例产出 → — 将可见结果与本节说明的导出文件和检查对应起来。
用审核后的日志说明限定范围的修复
说明缺陷、改动与观察结果,不将通过检查直接当作根因证明。缺失或不可比较证据保持未知。私有采集文件可能包含路径、日志与敏感值;脱敏尽力而为,分享前应审核。生产部署与线上验证仍需另行完成。
检查失败属于安装还是执行 — 可复现应用缺陷与技能缺失需要不同修复。