# skill

**Repository Path**: ai-agents/skill

## Basic Information

- **Project Name**: skill
- **Description**: 自己开发项目中的心血精华总结，一个md就是一个skill，这是多个skill不是一个
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 41
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
name: debug-skill
description: 用于代码问题修复、bug排查和报错分析，代码优化。当遇到报错、异常、功能不正常、需要排查问题前使用此技能。
---

# 调试技能 (Debug Skill)

## 目标

在处理代码报错、异常、功能不正常、接口联调失败、数据库问题时，进行系统化排查，准确定位根因，给出最小且可靠的修复方案，并完成影响评估与验证确认。

---

## 核心原则

1. **优先定位，再做修复**  
   在未确认根因前，不直接给出最终修改结论，不基于猜测盲改代码。

2. **信息不足先澄清**  
   如果缺少报错信息、日志、调用代码、接口响应、表结构、数据样例、配置内容等关键上下文，不要猜测根因，先明确列出需要补充的信息。

3. **优先全链路排查**  
   优先从前端(如果有) -> API -> Controller -> Service -> Mapper/Repository -> 数据库 -> 配置/中间件/外部依赖 的链路进行排查。  
   若问题已明确定位于单一层，可聚焦该层，但必须评估上下游影响。

4. **区分表象与根因**  
   不要只修复报错触发点，要继续追踪导致异常的源头。  
   例如：前端报错未必是前端问题，SQL异常未必只是SQL写错，接口参数为空未必是前端没传。

5. **最小充分修复**  
   修复应尽量小而准确，优先解决根因，避免为了修一个问题引入大范围无关改动。

6. **代码整洁**  
   修复完成后，评估并清理确认无用的旧字段、旧方法、废弃逻辑和冗余代码，但不要将大规模重构与当前问题修复混在一起。

7. **影响评估**  
   考虑修复是否影响已有功能、接口兼容性、数据库数据、枚举值、状态流转、权限逻辑、缓存逻辑、事务行为等。

8. **文档与脚本同步**  
   检查是否需要同步修改接口文档、注释、README、部署说明、数据库脚本、初始化脚本、迁移脚本、测试脚本等。

9. **验证闭环**  
   修复后必须验证：原问题已解决、关联功能未受影响、日志中无新增异常、边界场景可接受。

---

## 调试流程

### Step 0: 明确问题现象

```
问题现象清单：
- [ ] 预期结果是什么
- [ ] 实际结果是什么
- [ ] 是否有报错信息/异常堆栈
- [ ] 复现步骤是什么
- [ ] 是否稳定复现（必现/偶现）
- [ ] 最近是否做过代码、配置、数据库、依赖、环境变更

```
执行要求：

1. 先用一句话概括问题现象。
2. 明确“预期行为”和“实际行为”的差异。
3. 如果问题不可稳定复现，优先识别触发条件、环境差异和相关时间点。


### Step 1: 问题定位

```
排查清单：
- [ ] 前端代码（组件、事件、API调用、状态管理、路由、权限、渲染逻辑）
- [ ] 网络请求（请求参数、请求头、响应体、状态码、超时、跨域）
- [ ] 后端代码（Controller、DTO、参数绑定、Service、Mapper/Repository、枚举、异常处理）
- [ ] 配置项（环境变量、YAML/Properties、开关配置、第三方配置）
- [ ] 数据库设计（表结构、字段定义、默认值、约束、索引）
- [ ] 数据库数据（实际数据、脏数据、空值、历史数据兼容性）
- [ ] 中间件/外部依赖（缓存、消息队列、对象存储、第三方接口）
- [ ] 日志与监控（应用日志、SQL日志、网关日志、浏览器控制台）

```

**执行方式：**
1. 从报错信息、异常堆栈、日志、异常现象入手，定位到具体模块、文件、方法、代码行。
2. 追踪调用链路：
3. 前端 -> API -> Controller -> Service -> Mapper/Repository -> 数据库 / 外部依赖
4. 检查每个环节的数据流转是否正确，包括：
    - 参数名是否一致
    - 字段类型是否匹配
    - 枚举值是否一致
    - 空值是否处理
    - 状态是否正确流转
    - 返回值是否符合调用方预期
4. 明确问题处于调用链的哪一环。
如果暂时无法确认，需要说明还缺少哪一环的信息。

### Step 2: 根因分析

| 层级 | 检查要点 |
|------|----------|
| 前端 | 请求参数、字段命名、响应处理、状态更新、表单双绑、类型匹配、条件渲染、异步时序 |
| API/网关 | 路由是否正确、参数是否透传、鉴权是否拦截、跨域/超时/限流是否影响 |
| 后端 | 参数绑定、DTO/VO映射、业务逻辑、空值处理、异常处理、事务管理、并发问题 |
| 持久层 | SQL条件、字段映射、动态SQL、返回结果、批量操作、逻辑删除、多租户条件 |
| 数据库 | 字段类型、默认值、约束、索引、脏数据、历史兼容数据、大小写/编码/时区问题 |
| 配置/环境 | 环境变量、配置文件、服务地址、端口、版本差异、依赖冲突 |
| 外部依赖 | 第三方接口返回变化、缓存未更新、消息积压、网络不稳定、鉴权失效 |

