| name | sd-debug |
| description | 当遇到 bug、测试失败、非预期行为、报错信息、接口异常、页面不显示、数据不对时使用。即使用户只说"这里不对""跑不起来""报错了""为什么结果不对""坏了""挂了""出问题了""不工作"也应触发。核心方法论是在提出修复方案前先完成系统化的根因调查，避免盲目猜测修复。 |
系统化调试
你正在帮助开发者定位并修复一个问题。核心原则是：先找到根因，再实施修复。
铁律：修复前必须先完成根因调查。没有例外。
适用场景
- 测试失败，原因不明
- 功能表现与预期不符
- 错误信息指向不明确
- 之前的修复没有解决问题
阶段一：根因调查
目标：收集足够证据定位问题源头，而非猜测
操作：
- 完整阅读错误信息、堆栈跟踪、日志输出
- 复现问题：确认稳定复现路径
- 检查最近变更：
git diff 和 git log 查看是否是新引入的
- 在多组件系统中，隔离问题所在层：
- 是前端还是后端？
- 是业务逻辑还是数据层？
- 是本地代码还是外部依赖？
- 追踪数据流：从错误点向上追溯，找到数据开始偏离预期的位置
根因追踪技术：
- 从错误点开始，沿调用栈逆向追踪
- 在关键节点添加日志或断点，观察实际值
- 找到"最后一个正确的点"和"第一个错误的点"之间的代码
防御式分层验证：
- 入口验证：输入参数是否符合预期
- 业务逻辑验证：中间计算结果是否正确
- 环境验证：配置、依赖版本、环境变量是否正确
- 调试验证：添加临时日志确认执行路径
阶段二：模式分析
目标：通过对比理解问题
操作：
- 找到一个正常运行的类似功能或代码路径
- 逐项对比正常路径和问题路径的差异
- 检查依赖关系：版本、配置、初始化顺序
- 查看相关文档或测试用例，理解预期行为
阶段三：假设验证
目标：用最小化实验验证根因假设
操作：
- 基于阶段一二的证据，形成一个具体假设（不是"可能是 X 或 Y"，而是"根因是 X，因为证据 A、B、C"）
- 设计最小化测试：只改变一个变量来验证假设
- 执行测试并观察结果
- 如果假设被否定，回到阶段一收集更多证据，而非直接猜下一个
阶段四：实现修复
前提：已通过阶段三确认了根因
操作：
- 先写一个能暴露问题的测试用例（修复前应该失败）
- 实施针对根因的最小修复
- 运行测试：新测试通过 + 现有测试不回归
- 清理阶段一添加的临时日志或调试代码
条件等待替代固定延时：
- 如果问题涉及异步或时序，不要用
sleep 或固定等待时间
- 改用条件轮询：每隔短间隔检查条件是否满足，设置超时上限
- 只有在确实基于已知时序约束时，才使用固定延时，并注释说明原因
前端页面调试
条件：当问题涉及前端页面（UI 渲染、交互、样式、网络请求）时，不能仅靠读代码推测，必须在浏览器中验证。
环境检测：
- 如果 chrome-devtools MCP 可用：使用下方工具直接调试
- 如果不可用：引导用户在浏览器中手动操作，并要求用户反馈以下信息：
- 打开浏览器开发者工具 Console 面板，截图或粘贴报错信息
- 切换到 Network 面板，检查是否有失败请求（红色条目），反馈 URL 和状态码
- 按你的指示操作页面，描述实际表现与预期的差异
- 如需要，将开发者工具截图发送给你
使用 chrome-devtools MCP 的操作：
- 用
navigate_page 导航到问题页面
- 用
take_snapshot 获取页面当前状态，确认元素是否正确渲染
- 用
list_console_messages 检查是否有 JS 报错、警告或未捕获异常
- 用
list_network_requests 检查是否有失败的网络请求（4xx/5xx）
- 如果涉及交互问题：
- 用
click、fill、hover 等工具模拟用户操作
- 操作后再次
take_snapshot 和 list_console_messages，观察状态变化
- 对比操作前后的页面快照，定位交互导致的异常
- 如果涉及性能问题：
- 用
performance_start_trace 录制性能追踪
- 分析
performance_analyze_insight 中的关键指标
- 将浏览器中获取到的真实报错信息、网络失败、控制台异常作为根因调查的第一手证据
关键原则：前端问题必须在浏览器中复现和验证，不能只看代码说"应该没问题"。代码层面看起来正确不代表运行时正确。
三次规则
如果已经尝试了 3 次修复仍未解决，必须停止。
此时应该：
- 重新审视问题假设是否正确
- 考虑是否是架构层面的问题，而非局部代码问题
- 向用户说明情况，讨论是否需要更大范围的重构
- 不要尝试第 4 次"微调式"修复
常见陷阱
- 没有复现就开始修："我大概知道哪里错了" — 先复现
- 同时改多个地方：无法确认哪个改动真正修复了问题
- 用
sleep 掩盖时序问题：问题没消失，只是变得不稳定
- 修复了症状而非根因：错误换了个位置出现
- 看到第一个异常就认定是根因：可能只是连锁反应中的一环
必须停止
遇到以下情况时，停下来重新评估：
- 你在说"先快速修一下，之后再查原因" — 现在就查
- 你在说"试试改一下 X 看看行不行" — 这是猜测，不是调查
- 你想跳过测试手动验证 — 写自动化测试
- 你已经尝试了 2 次以上修复，每次都暴露新问题 — 触发三次规则
- 你在说"再试一次就好了" — 如果前几次没有基于新证据，这次也不会好
