SuperAPI AI 工具集

diagnosing-bugs

编程与开发

查看项目

更新于 11-14 10:26

技能介绍

diagnosing-bugs 是一个针对疑难缺陷与性能回归的诊断技能,强调严格的分阶段纪律,只有在明确说明理由时才能跳过某个阶段。在探索代码库时,它要求先阅读 GLOSSARY.md(如果存在)以建立相关模块的心智模型,并检查所触及区域的 ADR。

保密与脱敏:该技能会展示命令、输出与捕获的产物,因此要求先对所有密钥进行脱敏,用 <REDACTED> 替代;反馈回路应基于环境变量构建,使凭据留在环境中而非出现在展示内容里;捕获产物中的鉴权头只引用承载信号的行。如果脱敏后的输出不足以诊断缺陷,应明确说明并向用户索取必要信息。

第一阶段:构建反馈回路。这是整个技能的核心,其余步骤都是机械性的。只要有针对该缺陷的紧致通过/失败信号(在该缺陷上会变红),就能找到原因;二分、假设检验、插桩都只是消费这个信号。构造方式大致按顺序包括:在能触达缺陷的接缝处编写失败测试(单元、集成、端到端);对运行中的开发服务器使用 curl/HTTP 脚本;带固定输入的 CLI 调用并与已知良好快照比对 stdout;用 Playwright/Puppeteer 编写无头浏览器脚本驱动 UI 并对 DOM/控制台/网络断言;重放捕获的 trace,把真实网络请求/负载/事件日志存盘后隔离重放;一次性最小化测试装置,拉起系统最小子集、模拟依赖,用单次函数调用触发缺陷路径;属性/模糊测试循环,对"有时输出错误"跑 1000 个随机输入寻找失败模式;二分测试装置,在已知两个状态(提交、数据集、版本)之间自动"在状态 X 启动、检查、重复"以支持 git bisect run;差分循环,把同一输入分别跑旧版与新版本(或两套配置)并比对输出;最后是人机协同 bash 脚本,若必须由人点击,则用 scripts/hitl-loop.template.sh 驱动人,保持结构化的回路并把输出回传。技能强调应在此投入不成比例的精力,积极、有创造力、拒绝放弃,认为构建好反馈回路后缺陷已解决 90%。

紧致化回路:把回路当作产品来打磨——能否更快(缓存初始化、跳过无关启动、收窄测试范围)、信号能否更锐利(针对具体症状断言而非"没有崩溃")、能否更确定(固定时间、播种 RNG、隔离文件系统、冻结网络)。30 秒的不稳定回路几乎不比没有回路好;2 秒的确定性回路才是调试超能力。对非确定性缺陷,目标不是干净复现而是更高的复现率:循环触发 100 次、并行化、加压、收窄时间窗口、注入 sleep;50% 的偶发缺陷可调试,1% 则不行,需持续提高复现率。

若确实无法构建回路,应停下并明确说明,列出尝试过的方法,并通过 AskUserQuestion 工具向用户索取:(a) 能复现问题的环境访问权限;(b) 脱敏后的捕获产物(HAR 文件、日志转储、核心转储、带时间戳的屏幕录制);(c) 允许添加临时生产插桩。没有回路不得进入假设阶段。第一阶段的完成标准是:能指名一条已至少运行过一次的命令(展示调用与脱敏输出),且该命令具备变红能力(驱动真实缺陷代码路径并断言用户的确切症状)、确定性(每次运行结论相同,偶发缺陷需固定并提高复现率)、快速(秒级而非分钟级)、可由智能体无人值守运行(人工介入仅通过 scripts/hitl-loop.template.sh)。若在命令存在前就开始读代码构建理论,应立即停止——这正是该技能要防止的失败。关键原则:无回路,无假设;没有变红能力的命令,不进入第二阶段。

第二阶段:复现与最小化。运行回路,观察其随缺陷出现而变红,确认产生的失败模式正是用户描述的症状而非附近的另一失败(错误缺陷等于错误修复),故障可跨多次运行复现(非确定性缺陷达到足够调试的复现率),并捕获确切症状(错误信息、错误输出、缓慢耗时)以便后续阶段验证修复。变红后把复现缩减到仍会变红的最小场景:逐个删减输入、调用方、配置、数据与步骤,每次删减后重跑回路,只保留对失败承重的部分。最小复现能缩小第三阶段的假设空间,并成为第五阶段的干净回归测试。完成标准是剩余每个元素都承重:移除任意一个都会让回路变绿。未复现并最小化前不得继续。

第三阶段:提出假设。在测试任何假设前生成 3–5 个有排序的假设,避免锚定在第一个看似合理的想法上。每个假设必须可证伪,说明其预测,格式为"若 是原因,则 会使缺陷消失/ 会使其更糟"。若无法陈述预测,该假设只是感觉,应丢弃或细化。测试前向用户展示排序列表,用户常凭领域知识立即重排(如"我们刚部署了第 3 项的改动")或指出现已排除的假设;这是廉价的检查点。不要因此阻塞,用户不在时按自己的排序继续。

第四阶段:插桩。每个探针须对应第三阶段的特定预测,一次只改变一个变量。工具优先级:环境支持时用调试器/REPL 检查(一个断点胜过十条日志);在能区分假设的边界处加定向日志;绝不"记录一切再 grep"。每条调试日志带唯一前缀如 [DEBUG-a4f2],结束时用一次 grep 清理;无标签的日志会存活,有标签的会消亡。性能分支:对性能回归,日志通常是错误工具,应先建立基线测量(计时装置、performance.now()、性能分析器、查询计划),再二分;先测量后修复。

第五阶段:修复与回归测试。只在存在正确接缝时先写回归测试。正确接缝是指测试能像调用点那样演练真实缺陷模式;若唯一可用接缝太浅(缺陷需要多个调用方时只测单个调用方,单元测试无法复现触发缺陷的链路),在此写回归测试会带来虚假信心。若无正确接缝,这本身就是发现,应记录下来,说明代码库架构阻碍了缺陷锁定,并留待下一阶段标注。有正确接缝时:把最小复现转为该接缝处的失败测试;观察其失败;若通过改动代码或测试夹具强制变红,需与原始副本比对以证明改动确实生效;应用修复;观察其通过;再对原始(未最小化)场景重跑第一阶段的反馈回路。

第六阶段:清理。宣布完成前必须确认:原始复现不再复现(重跑第一阶段回路);回归测试通过(或已记录缺失接缝);所有 [DEBUG-...] 插桩已用前缀 grep 清除;一次性原型已删除(或移至明确标记的调试位置);在提交/PR 信息中说明最终正确的假设,供后续调试者学习。随后通过 AskUserQuestion 询问什么本可预防该缺陷,选项包括:没有好的测试接缝/调用方纠缠/隐藏耦合/没有值得改变的,外加"其他"。若答案涉及架构变更(无好接缝、调用方纠缠、隐藏耦合),应将具体情况交给 /mattpocock:improve-codebase-architecture 技能。建议应在修复完成之后提出,因为此时掌握的信息比开始时更多。事后复盘之后,用 /mattpocock:code-review 审查修复——没有经过双轴审查的缺陷修复不算完成。

适用场景:疑难缺陷排查、报错/抛异常/失败/缓慢问题的系统化定位、性能回归、非确定性偶发缺陷。限制:要求环境支持构建可运行回路;无法构建回路时须停止并向用户索取访问权限或产物;高度依赖命令行与脚本能力。