name: debugging description: 全面的错误调试专家，用于处理错误、测试失败、日志分析和系统问题。适用于遇到问题、分析错误日志、调查系统异常、调试生产问题、分析堆栈跟踪或识别根本原因时使用。结合通用调试工作流程与错误模式检测和日志分析。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

调试

此技能提供全面的调试能力，用于识别和修复错误、测试失败、意外行为和生产问题。它结合了通用调试工作流程与专门的错误分析、日志解析和模式识别。

何时使用此技能

当代码中遇到错误或异常时
当测试失败且需要理解原因时
当调查意外行为或错误时
当分析堆栈跟踪和错误消息时
当调试生产问题时
当修复用户或QA报告的问题时
当分析错误日志和堆栈跟踪时
当调查性能问题或异常时
当关联跨多个服务的错误时
当识别重复出现的错误模式时
当设置错误监控和警报时
当进行事件的事后分析时

此技能的功能

错误分析：捕获并分析错误消息和堆栈跟踪
日志解析：使用正则表达式模式和结构化解析从日志中提取错误
堆栈跟踪分析：分析多种编程语言的堆栈跟踪
错误关联：识别分布式系统中错误之间的关系
模式识别：检测常见错误模式和反模式
复现：识别复现问题的步骤
隔离：定位代码中的确切故障点
根本原因分析：从症状向后追溯以识别根本原因
最小修复：实施解决该问题的最小变更
验证：确认解决方案有效且不会引入新问题
监控设置：创建用于错误检测的查询和警报

辅助脚本

此技能在 scripts/ 中包含Python辅助脚本：

parse_logs.py：解析日志文件并提取错误、异常和堆栈跟踪。输出包含错误分析和模式检测的JSON。
```
python scripts/parse_logs.py /var/log/app.log
```

如何使用

调试错误

调试此错误：TypeError: 无法读取未定义的属性 'x'

调查 test_user_service.js 中测试失败的原因

分析错误日志

分析 /var/log/app.log 中的错误日志并识别根本原因

调查API返回500错误的原因

模式检测

从过去24小时的错误日志中查找模式

关联API服务和数据库之间的错误

调试过程

1. 捕获错误信息

错误消息：

读取完整的错误消息
注意错误类型（TypeError、ReferenceError等）
识别错误位置（文件和行号）

堆栈跟踪：

分析调用堆栈
识别函数调用序列
查找错误起源位置

上下文：

检查最近的代码变更
查看相关代码文件
理解执行流程

2. 错误提取（日志分析）

使用辅助脚本：

此技能包含一个用于解析日志的Python辅助脚本：

# 解析日志文件并提取错误
python scripts/parse_logs.py /var/log/app.log

手动日志解析模式：

# 从日志中提取错误
grep -i "error\|exception\|fatal\|critical" /var/log/app.log

# 提取堆栈跟踪
grep -A 20 "Exception\|Error\|Traceback" /var/log/app.log

# 提取特定错误类型
grep "TypeError\|ReferenceError\|SyntaxError" /var/log/app.log

结构化日志解析：

// 解析JSON日志
const errors = logs
  .filter(log => log.level === 'error' || log.level === 'critical')
  .map(log => ({
    timestamp: log.timestamp,
    message: log.message,
    stack: log.stack,
    context: log.context
  }));

3. 堆栈跟踪分析

常见模式：

JavaScript/Node.js：

错误：无法读取未定义的属性 'x'
    在 FunctionName (file.js:123:45)
    在 AnotherFunction (file.js:456:78)

Python：

Traceback（最近一次调用）：
  文件 "app.py"，第123行，在 function_name 中
    result = process(data)
  文件 "utils.py"，第45行，在 process 中
    return data['key']
KeyError: 'key'

Java：

java.lang.NullPointerException
    在 com.example.Class.method(Class.java:123)
    在 com.example.AnotherClass.call(AnotherClass.java:456)

4. 错误关联

时间线分析：

按时间戳分组错误
识别错误峰值和模式
与部署或变更关联
检查级联故障

服务关联：

映射跨服务边界的错误
识别上游/下游关系
跟踪错误传播路径
查找常见故障点

5. 模式识别

常见错误模式：

N+1查询问题：

循环中的多个数据库查询
模式：SELECT * FROM users; SELECT * FROM posts WHERE user_id = ?

内存泄漏：

内存使用量逐渐增加
模式：内存随时间增长而不释放

竞态条件：

负载下的间歇性故障
模式：仅在并发请求时发生错误

超时问题：

请求超时
模式：特定持续时间后出现错误（例如30秒）

6. 复现问题

复现步骤：

识别触发错误的确切条件
创建复现该问题的最小测试用例
验证问题是否一致且可复现
清晰地记录步骤

示例：

## 复现步骤

1. 导航到 `/users/123`
2. 点击“编辑个人资料”
3. 不填写必填字段提交表单
4. 发生错误：“无法读取未定义的属性 'validate'”

7. 隔离故障位置

代码分析：

阅读错误位置周围的代码
跟踪执行路径
识别假设被打破的位置
检查变量状态和值

调试技术：

添加策略性日志以跟踪执行
使用调试器断点
检查变量状态
检查函数返回值
验证数据结构

8. 形成和测试假设

假设形成：

什么可能导致此错误？
哪些假设可能是错误的？
哪些边缘情况未被考虑？
哪些依赖项可能缺失？

测试假设：

添加日志以验证假设
测试边缘情况
检查输入验证
验证依赖项是否可用
使用不同数据测试

9. 根本原因分析

调查步骤：

从症状开始：发生了什么错误？
向后追溯：错误发生前发生了什么变化？
检查模式：这是重复出现还是孤立事件？
关联事件：同时发生了什么其他事件？
识别原因：根本问题是什么？

