name: debug description: 通过日志分析和关联调试错误、测试失败和意外行为。在遇到问题、错误消息、分析日志或调查生产错误时使用。
调试
系统性的调试错误、测试失败、意外行为和生产问题。
使用方法
/debug [issue] [--logs] [--correlate] [--trace] [--type bug|build|perf|deploy]
选项
| 标志 | 用途 |
|---|---|
--logs |
启用日志模式分析（错误高峰、频率、类型） |
--correlate |
在结构化日志上运行SQL关联查询 |
--trace |
带上下文的深度堆栈跟踪分析 |
--type |
问题类别：bug（错误）、build（构建）、perf（性能）、deploy（部署） |
何时使用
- 出现错误消息或堆栈跟踪
- 测试失败
- 代码行为意外
- 用户说“坏了”或“不工作”
- 需要调查生产错误（使用
--logs） - 需要跨系统关联错误（使用
--correlate） - 需要深度堆栈分析（使用
--trace）
调试过程
- 捕获 - 获取错误消息、堆栈跟踪和重现步骤
- 隔离 - 缩小失败位置
- 假设 - 形成关于原因的假设
- 测试 - 用证据验证假设
- 修复 - 实施最小修复
- 验证 - 确认解决方案有效
调查步骤
# 检查可能导致问题的最近更改
git log --oneline -10
git diff HEAD~3
# 在日志中查找错误模式
grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20
# 检查测试输出
npm test 2>&1 | tail -50 # 或 pytest、cargo test 等
日志分析（--logs）
查找错误
# 带上下文的最近错误
grep -B 5 -A 10 "ERROR" /var/log/app.log
# 按错误类型计数
grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn
# 时间范围内的错误
awk '/2024-01-15 14:/ && /ERROR/' app.log
# 查找重复错误
grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20
# 查找错误高峰
grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn
常见模式
| 模式 | 指示 | 行动 |
|---|---|---|
| NullPointer | 缺少空值检查 | 添加验证 |
| Timeout | 依赖项慢 | 添加超时、重试 |
| Connection refused | 服务宕机 | 检查健康状态、重试 |
| OOM | 内存泄漏 | 分析、增加限制 |
| Rate limit | 请求过多 | 添加回退、队列 |
关联查询（--correlate）
-- 按端点的错误
SELECT endpoint, count(*) as errors
FROM logs
WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour'
GROUP BY endpoint ORDER BY errors DESC;
-- 随时间变化的错误率
SELECT
date_trunc('minute', time) as minute,
count(*) filter (where level = 'ERROR') as errors,
count(*) as total
FROM logs
WHERE time > NOW() - INTERVAL '1 hour'
GROUP BY minute ORDER BY minute;
-- 跨服务关联请求ID
SELECT service, message, time
FROM logs
WHERE request_id = 'req-12345'
ORDER BY time;
堆栈跟踪分析（--trace）
解析堆栈跟踪
import re
def parse_stack_trace(log_content: str) -> list[dict]:
pattern = r'(?P<exception>\w+Error|\w+Exception): (?P<message>.*?)
(?P<trace>(?:\s+at .+
)+)'
traces = []
for match in re.finditer(pattern, log_content):
traces.append({
'type': match.group('exception'),
'message': match.group('message'),
'trace': match.group('trace').strip().split('
')
})
return traces
调查清单
- 捕获 - 获取完整错误消息和堆栈跟踪
- 时间戳 - 何时开始？
- 频率 - 多频繁？是否增加？
- 范围 - 所有用户还是特定？
- 更改 - 最近部署？
- 依赖项 - 外部服务受影响？
输出格式
## 调试报告
**问题：** [简要描述]
**根本原因：** [实际错误]
### 证据
- [发现 1]
- [发现 2]
### 修复
[代码或配置更改]
### 验证
[如何确认修复有效]
### 预防
[如何预防未来发生]
示例
输入： “TypeError: Cannot read property ‘map’ of undefined” 操作： 跟踪未定义值，找到数据应初始化的地方，修复源头
输入： “测试失败” 操作： 运行测试，捕获失败，分析每个失败，修复基础问题
输入： /debug --logs "API 返回 500 错误"
操作： 在日志中搜索 500 状态，查找堆栈跟踪，识别根本原因，检查错误频率
输入： /debug --correlate "间歇性失败"
操作： 运行关联查询查找模式，识别受影响的端点，与事件关联