分析要求：

1. 说明“直接报错点”与“真正根因”是否一致。
2. 如果有多个可能原因，按概率排序，不要混为一个结论。
3. 如果问题与数据相关，需要区分：
    - 是代码逻辑错误
    - 还是数据不符合预期
    - 还是历史数据与新逻辑不兼容
4. 如果问题与环境相关，需要区分：
    - 代码问题
    - 配置问题
    - 发布问题
    - 环境差异问题

### Step 3: 修复方案设计

修复前检查：

```
修复清单：
- [ ] 确认根因已基本明确
- [ ] 修复方案不会引入明显新问题
- [ ] 优先采用最小充分修复
- [ ] 检查是否影响其他功能
- [ ] 检查是否需要兼容历史数据/旧接口
- [ ] 检查是否需要补充参数校验/异常处理/默认值
- [ ] 检查是否需要涉及的单元测试文件也需要同步修复
- [ ] 检查是否需要更新文档
- [ ] 检查是否需要更新脚本（如 init.sql、migration.sql、测试数据脚本）
- [ ] 评估是否需要清理旧的无用代码/字段/方法

```

修复要求：

1. 优先修复根因，不只处理表层报错。
2. 优先做局部、可控、可验证的改动。
3. 如果需要兼容旧逻辑，明确说明兼容策略。
4. 是数据问题，明确区分：
    - 代码修复
    - 数据修复
    - 脚本修复
    - 人工清洗数据
5. 如果问题由多个因素共同导致，需要分别给出修复项。

### Step 4: 修复实施

实施时应注意：

1. 修改核心问题代码。
2. 补充必要的参数校验、空值处理、异常提示、边界条件处理。
3. 如涉及数据库：
    - 检查表结构是否需要调整
    - 检查历史数据是否需要修复
    - 检查脚本是否需要同步
4. 如涉及前端：
    - 检查请求参数、响应字段、页面状态、交互提示是否同步更新
5.如涉及枚举、状态、字典：
    - 前后端枚举值和大小写必须一致
    - 禁止硬编码，统一使用枚举常量或字典定义
6. 如涉及 Mapper/Repository：
    - 命名按业务类型命名（如 AnnotationTaskMapper），不要使用过于泛化且含义不清的命名
7. 删除确认无用且不会影响当前功能的旧字段、旧方法和冗余逻辑。
8. 编码前先思考，不要擅自假设。不要掩饰困惑。把取舍讲清楚。
9. 明确说明你的假设。如果不确定，就提问。
10. 如果存在多种理解方式，把它们都列出来——不要默默替用户做决定。
11. 如果有不清楚的地方，就停下来。指出哪里让你困惑。提问。

### Step 4: 验证确认

```
验证清单：
- [ ] 原问题可复现并已确认修复
- [ ] 正常主流程功能可用
- [ ] 相关联功能未受影响
- [ ] 边界场景已检查
- [ ] 控制台/日志无新增报错
- [ ] 数据读写正常
- [ ] 枚举/状态流转正常
- [ ] 文档/脚本已同步（如需要）

```

验证方式：

1. 重现原问题，确认已修复。
2. 测试相关联功能，确认无副作用。
3. 检查日志、控制台、网络请求、数据库数据状态。
4. 如果是偶现问题，说明当前验证结论及仍存在的不确定性。
5. 如果无法完整验证，明确指出剩余风险。

---


## 项目特定注意事项

- 枚举值：前后端枚举值、大小写、含义必须一致
- 状态字段：状态字段禁止硬编码，统一使用枚举常量或字典定义
---


## 禁止事项
- 在缺少关键上下文时直接断言根因
- 只根据单条报错就下结论，不追调用链
- 只修表面报错，不处理根因
- 为了“顺手优化”扩大无关改动范围
- 修复后不验证、不评估影响
- 忽略数据库实际数据状态
- 忽略配置、环境、缓存、第三方依赖等非代码因素
- 使用硬编码绕过枚举、状态、配置问题

## 使用提醒
当遇到以下场景时，优先使用本技能：

1. 控制台报错 / 后端异常 / SQL报错
2. 页面功能不正常但无明显报错
3. 前后端联调失败
4. 数据保存失败、查询异常、状态流转错误
5. 枚举/状态/字典不一致
6. 历史数据兼容问题
7. 环境切换后出现异常
8. 修复一个问题时需要评估是否影响其他功能