debug

调试

针对错误、测试失败、意外行为和生产环境问题进行系统性调试。

用法

/debug [issue] [--logs] [--correlate] [--trace] [--type bug|build|perf|deploy]

选项

标志	用途
--logs	启用日志模式分析（错误激增、频率、类型）
--correlate	对结构化日志运行 SQL 关联查询
--trace	深入分析堆栈跟踪及上下文
--type	问题类别：bug、build、perf(ormance)、deploy(ment)

适用场景

• 出现错误消息或堆栈跟踪
• 测试失败
• 代码行为异常
• 用户表示“出问题了”或“无法正常工作”
• 需要调查生产环境错误（--logs）
• 需要关联多个系统中的错误（--correlate）
• 需要深入分析堆栈（--trace）

调试流程

1. 捕获 - 获取错误消息、堆栈跟踪和复现步骤
2. 隔离 - 缩小故障位置范围
3. 假设 - 推测可能的原因
4. 测试 - 使用证据验证假设
5. 修复 - 实施最小化修复
6. 验证 - 确认解决方案有效

调查步骤

# Check recent changes that might have caused the issue
git log --oneline -10
git diff HEAD~3

# Find error patterns in logs
grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20

# Check test output
npm test 2>&1 | tail -50  # or pytest, cargo test, etc.

日志分析（--logs）

查找错误

# Recent errors with context
grep -B 5 -A 10 "ERROR" /var/log/app.log

# Count by error type
grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn

# Errors in time range
awk '/2024-01-15 14:/ && /ERROR/' app.log

# Find repeated errors
grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20

# Find error spikes
grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn

常见模式

模式	表明	操作
NullPointer	缺少空值检查	添加验证
Timeout	依赖项响应缓慢	添加超时和重试
Connection refused	服务宕机	检查运行状况并重试
OOM	内存泄漏	分析性能并增加限制
Rate limit	请求过多	添加退避机制并排队

关联查询（--correlate）

-- Errors by endpoint
SELECT endpoint, count(*) as errors
FROM logs
WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour'
GROUP BY endpoint ORDER BY errors DESC;

-- Error rate over time
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;

-- Correlate request IDs across services
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>.*?)\n(?P<trace>(?:\s+at .+\n)+)'
    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('\n')
        })
    return traces

调查清单

1. 捕获 - 获取完整的错误消息和堆栈跟踪
2. 时间戳 - 问题何时开始？
3. 频率 - 多久发生一次？频率是否在增加？
4. 范围 - 影响所有用户还是特定用户？
5. 变更 - 最近是否有部署？
6. 依赖项 - 外部服务是否受到影响？

输出格式

## Debug Report

**Issue:** [Brief description]
**Root Cause:** [What's actually wrong]

### Evidence

- [Finding 1]
- [Finding 2]

### Fix

[Code or configuration change]

### Verification

[How to confirm the fix works]

### Prevention

[How to prevent this in the future]

示例

输入：“TypeError: Cannot read property 'map' of undefined” **操作：**追踪未定义的值，查找应初始化数据的位置，并修复源头

输入：“测试失败” **操作：**运行测试，捕获失败信息，分析每项失败并修复根本问题

输入：/debug --logs "API returning 500 errors" **操作：**搜索状态码为 500 的日志，查找堆栈跟踪，确定根本原因并检查错误频率

输入：/debug --correlate "intermittent failures" **操作：**运行关联查询以查找模式，确定受影响的端点，并与事件进行关联