分析框架：

## 错误分析

**错误**：[描述]
**频率**：[发生频率]
**时间线**：[何时开始]
**受影响的服务**：[哪些服务]
**用户影响**：[影响多少用户]

**根本原因假设**：
- [主要假设及证据]
- [替代假设]

**证据**：
- [支持假设的日志条目]
- [观察到的错误模式]
- [与其他事件的关联]

**推荐行动**：
- [立即修复]
- [长期预防]

10. 实施最小修复

修复原则：

修复根本原因，而不仅仅是症状
尽可能进行最小的变更
保留现有功能
不引入新的复杂性
添加适当的错误处理

修复验证：

使用复现案例测试修复
验证没有回归
检查边缘情况
确保错误处理适当
确认修复完整

11. 记录解决方案

文档应包含：

根本原因解释
支持诊断的证据
具体的代码修复
测试方法
预防建议

示例

示例1：空引用错误

输入：错误：TypeError: 无法读取未定义的属性 'name'

输出：

## 调试分析

### 错误信息
- **类型**：TypeError
- **位置**：`src/services/user.js:45`
- **消息**：无法读取未定义的属性 'name'

### 根本原因
当用户未找到时，`getUser()` 函数返回 `undefined`，但代码假设它始终返回用户对象。

### 代码位置
```javascript
// src/services/user.js:45
const user = getUser(userId);
console.log(user.name); // ❌ 错误：user 是 undefined

修复

// 添加空值检查
const user = getUser(userId);
if (!user) {
  throw new Error(`用户 ${userId} 未找到`);
}
console.log(user.name); // ✅ 安全

预防

始终验证可能返回 null/undefined 的函数的返回值
使用可选链：user?.name
添加 TypeScript 类型以在编译时捕获这些问题


### 示例2：数据库连接错误（日志分析）

**输入**：显示数据库连接失败的错误日志

**输出**：

```markdown
## 错误分析：数据库连接失败

### 检测到的模式

**错误**：来自 PostgreSQL 的 `ECONNREFUSED` 错误
**频率**：15 次错误/分钟，2 小时前开始
**时间线**：错误在 14:30 部署后开始

### 根本原因分析

**假设**：连接池耗尽

**证据**：
- 错误与高流量时段（14:30-16:30）相关
- 连接池大小：10，并发请求：50+
- 错误处理程序中没有连接清理
- 错误在峰值使用期间激增

**代码位置**：`src/db/connection.js:45`

**修复**：
```javascript
// 添加连接清理
try {
  const result = await query(sql);
  return result;
} catch (error) {
  // 确保连接被释放
  await releaseConnection();
  throw error;
}

监控查询：

SELECT count(*) FROM pg_stat_activity WHERE state = 'active';


## 参考文件

如需详细的调试工作流程、错误模式和技术，请根据需要加载参考文件：

- **`references/debugging_workflows.md`** - 按问题类型划分的常见调试工作流程、特定语言调试、调试技术、调试清单和常见错误模式（数据库错误、内存泄漏、竞态条件、超时、身份验证错误、网络错误、应用程序错误、性能错误）
- **`references/INCIDENT_POSTMORTEM.template.md`** - 事件事后分析模板，包含时间线、根本原因分析和行动项

调试特定类型问题或分析错误模式时，请加载 `references/debugging_workflows.md` 并参考相关部分。

## 最佳实践

### 调试方法

1. **从症状开始**：在跳转到解决方案之前先了解问题所在
2. **向后追溯**：从错误追踪到原因
3. **测试假设**：不要假设，要验证
4. **最小变更**：仅修复必要的内容
5. **验证修复**：始终测试修复是否有效

### 日志分析技术

1. **使用结构化日志**：JSON 日志更易于解析和分析
2. **包含上下文**：向所有日志添加请求ID、用户ID、时间戳
3. **日志级别**：使用适当的级别（错误、警告、信息、调试）
4. **关联ID**：使用请求ID跨服务追踪错误
5. **错误分组**：分组相似错误以识别模式

### 错误模式识别

**基于时间的模式：**
- 特定时间的错误（部署窗口、高峰时段）
- 特定持续时间后的错误（超时、内存泄漏）
- 特定事件期间的错误（数据库迁移、缓存清除）

**频率模式：**
- 突然激增（部署问题、流量激增）
- 逐渐增加（内存泄漏、资源耗尽）
- 间歇性（竞态条件、时序问题）

**关联模式：**
- 多个服务同时出现错误（基础设施问题）
- 特定用户操作后的错误（应用程序错误）
- 与外部服务相关的错误（依赖项问题）

### 常见调试模式

**空值/未定义检查：**
```javascript
// 始终检查空值/未定义
if (!value) {
  // 处理缺失值
}

错误处理：

try {
  // 风险操作
} catch (error) {
  // 记录带上下文的错误
  console.error('操作失败：', error);
  // 优雅处理
}

日志记录：

// 策略性日志记录
console.log('操作前：', { userId, data });
const result = await operation();
console.log('操作后：', { result });

类型检查：

// 验证类型
if (typeof value !== 'string') {
  throw new TypeError('预期为字符串');
}

监控设置

错误率监控：

// 随时间跟踪错误率
const errorRate = errors.length / totalRequests;
if (errorRate > 0.01) { // 1% 错误率阈值
  alert('检测到高错误率');
}

错误警报：

错误率激增时警报（> 5% 增加）
新错误类型时警报
关键错误模式时警报
跨服务错误关联时警报

预防策略

输入验证：在边界验证所有输入
类型安全：使用 TypeScript 或类型检查
错误边界：在适当级别捕获错误
测试：为边缘情况编写测试
代码审查：审查代码中的常见陷阱

调试 debugging

调试