系统性调试

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，你能将复现率提高到足够高以进行调试吗？
• 如果不可复现 → 收集更多数据，不要猜测。

构建循环的方法——大致按此顺序尝试：

1. 失败测试在触及 bug 的接缝处：单元测试、集成测试或端到端测试。
2. HTTP 脚本/curl 针对运行中的开发服务器。
3. CLI 调用带有固定输入，将 stdout/stderr 与预期输出进行 diff。
4. 无头浏览器脚本（Playwright/Puppeteer）对 DOM、控制台或网络进行断言。
5. 重放捕获的跟踪：HAR、请求负载、事件日志、队列消息或 webhook 主体。
6. 一次性 harness启动系统的最小有用切片并调用失败路径。
7. 属性/模糊循环当 bug 在广阔输入空间上间歇性错误输出时。
8. 二分 harness适用于 git bisect run，当 bug 出现在两个已知状态之间时。
9. 差分循环比较旧版本与新版本、两个配置、两个提供者或两个数据集。
10. 人在回路脚本仅作为最后手段：脚本化人的步骤并捕获其结果，以便循环保持结构化。

循环存在后收紧它：

• 让它更快：缓存设置、缩小范围、跳过无关初始化。
• 让信号更清晰：断言确切症状，而不是通用成功。
• 让它更确定性：固定时间、种子随机性、隔离文件系统、冻结网络。

对于非确定性 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 历史、复现 bug
• web_fetch——研究错误消息和库文档

与 task 一起使用

对于复杂的多组件调试，调度调查子代理：

task: 调查为什么 [特定测试/行为] 失败

上下文：
遵循 systematic-debugging 技能：
1. 仔细阅读错误消息
2. 复现问题
3. 追踪数据流以找到根因
4. 报告发现——还不要修复

错误：[粘贴完整错误]
文件：[失败代码的路径]
测试命令：[确切命令]

与 test-driven-development 一起使用

修复 bug 时：

1. 编写复现 bug 的测试（红色）
2. 系统性地调试以找到根因
3. 修复根因（绿色）
4. 测试证明修复并防止回归

现实影响

来自调试会话：

• 系统性方法：15-30 分钟修复
• 随机修复方法：2-3 小时的折腾
• 首次修复率：95% vs 40%
• 引入的新 bug：接近零 vs 常见

没有捷径。没有猜测。系统性总是赢。