185 lines
6.5 KiB
Markdown
185 lines
6.5 KiB
Markdown
---
|
||
name: debugging
|
||
version: 2.0.0
|
||
description: "七步法系统化调试工作流。当用户报告 Bug、错误、异常、截图指出界面问题或功能与预期不符时使用。含信号解析和结构化调试报告。"
|
||
---
|
||
|
||
> ⚠️ 核心执行流程已在 `.cursor/rules/skill-debugging.mdc` 中由 Cursor 自动注入。
|
||
> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
|
||
|
||
# Debugging Workflow
|
||
|
||
## 触发条件
|
||
|
||
用户报告错误、异常、意外行为，或请求排查问题。包含但不限于：
|
||
|
||
| 来源 | 典型表现 | 示例 |
|
||
|---|---|---|
|
||
| 运行时错误 | 控制台报错、崩溃、白屏 | "点击按钮报 500" |
|
||
| 视觉/UI 异常 | 组件显示与预期不符 | "暗色模式下输入框是白色" |
|
||
| 截图指出问题 | 用户提供截图标注异常区域 | 附图 + "这里不对" |
|
||
| 功能失效 | 操作无响应或结果错误 | "筛选没有效果" |
|
||
| 样式回归 | 改动后样式错乱 | "更新后布局乱了" |
|
||
|
||
> ⚠️ **截图 = Bug 报告**：用户提供截图并指出问题，本质是视觉 Bug 报告，必须激活本技能。
|
||
|
||
## 七步法
|
||
|
||
### -1. 截图前置守卫 (Screenshot Guard)
|
||
|
||
收到用户消息时，**先检查输入形式**，再分析文字意图：
|
||
|
||
| 输入形式 | 问题关键词 | 判定 |
|
||
|---------|-----------|------|
|
||
| 包含截图/图片 | 不合理 / 不对 / 有问题 / 调整 / 修复 / 偏了 / 太大 / 太小 / 空白 / 溢出 / 错位 | → 视觉 Bug，激活完整调试流程 |
|
||
| 包含截图/图片 | 新增 / 添加 / 改为 / 参考这个 / 照着做 | → 需求变更，走正常开发流程 |
|
||
|
||
**硬规则**：无论判定结果是哪条路径，都**必须在回复开头输出守卫判定块**：
|
||
|
||
```
|
||
## 截图守卫判定
|
||
- 输入形式：包含截图 ✓
|
||
- 关键词扫描：「XXX」→ 命中 [视觉 Bug / 需求变更] 类
|
||
- 判定：[激活调试流程 / 走正常开发流程]
|
||
```
|
||
|
||
**视觉 Bug 路径规则**：
|
||
- 截图 + 问题描述 = 视觉 Bug，**不得降级为 L1 直接执行**，最低 L2
|
||
- 必须走完信号解析 → 修复 → 回归验证（含 chrome-devtools 截图对比）全流程
|
||
|
||
**需求变更路径规则**：
|
||
- 截图用于"参考设计"或"说明改动目标"，走正常开发流程
|
||
- 复杂度按 001-workflow 标准判定（可为 L1）
|
||
|
||
### 0. 信号解析 (Parse Signals)
|
||
|
||
从用户描述中**主动提取**以下关键信号（缺失的主动追问）：
|
||
|
||
| 信号 | 来源 | 重要性 |
|
||
|---|---|---|
|
||
| 错误消息 / 堆栈追踪 | 控制台、日志、浏览器 DevTools | 🔴 必需 |
|
||
| 复现步骤 | 用户操作序列 | 🔴 必需 |
|
||
| 截图标注的异常区域 | 用户截图 + 文字描述 | 🔴 必需（有截图时） |
|
||
| 影响区域 | 后端服务 / 前端组件 / API / DB | 🟠 重要 |
|
||
| 环境信息 | PHP 版本 / 浏览器 / OS | 🟡 有用 |
|
||
| 上次正常的时间/版本 | Git log / 部署记录 | 🟡 有用 |
|
||
| 偶发 vs 稳定 | 复现概率 | 🟡 有用 |
|
||
|
||
### 0.5 路由到调试策略 (Route to Debug Strategy)
|
||
|
||
根据影响区域选择最高效的调试工具：
|
||
|
||
| 影响区域 | 首选调试方式 | 测试工具 | 关键位置 |
|
||
|---|---|---|---|
|
||
| PHP Service 逻辑 | 断点 + 日志 | PHPUnit | `Case-Database-Backend/test/Unit/` |
|
||
| API 端点 | Postman / curl + 日志 | Hyperf HttpClient | `Case-Database-Backend/test/Feature/` |
|
||
| 数据库查询 | SQL 日志 + `EXPLAIN` | PHPUnit + SQLite | `Case-Database-Backend/test/Unit/` |
|
||
| Vue 组件渲染 | Vue DevTools | Vitest + VTU | `frontend-*/src/**/*.test.ts` |
|
||
| Vue 状态管理 | Pinia DevTools | Vitest | `frontend-*/src/**/*.test.ts` |
|
||
| API 请求/响应 | 浏览器 Network 面板 | Mock + Vitest | `frontend-*/src/**/*.test.ts` |
|
||
| 样式/布局 | Chrome DevTools Elements | 视觉回归 | — |
|
||
| Swoole 协程 | `var_dump` + Hyperf 日志 | PHPUnit | `Case-Database-Backend/test/` |
|
||
| WebSocket | 浏览器 WS 面板 + 服务端日志 | Swoole Testing | `Case-Database-Backend/test/` |
|
||
|
||
### 1. 复现 (Reproduce)
|
||
|
||
- 获取准确的错误信息、堆栈追踪
|
||
- 确认可稳定复现的步骤
|
||
- 确认环境：浏览器/Node 版本、OS
|
||
- **关键**：如果无法稳定复现，记录复现概率和条件
|
||
|
||
### 2. 收集 (Collect)
|
||
|
||
- 读取相关源码文件
|
||
- 检查最近的 git 变更：`git log --oneline -10 -- <affected-path>`
|
||
- 查看相关日志
|
||
- 检查环境变量配置
|
||
- **新增**：查看该区域的已有测试，了解预期行为
|
||
|
||
### 3. 假设 (Hypothesize)
|
||
|
||
列出 2-3 个最可能的原因，按概率排序：
|
||
```
|
||
假设 A (70%): <描述> — 因为 <证据>
|
||
假设 B (20%): <描述> — 因为 <证据>
|
||
假设 C (10%): <描述> — 因为 <证据>
|
||
```
|
||
|
||
每个假设必须指向**具体文件和代码行**。
|
||
|
||
### 4. 验证 (Verify)
|
||
|
||
从最高概率假设开始验证。每次只验证一个假设：
|
||
- 添加 `console.log` / 断点 / Hyperf 日志
|
||
- 写最小复现测试用例（参考 `bug-reproduce` 技能）
|
||
- 检查相关数据状态
|
||
|
||
### 5. 修复 (Fix)
|
||
|
||
- 修复根因，不是症状
|
||
- 修改尽可能小
|
||
- 添加防御性代码防止复发
|
||
|
||
### 6. 回归 (Regress)
|
||
|
||
- 确认原始问题已修复
|
||
- 运行相关测试套件
|
||
- 检查是否引入新问题
|
||
- **新增**：编写回归测试防止复发
|
||
|
||
## 硬停止条件
|
||
|
||
遇到以下情况时**立即停止调试**，告知用户需要额外条件：
|
||
|
||
| 条件 | 原因 | 建议 |
|
||
|---|---|---|
|
||
| 需要真实第三方 API 凭证 | 无法在本地模拟 | 提供测试凭证或 Mock 服务 |
|
||
| 竞态条件/时序依赖 | 不可靠的复现 | 添加日志收集并发数据 |
|
||
| 需要生产数据 | 本地无法重建状态 | 导出脱敏数据子集 |
|
||
| 需要特定基础设施 | 本地无法模拟 | 在测试环境调试 |
|
||
| 超过 3 次假设全部否定 | 信息不足 | 收集更多日志和上下文 |
|
||
|
||
## 调试报告模板
|
||
|
||
```markdown
|
||
## 🔧 调试报告
|
||
|
||
**问题**: [一句话描述]
|
||
**状态**: ✅ 已修复 | ⏳ 进行中 | ❌ 需要更多信息
|
||
|
||
### 信号
|
||
- 错误: [错误消息]
|
||
- 区域: [影响区域]
|
||
- 复现: [步骤]
|
||
|
||
### 根因
|
||
[1-2 句话解释 Bug 产生的机制]
|
||
|
||
### 修复
|
||
| 文件 | 修改 |
|
||
|---|---|
|
||
| `path/to/file` | [修改说明] |
|
||
|
||
### 回归测试
|
||
- `path/to/test` — [测试说明]
|
||
|
||
### 验证
|
||
- [ ] 原始问题已修复
|
||
- [ ] 回归测试通过
|
||
- [ ] 无新问题引入
|
||
```
|
||
|
||
## 常见问题速查
|
||
|
||
详见 `references/common-errors.md`。
|
||
|
||
## 验证
|
||
|
||
1. [ ] 提取了所有关键信号（错误消息、复现步骤、影响区域）
|
||
2. [ ] 选择了正确的调试策略和工具
|
||
3. [ ] 原始问题已修复
|
||
4. [ ] 所有现有测试通过
|
||
5. [ ] 添加了防止复发的回归测试
|
||
6. [ ] 修复范围最小化
|
||
7. [ ] 输出了结构化调试报告
|