系统性调试
Harness-agent 工具
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
概述
随机修复浪费时间并制造新 bug。快速补丁掩盖了潜在问题。
核心原则: 始终先找到根因,再尝试修复。症状修复就是失败。
违反此流程的字面意思就是违反调试精神。
铁律
没有根因调查就禁止修复
如果你还没有完成阶段1,就不能提出修复方案。
反馈循环规则
反馈循环就是调试工作。在阅读代码建立理论之前,先创建或确定一个紧密的命令,它能在用户的确切症状上变红,并在 bug 修复后变绿。紧密循环是快速的、确定性的、可由代理运行的,并且足够具体以捕获此 bug——而不仅仅是"不崩溃"。
当干净的复现很困难时,投入不成比例的努力来构建循环。在没有红色能力的循环的情况下猜测,正是此技能旨在防止的失败模式。
何时使用
用于任何技术问题:
- 测试失败
- 生产环境 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
特别要使用当:
- 时间紧迫时(紧急情况让人想猜测)
- "就一个快速修复"看起来很明显
- 你已经尝试了多个修复
- 之前的修复没有奏效
- 你不完全理解问题
不要跳过当:
- 问题看起来简单(简单 bug 也有根因)
- 你很匆忙(仓促保证返工)
- 有人希望它立即修复(系统性的比折腾更快)
四个阶段
你必须在继续下一个之前完成每个阶段。
阶段1:根因调查
在尝试任何修复之前:
1. 仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码
行动: 使用 read_file 读取相关源文件。使用 glob 在代码库中查找错误字符串。
2. 构建紧密反馈循环
- 你能用一个命令触发用户的确切症状吗?
- 命令对这个 bug 失败,并且只在 bug 修复后通过吗?
- 它足够快可以重复运行吗?
- 它是确定性的吗?对于不稳定的 bug,你能将复现率提高到足够高以进行调试吗?
- 如果不可复现 → 收集更多数据,不要猜测。
构建循环的方法——大致按此顺序尝试:
- 失败测试在触及 bug 的接缝处:单元测试、集成测试或端到端测试。
- HTTP 脚本/curl 针对运行中的开发服务器。
- CLI 调用带有固定输入,将 stdout/stderr 与预期输出进行 diff。
- 无头浏览器脚本(Playwright/Puppeteer)对 DOM、控制台或网络进行断言。
- 重放捕获的跟踪:HAR、请求负载、事件日志、队列消息或 webhook 主体。
- 一次性 harness启动系统的最小有用切片并调用失败路径。
- 属性/模糊循环当 bug 在广阔输入空间上间歇性错误输出时。
- 二分 harness适用于
git bisect run,当 bug 出现在两个已知状态之间时。 - 差分循环比较旧版本与新版本、两个配置、两个提供者或两个数据集。
- 人在回路脚本仅作为最后手段:脚本化人的步骤并捕获其结果,以便循环保持结构化。
循环存在后收紧它:
- 让它更快:缓存设置、缩小范围、跳过无关初始化。
- 让信号更清晰:断言确切症状,而不是通用成功。
- 让它更确定性:固定时间、种子随机性、隔离文件系统、冻结网络。
对于非确定性 bug,直接目标是更高的复现率,而不是完美。运行触发器 100 次、并行化、增加压力、缩小时间窗口或注入睡眠。50% 的 flake 是可调试的;1% 的 flake 通常不是。
行动: 使用 execute 工具运行紧密循环:
# 运行特定的失败测试
pytest tests/test_module.py::test_name -v
# 或运行脚本化复现
python scripts/repro_bug.py
# 或运行高重复不稳定复现
for i in {1..100}; do pytest tests/test_flake.py::test_name -q || break; done
3. 检查最近更改
- 什么更改可能导致此问题?
- Git diff、最近提交
- 新依赖项、配置更改
行动:
# 最近提交
git log --oneline -10
# 未提交的更改
git diff
# 特定文件中的更改
git log -p --follow src/problematic_file.py | head -100
4. 在多组件系统中收集证据
当系统有多个组件时(API → 服务 → 数据库,CI → 构建 → 部署):
在提出修复之前,添加诊断工具:
对于每个组件边界:
- 记录什么数据进入组件
- 记录什么数据离开组件
- 验证环境/配置传播
- 检查每层的状态
运行一次以收集显示其在何处中断的证据。 然后分析证据以识别失败的组件。 然后调查该特定组件。
5. 追踪数据流
当错误在调用栈深处时:
- 坏值起源于哪里?
- 谁用坏值调用了此函数?
- 继续向上追踪直到找到源头
- 在源头修复,而不是在症状处修复
行动: 使用 glob 追踪引用:
# 查找函数被调用的位置
grep(pattern="function_name\\(", path="src/")
# 查找变量被设置的位置
grep(pattern="variable_name\\s*=", path="src/")
阶段1 完成检查清单
- 错误消息已完整阅读和理解
- 存在紧密循环命令并已运行至少一次
- 循环能够变红:它断言用户的确切症状,而不是附近失败
- 循环是确定性的,或者不稳定 bug 有足够高的复现率来调试
- 已识别并审查最近更改
- 已收集证据(日志、状态、数据流)
- 问题隔离到特定组件/代码
- 根因假设可以陈述和测试
停止: 在你理解为什么发生之前,不要进入阶段2。
阶段2:模式分析
在修复之前找到模式:
0. 最小化复现
一旦循环变红,将复现缩小到仍然变红的最小场景。逐个削减输入、调用者、配置、数据和步骤,**每次削减后重新运行循环。只保留对失败有负载的内容。
当移除任何剩余元素都会使循环变绿时完成。最小复现缩小了假设空间,并且通常成为最干净的回归测试。
1. 找到工作示例
- 在同一代码库中找到类似的工作代码
- 什么工作是类似于损坏的东西?
行动: 使用 glob 找到可比较的模式:
grep(pattern="similar_pattern", path="src/")
2. 与参考对比
- 如果实施模式,请完整阅读参考实现
- 不要略读——阅读每一行
- 在应用之前完全理解模式
3. 识别差异
- 工作的和损坏的之间有什么不同?
- 列出每一个差异,无论多小
- 不要假设"那不可能重要"
4. 理解依赖
- 这需要什么其他组件?
- 什么设置、配置、环境?
- 它做了什么假设?
阶段3:假设和测试
科学方法:
1. 形成排名的可证伪假设
- 在测试任何一个之前,生成 3-5 个合理的假设。
- 按可能性和证伪成本对它们排名。
- 陈述每个假设做出的预测:"如果 X 是原因,那么改变或观察 Y 应该使 Z 发生。"
- 丢弃或 sharpen 任何不能做出可测试预测的假设。
如果用户在场,在测试之前显示排名列表。他们可能拥有可以立即重新排名的领域知识。如果用户 AFK,继续你的排名。
2. 最小化测试
- 用最小可能的探测测试排名最高的假设。
- 一次更改一个变量。
- 不要一次修复多个东西。
- 优先使用调试器/REPL 检查(当可用时);一个断点胜过十个日志。
- 如果添加日志,用唯一前缀(如
[DEBUG-a4f2])标记每一行临时行,以便清理是单次搜索。
3. 继续前验证
- 有效吗?→ 阶段4
- 无效?→ 形成新的假设
- 不要在顶部添加更多修复
4. 当你不知道时
- 说"我不理解 X"
- 不要假装知道
- 向用户寻求帮助
- 更多研究
阶段4:实施
修复根因,而不是症状:
1. 创建失败测试用例
- 尽可能简单的复现
- 如果可能,自动化测试
- 修复之前必须有
- 使用
test-driven-development技能
2. 实施单一修复
- 解决已识别的根因
- 一次一个更改
- 没有"趁我在场"的改进
- 没有捆绑的重构
3. 验证修复
# 运行特定的回归测试
pytest tests/test_module.py::test_regression -v
# 运行完整套件——无回归
pytest tests/ -q
4. 如果修复不起作用——三的法则
- 停止。
- 计数:你尝试了多少次修复?
- 如果 < 3:返回阶段1,用新信息重新分析
- 如果 ≥ 3:停止并质疑架构(下面的步骤5)
- 不要在没有架构讨论的情况下尝试修复 #4
5. 如果 3+ 次修复失败:质疑架构
表明架构问题的模式:
- 每次修复在不同地方揭示新的共享状态/耦合
- 修复需要"大规模重构"来实施
- 每次修复在其他地方制造新症状
停止并质疑基本面:
- 这个模式从根本上合理吗?
- 我们是否"仅靠惯性坚持它"?
- 我们应该重构架构而不是继续修复症状?
在尝试更多修复之前与用户讨论。
这不是失败的假设——这是错误的架构。
危险信号——停止并遵循流程
如果你发现自己想:
- "现在快速修复,稍后调查"
- "只是试试改变 X,看看是否有效"
- "添加多个更改,运行测试"
- "跳过测试,我会手动验证"
- "可能就是 X,让我修复它"
- "我不完全理解,但这可能有效"
- "模式说 X,但我会不同地调整它"
- "这是主要问题:[列出修复而没有调查]"
- 在追踪数据流之前提出解决方案
- "再试一次修复"(当已经尝试 2+ 次时)
- 每次修复在不同地方揭示新问题
所有这些意味着:停止。返回阶段1。
如果 3+ 次修复失败: 质疑架构(阶段4 步骤5)。
常见合理化
| 借口 | 现实 |
|---|---|
| "问题很简单,不需要流程" | 简单问题也有根因。流程对于简单 bug 很快。 |
| "紧急情况,没有时间走流程" | 系统性调试比猜测-检查折腾更快。 |
| "先试试这个,然后调查" | 第一次修复设定了模式。从一开始就要做对。 |
| "我会确认修复有效后写测试" | 未经测试的修复不会持久。测试首先证明它。 |
| "一次多个修复节省时间" | 无法隔离什么有效。导致新 bug。 |
| "参考太长,我会调整模式" | 部分理解保证 bug。完整阅读它。 |
| "我看到了问题,让我修复它" | 看到症状 ≠ 理解根因。 |
| "再试一次修复"(2+ 失败后) | 3+ 失败 = 架构问题。质疑模式,不要再修复。 |
快速参考
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查更改、收集证据、追踪数据流 | 理解什么和为什么 |
| 2. 模式 | 找到工作示例、比较、识别差异 | 知道有什么不同 |
| 3. 假设 | 形成理论、最小化测试、一次一个变量 | 确认或新假设 |
| 4. 实施 | 创建回归测试、修复根因、验证 | Bug 解决,所有测试通过 |
Harness-agent 集成
调查工具
在阶段1期间使用这些工具:
grep——在源中查找错误字符串和追踪引用glob——按名称或模式定位文件read_file——带行号读取源以进行精确分析execute——运行测试、检查 git 历史、复现 bugweb_fetch——研究错误消息和库文档
与 task 一起使用
对于复杂的多组件调试,调度调查子代理:
task: 调查为什么 [特定测试/行为] 失败
上下文:
遵循 systematic-debugging 技能:
1. 仔细阅读错误消息
2. 复现问题
3. 追踪数据流以找到根因
4. 报告发现——还不要修复
错误:[粘贴完整错误]
文件:[失败代码的路径]
测试命令:[确切命令]
与 test-driven-development 一起使用
修复 bug 时:
- 编写复现 bug 的测试(红色)
- 系统性地调试以找到根因
- 修复根因(绿色)
- 测试证明修复并防止回归
现实影响
来自调试会话:
- 系统性方法:15-30 分钟修复
- 随机修复方法:2-3 小时的折腾
- 首次修复率:95% vs 40%
- 引入的新 bug:接近零 vs 常见
没有捷径。没有猜测。系统性总是赢。