SuperAPI AI 工具集

diagnosing-bugs

编程与开发

查看项目

更新于 11-04 04:19

技能介绍

用途:该技能是一套面向疑难缺陷(hard bugs)和性能回归的纪律化诊断循环,适用于用户说“diagnose”“debug this”,或报告某处损坏、抛错、失败、变慢的情况。整体流程只有在明确给出理由时才允许跳过阶段。在浏览代码库时,若存在 GLOSSARY.md 应阅读以建立相关模块的清晰心智模型,并查看所触及领域的 ADR。

安全与脱敏:该技能会要求展示命令、输出和捕获的产物,因此必须先对所有密钥脱敏,用 <REDACTED> 替代。回路应基于环境变量构建,让凭证留在环境中而不出现在展示内容里。捕获的产物可能带有认证头,只引用承载信号的行。若脱敏后的输出不足以诊断缺陷,应如实说明并向用户询问。

阶段一:构建反馈回路。这是该技能的核心,其余都是机械性工作。若对缺陷拥有紧致的通过/失败信号(在该缺陷上会变红),就能找到原因;二分、假设检验和插桩都只是消费它。若没有,单靠盯着代码无法解决问题。应在此投入不成比例的精力,积极、有创意、不轻言放弃。构建方式大致按顺序包括:在能触及缺陷的接缝处写失败测试(单元、集成、e2e);对运行中的开发服务器执行 curl/HTTP 脚本;用固定输入调用 CLI 并将 stdout 与已知良好快照做 diff;用无头浏览器脚本(Playwright/Puppeteer)驱动 UI 并对 DOM/控制台/网络做断言;重放捕获的 trace(把真实网络请求/载荷/事件日志存盘,隔离地经代码路径重放);一次性测试架(最小子系统加模拟依赖,用单次函数调用走缺陷路径);属性/模糊循环(若缺陷是“有时输出错误”,跑 1000 个随机输入寻找失败模式);二分测试架(缺陷出现在两个已知状态之间时,自动化“在状态 X 启动、检查、重复”以便 git bisect run);差分回路(同一输入分别经旧版与新版或两种配置,diff 输出);最后手段是 HITL bash 脚本(若必须人工点击,用 scripts/hitl-loop.template.sh 驱动,使回路仍有结构,捕获输出回传)。构建好正确的反馈回路,缺陷就解决了 90%。

收紧回路:把回路当产品对待。能否更快(缓存初始化、跳过无关初始化、缩小测试范围)?能否让信号更锐利(断言具体症状而非“没崩”)?能否更具确定性(固定时间、设置随机种子、隔离文件系统、冻结网络)?30 秒的易抖回路几乎不比没有好;2 秒的确定性回路才是调试超能力。

非确定性缺陷:目标不是干净复现,而是更高的复现率。可将触发循环 100 次、并行化、加压、收窄时间窗口、注入 sleep。50% 概率抖动的缺陷可调试,1% 则不行,应持续提高复现率直到可调试。

确实无法构建回路时:停下并明确说明,列出尝试过的内容,向用户请求:(a) 访问能复现问题的环境;(b) 脱敏的捕获产物(HAR 文件、日志转储、core dump、带时间戳的屏幕录制);或 (c) 允许添加临时生产插桩。没有回路不得进入假设阶段。完成标准是得到紧致且能变红的回路:能说出一个已至少运行过一次的命令(脚本路径、测试调用、curl),展示其调用与脱敏输出,且该命令:能变红(驱动真实缺陷代码路径并断言用户的确切症状,修复后变绿,而非仅“运行无错”)、确定(每次判定一致;抖动缺陷则按上文达到固定的高复现率)、快速(秒级而非分钟级)、可由代理无人值守运行(人工仅通过 scripts/hitl-loop.template.sh 介入)。若在该命令存在前就读代码建立理论,应停下:直接跳到假设正是该技能要防止的失败。没有能变红的命令,就不进入阶段二。

阶段二:复现与最小化。运行回路,观察缺陷出现时变红。确认:回路产生的是用户描述的失败模式而非恰好邻近的另一种失败(错缺陷等于错修复);失败在多次运行中可复现(非确定性缺陷则达到足够高的复现率);已捕获确切症状(错误消息、错误输出、缓慢计时),供后续阶段验证修复确实针对它。最小化:变红后把复现收缩到仍能变红的最小场景,逐个削减输入、调用方、配置、数据与步骤,每次削减后重跑回路,只保留对失败承重的部分。原因是:最小复现缩小阶段三的假设空间(更少可怀疑的活动部件),并成为阶段五的干净回归测试。完成标准是每个剩余元素都承重:移除任何一项都会让回路变绿。未复现并最小化前不得继续。

阶段三:假设。在检验任何假设前生成 3–5 个排序假设。单一假设生成会锚定在第一个看似合理的想法上。每个假设必须可证伪:说明它做出的预测。格式:“若是原因,则会使缺陷消失/会使其更糟。”若无法陈述预测,该假设只是感觉:丢弃或锐化。检验前向用户展示排序列表;他们常有领域知识可立即重排(“我们刚部署了 #3 的改动”),或知道已排除的假设。这是低成本检查点、能大幅省时;不必阻塞,用户不在时按自己的排序继续。

阶段四:插桩。每个探针必须对应阶段三的具体预测。一次只改变一个变量。工具偏好:环境支持时用调试器/REPL 检查,一个断点胜过十行日志;在能区分假设的边界处做定向日志;绝不“全量记录再 grep”。每个调试日志打上唯一前缀如 [DEBUG-a4f2],清理时只需一次 grep;未打标签的日志会存活,打了标签的会消亡。性能分支:性能回归时日志通常是错的,应先建立基线测量(计时测试架、performance.now()、profiler、查询计划),再二分。先测量,后修复。

阶段五:修复与回归测试。在修复前先写回归测试,但仅当存在正确接缝。正确接缝是指测试能按调用点发生的真实缺陷模式来演练。若唯一可用接缝过浅(缺陷需多调用方时却只做单调用方测试,单元测试无法复现触发缺陷的链条),此处的回归测试会带来虚假信心。若不存在正确接缝,这本身就是发现,应记录:代码库架构阻碍了缺陷被锁定,并标注给下一阶段。若有正确接缝:把最小复现变成该接缝处的失败测试,观察它失败,应用修复,观察它通过,再对原始(未最小化)场景重跑阶段一的反馈回路。

阶段六:清理。宣布完成前必须:原始复现不再复现(重跑阶段一回流);回归测试通过(或已记录缺乏接缝);所有 [DEBUG-...] 插桩已移除(grep 该前缀);一次性原型已删除(或移到明确标记的调试位置);在 commit/PR 消息中说明最终正确的假设,让下一位调试者受益。

阅读材料:路径相对于仓库根目录。GLOSSARY.md 和 docs/adr/ 中的 ADR 提供项目领域语言及所触及领域的决策;若缺失,则在无它们的情况下探索。