@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/software-development/systematic-debugging/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: systematic-debugging
+description: "4阶段根因调试：在修复前先理解 bug。"
+version: 1.1.0
+author: Hermes Agent (adapted from obra/superpowers)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [debugging, troubleshooting, problem-solving, root-cause, investigation]
+    related_skills: [test-driven-development, plan, subagent-driven-development]
+---
+
+# 系统化调试
+
+## 概览
+
+随意的修复不仅浪费时间，还会引入新 bug。仓促的补丁会掩盖底层问题。
+
+**核心原则：** 在尝试任何修复之前，务必找到根本原因。仅治标不治本是失败的。
+
+**违背此流程的字面意义，就是违背调试的精神。**
+
+## 铁律
+
+```
+未进行根因调查前，绝不执行修复
+```
+
+如果你没有完成 Phase 1，就不能提出修复方案。
+
+## 反馈循环规则
+
+反馈循环本身就是调试工作。在阅读代码构建理论之前，创建或确定一个**紧凑的**命令，该命令能在用户的准确症状上亮红灯，并在 bug 修复后亮绿灯。紧凑的循环应当是快速、确定性的、Agent 可运行的，且足够具体以捕获此 bug —— 而不仅仅是“不崩溃”。
+
+当难以实现干净的复现时，要不遗余力地构建该循环。在没有能够亮红灯的循环的情况下进行猜测，正是本技能旨在防止的失败模式。
+
+## 何时使用
+
+用于**任何**技术问题：
+- 测试失败
+- 生产环境中的 bug
+- 意外行为
+- 性能问题
+- 构建失败
+- 集成问题
+
+**尤其在以下情况下使用：**
+- 时间紧迫（紧急情况会诱使人去盲猜）
+- “只需一个快速修复”看起来很明显
+- 你已经尝试了多种修复方法
+- 之前的修复无效
+- 你并未完全理解该问题
+
+**在以下情况下也不要跳过：**
+- 问题看似简单（简单的 bug 也有根本原因）
+- 你很赶时间（仓促只会导致返工）
+- 别人要求立即修复（系统化方法比盲目试错更快）
+
+## 四个阶段
+
+你**必须**在进入下一阶段之前完成当前阶段。
+
+---
+
+## Phase 1: 根因调查
+
+**在尝试任何修复之前：**
+
+### 1. 仔细阅读错误信息
+
+- 不要跳过任何错误或警告
+- 它们通常包含确切的解决方案
+- 完整阅读 stack trace
+- 记录行号、文件路径、错误代码
+
+**行动：** 对相关的源文件使用 `read_file`。使用 `search_files` 在代码库中查找错误字符串。
+
+### 2. 构建紧凑的反馈循环
+
+- 你能用一条命令触发用户的准确症状吗？
+- 该命令是否因此 bug 而失败，并且只有在 bug 修复后才通过？
+- 它足够快，能重复运行吗？
+- 它是确定性的吗？对于不稳定的 bug，你能将复现率提高到足以进行调试的程度吗？
+- 如果不可复现 → 收集更多数据，不要猜测。
+
+**构建循环的方法 —— 大致按以下顺序尝试：**
+
+1. 触达 bug 的交界处的**失败测试**：单元测试、集成测试或端到端测试。
+2. 针对运行中的开发服务器运行的 **HTTP 脚本 / curl**。
+3. 带有 fixture 输入的 **CLI 调用**，对比 stdout/stderr 与预期输出。
+4. 断言 DOM、console 或 network 的 **Headless 浏览器脚本**（Playwright/Puppeteer）。
+5. **重放捕获的 trace**：HAR、request payload、event log、queue message 或 webhook body。
+6. **一次性测试脚手架**，启动系统中最小有用的切片并调用失败的路径。
+7. 当 bug 在广泛的输入空间中表现为间歇性的错误输出时，使用 **Property / fuzz 循环**。
+8. 当 bug 出现在两个已知状态之间时，适用于 `git bisect run` 的 **二分法脚手架**。
+9. 比较旧版本与新版本、两个配置、两个提供商或两个数据集的 **差分循环**。
+10. **人工介入脚本** 仅作为最后手段：将人工操作步骤脚本化并捕获其结果，以保持循环的结构化。
+
+**一旦循环建立，就使其更紧凑：**
+
+- 让它更快：缓存设置、缩小范围、跳过不相关的初始化。
+- 让信号更敏锐：断言准确的特定症状，而非通用的成功状态。
+- 让它更具确定性：固定时间、设定随机数种子、隔离文件系统、冻结网络。
+
+对于非确定性 bug，当前目标是将复现率提高到可调试水平，而不是追求完美。运行触发器 100 次、并行化、增加压力、缩小时间窗口或注入 sleep（延迟）。50% 的不稳定复现是可调试的；1% 的通常不可调试。
+
+**行动：** 使用 `terminal` 工具运行紧凑循环：
+
+```bash
+# 运行特定的失败测试
+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，最近的提交
+- 新的依赖项、配置变更
+
+**行动：**
+
+```bash
+# 最近的提交
+git log --oneline -10
+
+# 未提交的变更
+git diff
+
+# 特定文件中的变更
+git log -p --follow src/problematic_file.py | head -100
+```
+
+### 4. 在多组件系统中收集证据
+
+**当系统有多个组件时（API → service → database, CI → build → deploy）：**
+
+**在提出修复方案之前，添加诊断埋点：**
+
+对于**每个**组件边界：
+- 记录进入该组件的数据
+- 记录流出该组件的数据
+- 验证环境/配置的传播
+- 检查每一层的状态
+
+运行一次以收集显示**在哪里**中断的证据。
+**然后**分析证据以识别出故障的组件。
+**接着**调查该特定组件。
+
+### 5. 追踪数据流
+
+**当错误深藏在 call stack 中时：**
+
+- 错误的值最初是在哪里产生的？
+- 是谁用这个错误的值调用了此函数？
+- 持续向上游追踪，直到找到源头
+- 在源头修复，而不是在症状处
+
+**行动：** 使用 `search_files` 追踪引用：
+
+```python
+# 查找函数被调用的位置
+search_files("function_name(", path="src/", file_glob="*.py")
+
+# 查找变量被赋值的位置
+search_files("variable_name\\s*=", path="src/", file_glob="*.py")
+```
+
+### Phase 1 完成清单
+
+- [ ] 错误信息已被完整阅读和理解
+- [ ] 存在紧凑的循环命令，并且至少已运行过一次
+- [ ] 循环具备亮红灯能力：它断言的是用户准确的特定症状，而不是附近的故障
+- [ ] 循环是确定性的，或者对于不稳定的 bug，其复现率已提高到足以进行调试
+- [ ] 已识别并审查了最近的变更
+- [ ] 已收集证据（日志、状态、数据流）
+- [ ] 问题已隔离到特定的组件/代码
+- [ ] 可以陈述并测试根因假设
+
+**停止：** 在你理解它**为什么**发生之前，不要进入 Phase 2。
+
+---
+
+## Phase 2: 模式分析
+
+**在修复之前找到模式：**
+
+### 0. 最小化复现步骤
+
+一旦循环亮起红灯，就将复现步骤缩减至仍然会亮红灯的最小场景。**每次只删减一个**输入、调用方、配置、数据和步骤，每次删减后重新运行循环。只保留对触发失败起关键作用的因素。
+
+当移除任何剩余元素都会使循环变为通过（绿灯）时，最小化就完成了。最小化的复现缩小了假设空间，并且通常能成为最干净的回归测试。
+
+### 1. 查找正常工作的示例
+
+- 在同一个代码库中找到类似的正常工作的代码
+- 有什么与损坏的部分相似但能正常工作？
+
+**行动：** 使用 `search_files` 查找可比较的模式：
+
+```python
+search_files("similar_pattern", path="src/", file_glob="*.py")
+```
+
+### 2. 与参考进行比较
+
+- 如果正在实现某种模式，请完整阅读参考实现
+- 不要粗略浏览 —— 阅读每一行
+- 在应用之前完全理解该模式
+
+### 3. 识别差异
+
+- 正常工作的部分和损坏的部分之间有什么不同？
+- 列出每一个差异，无论多么微小
+- 不要假设“那无关紧要”
+
+### 4. 理解依赖项
+
+- 这需要哪些其他组件？
+- 有哪些设置、config、environment？
+- 它做出了哪些假设？
+
+---
+
+## Phase 3: 假设与测试
+
+**科学方法：**
+
+### 1. 形成排序的可证伪假设
+
+- 在测试任何单个假设之前，生成 3–5 个合理的假设。
+- 根据可能性和证伪成本对它们进行排序。
+- 陈述每个假设做出的预测：“如果 X 是原因，那么改变或观察 Y 应该会导致 Z 发生。”
+- 丢弃或细化任何不能做出可测试预测的假设。
+
+如果用户在场，请在测试前展示排序列表。他们可能具有能瞬间重新排序的领域知识。如果用户不在（AFK），请按你的排序继续进行。
+
+### 2. 最小化测试
+
+- 用尽可能小的探针测试排名最高的假设。
+- 每次只改变一个变量。
+- 不要同时修复多个问题。
+- 尽可能优先使用 debugger/REPL 检查；一个断点胜过十条日志。
+- 如果你添加了日志，请使用唯一前缀（如 `[DEBUG-a4f2]`）标记每一行临时代码，以便通过一次搜索即可完成清理。
+
+### 3. 在继续之前进行验证
+
+- 有效吗？→ Phase 4
+- 无效？→ 形成新的假设
+- 不要在上面叠加更多的修复
+
+### 4. 当你不知道时
+
+- 说“我不理解 X”
+- 不要假装知道
+- 向用户求助
+- 进行更多研究
+
+---
+
+## Phase 4: 实现
+
+**修复根本原因，而不是症状：**
+
+### 1. 创建失败测试用例
+
+- 尽可能简单的复现
+- 尽可能是自动化测试
+- 在修复之前**必须**拥有
+- 使用 `test-driven-development` 技能
+
+### 2. 实施单一修复
+
+- 解决已识别的根本原因
+- 每次只做一个改动
+- 不要做“顺手为之”的改进
+- 不要包含捆绑的重构
+
+### 3. 验证修复
+
+```bash
+# 运行特定的回归测试
+pytest tests/test_module.py::test_regression -v
+
+# 运行完整测试套件 —— 无回归问题
+pytest tests/ -q
+```
+
+### 4. 如果修复无效 —— 三次法则
+
+- **停止。**
+- 数一数：你已经尝试了多少次修复？
+- 如果 < 3 次：返回 Phase 1，利用新信息重新分析
+- **如果 ≥ 3 次：停止并质疑架构（见下方第 5 步）**
+- 在未进行架构讨论之前，不要尝试第 4 次修复
+
+### 5. 如果 3 次以上的修复均失败：质疑架构
+
+**表明存在架构问题的模式：**
+- 每次修复都会在不同位置暴露出新的共享状态/耦合
+- 修复需要“大规模重构”才能实施
+- 每次修复都会在其他地方引发新症状
+
+**停下来质疑根本基础：**
+- 这个模式从根本上合理吗？
+- 我们是否只是“出于纯粹的惯性才硬撑下去”？
+- 我们应该重构架构还是继续修补症状？
+
+**在尝试更多修复之前，与用户进行讨论。**
+
+这不是失败的假设 —— 而是架构错误。
+
+---
+
+## 危险信号 —— 停止并遵循流程
+
+如果你发现自己在想：
+- “先做个快速修复，以后再调查”
+- “试着改一下 X 看看行不行”
+- “添加多个改动，然后运行测试”
+- “跳过测试吧，我会手动验证的”
+- “可能是因为 X，让我修一下”
+- “我还没完全理解，但这可能管用”
+- “参考模式说用 X，但我会以不同方式调整它”
+- “主要问题是这些：[在未进行调查前就列出修复方案]”
+- 在追踪数据流之前提出解决方案
+- **“再试一次修复”（当已经尝试了 2 次以上时）**
+- **每次修复都会在不同地方暴露出一个新问题**
+
+**以上所有都意味着：停止。返回 Phase 1。**
+
+**如果 3 次以上的修复失败了：** 质疑架构（Phase 4 第 5 步）。
+
+## 常见的自我辩解
+
+| 借口 | 现实 |
+|--------|---------|
+| “问题很简单，不需要走流程” | 简单的问题也有根本原因。对于简单的 bug，流程执行起来很快。 |
+| “紧急情况，没时间走流程” | 系统化调试比瞎猜和盲目试错**更快**。 |
+| “先试一下这个，然后再调查” | 第一次修复会确立模式。从一开始就要做对。 |
+| “我会在确认修复有效后写测试” | 未经测试的修复无法持久。先写测试能证明它。 |
+| “一次进行多项修复能节省时间” | 无法隔离出到底是哪一项起了作用。还会导致新 bug。 |
+| “参考实现太长了，我将直接套用模式” | 一知半解必然会引入 bug。请完整阅读它。 |
+| “我看到问题了，让我修复它” | 看到症状 ≠ 理解根本原因。 |
+| “再试一次修复”（在失败 2 次以上之后） | 失败 3 次以上 = 架构问题。质疑该模式，不要再盲目修复了。 |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|-------|---------------|------------------|
+| **1. 根因调查** | 阅读错误、复现问题、检查变更、收集证据、追踪数据流 | 理解是**什么**以及**为什么** |
+| **2. 模式分析** | 寻找正常工作的示例、进行比较、识别差异 | 知道哪里不同 |
+| **3. 假设测试** | 形成理论、最小化测试、每次只测试一个变量 | 确认假设或形成新假设 |
+| **4. 代码实现** | 创建回归测试、修复根本原因、验证 | Bug 已解决，所有测试通过 |
+
+## Hermes Agent 集成
+
+### 调查工具
+
+在 Phase 1 期间使用这些 Hermes 工具：
+
+- **`search_files`** —— 查找错误字符串、追踪函数调用、定位模式
+- **`read_file`** —— 读取带有行号的源代码以进行精确分析
+- **`terminal`** —— 运行测试、检查 git 历史、复现 bug
+- **`web_search`/`web_extract`** —— 研究错误信息、查阅库文档
+
+### 配合 delegate_task
+
+对于复杂的多组件调试，分派调查子 Agent：
+
+```python
+delegate_task(
+    goal="调查为什么 [特定的测试/行为] 会失败",
+    context="""
+    遵循 systematic-debugging 技能：
+    1. 仔细阅读错误信息
+    2. 复现该问题
+    3. 追踪数据流以找到根本原因
+    4. 报告发现 —— 暂不要修复
+
+    Error: [粘贴完整的错误信息]
+    File: [失败代码的路径]
+    Test command: [确切的命令]
+    """,
+    toolsets=['terminal', 'file']
+)
+```
+
+### 配合 test-driven-development
+
+在修复 bug 时：
+1. 编写一个能复现该 bug 的测试（RED）
+2. 系统化调试以找到根本原因
+3. 修复根本原因（GREEN）
+4. 该测试证明了修复的有效性并防止回归
+
+## 实际影响
+
+来自调试会话的数据：
+- 系统化方法：15-30 分钟即可修复
+- 随机修复方法：盲目折腾 2-3 小时
+- 一次性修复成功率：95% vs 40%
+- 引入的新 bug：几乎为零 vs 经常发生
+
+**不走捷径。不靠猜测。系统化调试永远是赢家。**