84 lines
3.1 KiB
Plaintext
84 lines
3.1 KiB
Plaintext
---
|
||
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`
|