SuperAPI AI 工具集

bug-diagnosis

编程与开发

查看项目

更新于 11-09 13:12

技能介绍

用途

Bug Diagnosis 是一个用于诊断“已经扛过第一轮明显修复”的疑难 bug 的技能。它的核心目标不是快速打补丁,而是找到并锁定根因。技能强调固定的纪律顺序:先构建能在秒级断言“bug 存在/不存在”的信号,再写下可被证伪的竞争假设,测试最便宜且最可能的假设,通过二分法缩小搜索空间,最后用一条曾被看到失败的回归测试锁定原因。

主要能力

  • 构建可复现信号:按 bug 类型选择合适的测试夹具(失败测试、请求重放、CLI 运行、计时工具、版本间差分),模板提供 0/1/125 退出码契约,可直接用于 git bisect run。要求信号断言具体症状、固定时钟/随机种子/语言环境/网络/工作进程数,并多次运行记录红绿。
  • 假设管理与排序:要求写出 3–5 个假设,每个包含机制和可证伪预测(“如果 X 是原因,那么改变 Y 会使症状消失”),并给出先验概率(0–1)和实验成本(分钟)。验证器按先验÷成本排序开放假设,拒绝模糊预测、多变量实验和无证据的确认。
  • 二分定位:支持提交(git bisect)、输入、配置/依赖三种二分场景,并提供决策框架说明何时优先二分、何时优先假设。
  • 插桩与脱敏:用唯一标记(如 [DBG-7c1e])标记临时日志行,避免打印完整请求对象、头部或环境转储。在分享任何输出前,使用 redact_scan.py 扫描并生成脱敏副本,用眼睛检查副本后只粘贴携带信号的日志行。
  • 修复与回归测试:将最小化复现转化为测试,在修改代码前先看到它因报告的症状而失败,应用最小修复后运行测试和原始未最小化信号,清理调试标记,并在提交信息中记录确认的假设和证据。

使用方式

技能提供两个脚本:

  • scripts/hypothesis_log.py:对诊断日志进行门禁检查,包括复现质量、可证伪预测、单变量实验、停止规则和修复完整性,并按先验÷成本排序开放假设。退出码:0 通过,1 门禁失败,2 输入不可读。
  • scripts/redact_scan.py:检测密钥、令牌、JWT、认证/ cookie 头、URL 凭据、秘密赋值、高熵块及可选 PII,并写出脱敏副本。退出码:0 干净,1 发现敏感信息,2 读取错误。

两者均支持 --format text|json,阈值通过参数调整:--max-runtime、--min-red-rate、--min-hypotheses、--stop-after、--min-entropy。

快速开始示例:

# 验证诊断日志并查看下一个要测试的假设
python3 engineering/bug-diagnosis/scripts/hypothesis_log.py \
  --input engineering/bug-diagnosis/assets/sample_diagnosis_log_passing.json

# 在粘贴日志前检查文件中的秘密信息
python3 engineering/bug-diagnosis/scripts/redact_scan.py \
  --paths engineering/bug-diagnosis/assets/sample_debug_log.txt --pii

技能还提供参考文档(references/reproduction-signals.md 和 references/bisection-instrumentation-redaction.md)、诊断日志模板、复现脚本模板,以及示例日志文件(其中一个故意有缺陷,验证器退出 1;一个格式良好,验证器退出 0)。

适用场景

  • 首次修复后症状复发或转移
  • 间歇性失败(本地通过、CI 五次一次失败)
  • 两个版本之间出现回归,不知道哪个改动导致
  • 症状远离原因(错误总计、记录损坏、无错误挂起)
  • 性能回归需要测量原因而非猜测
  • 需要与同事、供应商或助手共享日志/跟踪且可能包含凭据

限制

  • 明确不覆盖:已知原因后的最小代码修改范围(由 focused-fix 技能负责)、生产事故指挥/分页/客户沟通、安全漏洞分类与利用分析、附加调试器或性能分析器。
  • redact_scan.py 仅匹配已知格式和高熵特征,可能漏掉专有令牌格式、拆分秘密和上下文相关个人数据,分享前必须人工阅读脱敏副本。
  • 假设日志中的先验概率是判断而非测量,排序质量取决于这些估计;每次结果后需重新排序。
  • 验证器只检查日志结构和纪律,不验证所述证据的真实性。
  • 若 90 分钟内无法建立信号、连续 4 个实验无结论、所有假设被反驳、修复需要超出约定影响范围、或复现需要生产数据/写入,应停止并报告所需条件。