sd-debug

name	sd-debug
description	当遇到 bug、测试失败、非预期行为、报错信息、接口异常、页面不显示、数据不对时使用。即使用户只说"这里不对""跑不起来""报错了""为什么结果不对""坏了""挂了""出问题了""不工作"也应触发。核心方法论是在提出修复方案前先完成系统化的根因调查，避免盲目猜测修复。

系统化调试

你正在帮助开发者定位并修复一个问题。核心原则是：先找到根因，再实施修复。

铁律：修复前必须先完成根因调查。没有例外。

适用场景

• 测试失败，原因不明
• 功能表现与预期不符
• 错误信息指向不明确
• 之前的修复没有解决问题

阶段一：根因调查

目标：收集足够证据定位问题源头，而非猜测

操作：

1. 完整阅读错误信息、堆栈跟踪、日志输出
2. 复现问题：确认稳定复现路径
3. 检查最近变更：git diff 和 git log 查看是否是新引入的
4. 在多组件系统中，隔离问题所在层：
   • 是前端还是后端？
   • 是业务逻辑还是数据层？
   • 是本地代码还是外部依赖？
5. 追踪数据流：从错误点向上追溯，找到数据开始偏离预期的位置

根因追踪技术：

• 从错误点开始，沿调用栈逆向追踪
• 在关键节点添加日志或断点，观察实际值
• 找到"最后一个正确的点"和"第一个错误的点"之间的代码

防御式分层验证：

• 入口验证：输入参数是否符合预期
• 业务逻辑验证：中间计算结果是否正确
• 环境验证：配置、依赖版本、环境变量是否正确
• 调试验证：添加临时日志确认执行路径

阶段二：模式分析

目标：通过对比理解问题

操作：

1. 找到一个正常运行的类似功能或代码路径
2. 逐项对比正常路径和问题路径的差异
3. 检查依赖关系：版本、配置、初始化顺序
4. 查看相关文档或测试用例，理解预期行为

阶段三：假设验证

目标：用最小化实验验证根因假设

操作：

1. 基于阶段一二的证据，形成一个具体假设（不是"可能是 X 或 Y"，而是"根因是 X，因为证据 A、B、C"）
2. 设计最小化测试：只改变一个变量来验证假设
3. 执行测试并观察结果
4. 如果假设被否定，回到阶段一收集更多证据，而非直接猜下一个

阶段四：实现修复

前提：已通过阶段三确认了根因

操作：

1. 先写一个能暴露问题的测试用例（修复前应该失败）
2. 实施针对根因的最小修复
3. 运行测试：新测试通过 + 现有测试不回归
4. 清理阶段一添加的临时日志或调试代码

条件等待替代固定延时：

• 如果问题涉及异步或时序，不要用 sleep 或固定等待时间
• 改用条件轮询：每隔短间隔检查条件是否满足，设置超时上限
• 只有在确实基于已知时序约束时，才使用固定延时，并注释说明原因

前端页面调试

条件：当问题涉及前端页面（UI 渲染、交互、样式、网络请求）时，不能仅靠读代码推测，必须在浏览器中验证。

环境检测：

• 如果 chrome-devtools MCP 可用：使用下方工具直接调试
• 如果不可用：引导用户在浏览器中手动操作，并要求用户反馈以下信息：
  1. 打开浏览器开发者工具 Console 面板，截图或粘贴报错信息
  2. 切换到 Network 面板，检查是否有失败请求（红色条目），反馈 URL 和状态码
  3. 按你的指示操作页面，描述实际表现与预期的差异
  4. 如需要，将开发者工具截图发送给你

使用 chrome-devtools MCP 的操作：

1. 用 navigate_page 导航到问题页面
2. 用 take_snapshot 获取页面当前状态，确认元素是否正确渲染
3. 用 list_console_messages 检查是否有 JS 报错、警告或未捕获异常
4. 用 list_network_requests 检查是否有失败的网络请求（4xx/5xx）
5. 如果涉及交互问题：
   • 用 click、fill、hover 等工具模拟用户操作
   • 操作后再次 take_snapshot 和 list_console_messages，观察状态变化
   • 对比操作前后的页面快照，定位交互导致的异常
6. 如果涉及性能问题：
   • 用 performance_start_trace 录制性能追踪
   • 分析 performance_analyze_insight 中的关键指标
7. 将浏览器中获取到的真实报错信息、网络失败、控制台异常作为根因调查的第一手证据

关键原则：前端问题必须在浏览器中复现和验证，不能只看代码说"应该没问题"。代码层面看起来正确不代表运行时正确。

三次规则

如果已经尝试了 3 次修复仍未解决，必须停止。

此时应该：

1. 重新审视问题假设是否正确
2. 考虑是否是架构层面的问题，而非局部代码问题
3. 向用户说明情况，讨论是否需要更大范围的重构
4. 不要尝试第 4 次"微调式"修复

常见陷阱

• 没有复现就开始修："我大概知道哪里错了" — 先复现
• 同时改多个地方：无法确认哪个改动真正修复了问题
• 用 sleep 掩盖时序问题：问题没消失，只是变得不稳定
• 修复了症状而非根因：错误换了个位置出现
• 看到第一个异常就认定是根因：可能只是连锁反应中的一环

必须停止

遇到以下情况时，停下来重新评估：

• 你在说"先快速修一下，之后再查原因" — 现在就查
• 你在说"试试改一下 X 看看行不行" — 这是猜测，不是调查
• 你想跳过测试手动验证 — 写自动化测试
• 你已经尝试了 2 次以上修复，每次都暴露新问题 — 触发三次规则
• 你在说"再试一次就好了" — 如果前几次没有基于新证据，这次也不会好