---
description: >
  系统化调试技能。当用户报告 bug、错误、异常、崩溃，
  提供截图指出界面问题，或描述功能与预期不符时激活。
alwaysApply: true
---

# Debugging — 七步法

> 本文件是精简执行摘要。完整流程、模板和深度参考见：
> Read `.cursor/skills/debugging/SKILL.md`

## -1. 截图前置守卫（Scan 阶段硬检查）

收到用户消息时，**先检查输入形式**，再分析文字意图：

| 输入形式 | 问题关键词 | 判定 |
|---------|-----------|------|
| 包含截图/图片 | 不合理 / 不对 / 有问题 / 调整 / 修复 / 偏了 / 太大 / 太小 / 空白 / 溢出 / 错位 | → 视觉 Bug，激活完整调试流程 |
| 包含截图/图片 | 新增 / 添加 / 改为 / 参考这个 / 照着做 | → 需求变更，走正常开发流程 |

**硬规则**：无论判定结果是哪条路径，都**必须在回复开头输出守卫判定块**：

```
## 截图守卫判定
- 输入形式：包含截图 ✓
- 关键词扫描：「XXX」→ 命中 [视觉 Bug / 需求变更] 类
- 判定：[激活调试流程 / 走正常开发流程]
```

**视觉 Bug 路径规则**：
- 截图 + 问题描述 = 视觉 Bug，**不得降级为 L1 直接执行**，最低 L2
- 必须走完信号解析 → 修复 → 回归验证（含 chrome-devtools 截图对比）全流程

**需求变更路径规则**：
- 截图用于"参考设计"或"说明改动目标"，走正常开发流程
- 复杂度按 001-workflow 标准判定（可为 L1）

## 0. 信号解析

从用户描述中提取（缺失则追问）：

| 信号 | 重要性 |
|------|--------|
| 错误消息 / 堆栈追踪 | 必需 |
| 复现步骤 | 必需 |
| 截图标注的异常区域 | 必需（有截图时） |
| 影响区域（前端/后端/API/DB） | 重要 |
| 环境信息 / 上次正常版本 | 有用 |

## 0.5 调试策略路由

| 影响区域 | 首选方式 | 测试工具 |
|----------|---------|---------|
| PHP Service | 断点 + 日志 | PHPUnit |
| API 端点 | curl + 日志 | Hyperf HttpClient |
| 数据库查询 | SQL 日志 + EXPLAIN | PHPUnit + SQLite |
| Vue 组件渲染 | Vue DevTools | Vitest + VTU |
| 样式/布局 | Chrome DevTools | 视觉回归 |

## 1-6. 核心流程

1. **复现** — 确认稳定复现步骤，记录复现概率和条件
2. **收集** — 读取源码、检查 git log、查看日志和已有测试
3. **假设** — 列出 2-3 个最可能原因，按概率排序，指向具体文件和行
4. **验证** — 从最高概率假设开始，每次只验证一个
5. **修复** — 修复根因，修改尽可能小，添加防御性代码
6. **回归** — 确认修复、运行测试套件、编写回归测试防复发

## 硬停止条件

需要真实第三方凭证、竞态条件不可靠复现、需要生产数据、超过 3 次假设全部否定 → 立即停止，告知用户需要额外条件。

## 验证

- [ ] 提取了所有关键信号
- [ ] 选择了正确的调试策略
- [ ] 原始问题已修复
- [ ] 所有现有测试通过
- [ ] 添加了回归测试
- [ ] 修复范围最小化

深度参考：`.cursor/skills/debugging/references/common-errors.md`