SuperAPI AI 工具集

debugging-by-constraints

编程与开发

查看项目

更新于 10-27 18:31

技能介绍

用途

这是一个用于生产环境缺陷和 PR 审查发现的证据优先调试技能。它的出发点是:代码是不可靠的叙述者,它只说明可能发生什么,而不是实际发生了什么;调试应当从实际发生的事实出发。

主要能力

该技能把调试工作分为两个层级:

  • 事实:由工具或人收集的数据,包括缺陷报告、日志、指标、追踪、配置、开关值、版本、部署历史、git 历史、性能剖析、数据包与 DNS 数据。文档、帮助文本、规格说明和现有测试属于“预期行为”的事实。事实只读,不能编辑或争辩;看起来错误的事实应重新收集,或退回给产生它的人。
  • 代码事实:记录代码说了什么及其位置,例如 C3: incidents.ts:480 groups rows with groupByIdKeepAll。代码只说明可能发生什么,因此代码事实可以解释机制,但绝不能作为最强信号。
  • 假设:所有推断出来的内容,包括原因、理论、叙述以及构建的每一个复现。复现一旦显示出所报告的症状,就成为事实来源。假设只有在符合每一个事实时才成立。

每个事实都是一条约束。目标是找到唯一一个能符合所有事实的假设(单一原因,或每个原因都必需的组合)。原则是“让事实丰满,让假设单薄”。

使用方式

技能按四个步骤推进:

Step 0:收集事实,从最便宜的开始。 完整阅读缺陷报告,把其中所有内容转成编号事实:首个坏版本与最后好版本、配置、开关、症状、附带的剖析与日志。如果报告有复现步骤,立即运行并记录信号。列出最后好版本与首个坏版本之间窗口内的所有变更,覆盖所有仓库、目录和团队:提交、部署、配置、开关翻转、依赖升级。所有查询和命令都要自己运行。当没有工具能触达某个事实时,写一个一次性脚本来收集或计数,并把脚本命名为该事实的来源。截图、粘贴的数字或仪表盘读数只是线索,不是事实:要用精确查询和时间窗口从源头重新收集。用户是最后手段:在请用户运行、打开或检查任何东西之前,先自己尝试一次并展示尝试过程。只有在收集完事实之后,才读代码来解释缺陷,并且只读缺陷发生时运行的版本(报告中的首个坏版本),在每个代码事实中注明该提交;HEAD 是另一个程序。

Step 1:选取对照组,找出信号。 变量是出问题的案例,对照组是除可疑差异外与之相等的案例:开关关闭、最后好版本、健康主机、未受影响用户。当不存在好版本时,在同一版本内选取对照组。当正常路径与变量差异过多时,选取“悲伤路径”对照组:同样失败但方式不同且更明显的案例。从两者收集相同的事实,尽可能以数字比较。只出现在变量中而不在对照组中的是信号;两者都出现的是噪声。从变量的多个实例收集同一事实,只有一个实例显示而其他不显示的是该实例的怪癖,不是缺陷。检查对照组是否以同样方式损坏。

Step 2:构建矩阵。 列出可能的假设,然后画出“假设×事实”矩阵:每行一个假设,每列一个事实(信号与噪声),每个单元格填 ✓ 符合、✗ 矛盾或 ? 未知。读列:符合几乎所有行的信号是弱信号(如 p99、错误率、SLO 等聚合指标);符合一行的信号是强信号,优先测试该行。读行:一个 ✗ 就杀死一行;? 是需要收集的事实,不是通过。如果没有一行全是 ✓,按顺序应用:重新检查可疑事实的收集方式;把粗粒度假设拆成部分;把各自解释一个主机或实例的细粒度假设合并为共同原因;合并两个各自解释不同事实且不矛盾的假设;最后才从事实出发提出新假设。如果所有信号都弱,或第 5 条策略找不到东西,就在 LAYERS.md 中下降一层:基础设施缺陷沿栈向下,逻辑缺陷沿请求路径向下,对该层运行 Step 0,在第一个给出强信号的层停止。收集更多事实,而不是更多假设。

Step 3:验证。 用每一个事实(包括噪声)检查获胜行。引用:解释中的每个主张都要注明所依据的事实编号;没有事实的主张要删除,或变成待收集的事实。复现一致性:复现是假设,只有当它显示与真实缺陷相同的最强信号时才成立;信号不同的复现是另一个缺陷,应丢弃。必要性:对于组合行,逐个移除每个原因,每次都必须有某个事实无法解释,否则该原因不是必需的。审查:派一个全新的子代理,带上 REVIEWER.md 的全部八项、事实列表、对照组和矩阵,不要给它你的叙述和你读过的代码,它的任务是打破获胜行。

Step 4:修复。 如果只有一个修复方案符合,就说明它。如果有多个符合,列出每个方案及其权衡和你的推理,在改代码前请用户选择。带有问责性质的决策同样交给用户:回滚、升级给另一个团队、砍掉功能。对照预期行为事实检查修复。在能显示真实信号的接缝处写回归测试;如果没有接缝能显示,就说明这一点。搜索同一错误在其他地方的出现:修复路径的其他调用者,以及按同一模式编写的其他代码。更新所有描述变更行为的文档、帮助文本和测试。移除添加的每一个调试探针。在提交或 PR 中说明原因、最强信号和对照组。

适用场景

  • 生产遥测中出现缺陷或性能回退
  • 用户报告的 bug
  • PR 审查发现的问题

限制与护栏

  • 生产环境对你只读。任何重启、扩缩容、写入、删除或翻转开关的命令,都要先询问用户。在获得批准的重启之前,捕获它销毁的内容:线程栈、打开的连接、IPC 状态、内存剖析。
  • 在本地启动应用之前,先找出它在启动时调用的外部依赖(种子数据、调度器、健康检查、webhook)并先关闭它们。本地栈是复现,Step 3 将其视为假设,绝不是矩阵的事实来源;事实要从缺陷发生的地方收集。
  • 把编号事实列表和矩阵放在一个工作文件中并原地更新。新事实取下一个编号,不重新编号、不丢弃。在添加假设或更改获胜行之前重新阅读该文件。不在文件中的发现等于不存在。
  • 在命令、输出和工件中,用 <REDACTED> 代替每一个秘密。只引用携带信号的行。
  • 报告结尾提示:运行 /debug-retro,把每次介入转化为一条规则。

暂未提供

该技能的收费、价格、平台支持范围、安装命令等具体信息,资料中暂未提供。