用途:面向难以复现的硬缺陷和性能回退,提供一套分阶段的诊断纪律。可根据已有证据调整阶段顺序,但需说明任何实质性的验证缺口。探索代码库时,如存在 GLOSSARY.md 应阅读以建立相关模块的心智模型,并查看所触及区域的 ADR。
主要能力与流程:第一阶段构建反馈回路,这是核心,其余步骤相对机械。回路形式按大致顺序包括:在能到达缺陷的接缝写失败测试(单元、集成、e2e)、对运行中的开发服务器发起 curl/HTTP 脚本、带夹具输入的 CLI 调用并与已知良好快照对比 stdout、用 Playwright/Puppeteer 驱动 UI 并对 DOM/控制台/网络断言、回放捕获的 trace、一次性最小 harness、属性/模糊测试、二分 harness 以配合 git bisect run、新旧版本差分对比,以及最后的 HITL bash 脚本(scripts/hitl-loop.template.sh)。
回路的完成标准是紧凑且可红:能指出一条已至少运行过一次的命令(脚本路径、测试调用或 curl),它驱动真实缺陷代码路径、断言用户的确切症状,能对该缺陷变红并在修复后变绿,判定确定(非确定性缺陷需固定且较高的复现率),耗时以秒计,且可无人值守运行。随后要收紧回路:更快、信号更锐利、更确定。
第二阶段复现并最小化:运行回路观察变红,确认失败模式与用户描述一致而非邻近的其他失败,确认可多次复现,并捕获确切症状。然后逐步削减输入、调用方、配置、数据和步骤,每次削减后重跑,直到每个剩余元素都是承重的。
第三阶段提出可证伪假设,格式为“若 X 是原因,则 Y 会使缺陷消失/加重”,无法给出预测的假设应丢弃或锐化;向用户展示排序后的假设列表,用户可能凭领域知识立即重排。
第四阶段插桩:每个探针须对应第三阶段的特定预测,一次只改一个变量;优先调试器/REPL,其次在能区分假设的边界加定向日志,禁止“全量日志再 grep”;每条调试日志加唯一前缀如 [DEBUG-a4f2],便于最后一次性清理。性能回退分支中日志通常不对,应先建立基线测量(计时 harness、performance.now()、profiler、查询计划),再二分,先测量后修复。
第五阶段修复与回归测试:仅在存在正确接缝时先写回归测试,接缝须在调用点复现真实缺陷模式;若只有过浅接缝,回归测试会带来虚假信心;若无正确接缝,这本身就是发现,应记录并提示架构阻碍了缺陷锁定。有正确接缝时把最小化复现变成失败测试,看它失败,应用修复,看它通过,再对原始未最小化场景重跑第一阶段回路。
第六阶段清理:原始复现不再复现、回归测试通过(或记录无接缝)、所有 [DEBUG-...] 插桩被移除、一次性原型删除或移至明确标记的调试位置、把正确的假设写进提交或 PR 信息以惠及下一位调试者。
保密要求:展示命令、输出和捕获产物前须先脱敏,秘密位置写 <REDACTED>;回路应基于环境变量构建,使凭据留在环境中而非展示内容里;捕获产物可能含认证头,只引用承载信号的行。若脱敏后的输出不足以诊断,应说明并询问用户。真正无法构建回路时应停下来明确说明,列出尝试过的方法,并向用户请求:可复现的环境访问权限、脱敏后的捕获产物(HAR、日志转储、核心转储、带时间戳的录屏),或允许临时添加生产插桩;可继续只读分析,但假设须标注为暂定,不得把未验证假设当作原因,也不得声称修复已被证明。
严重限制:资料未提供安装命令、平台支持、许可、价格与官方仓库地址,暂未提供;所述内容为该技能页面的诊断方法论。