debugging

用途

该调试技能用于识别和修复代码错误、测试失败、异常行为以及生产环境问题，将通用调试流程与错误分析、日志解析和模式识别能力结合起来。当遇到代码中的错误或异常、测试失败、难以解释的行为或缺陷、需要分析堆栈跟踪与错误信息、排查生产问题、修复用户或 QA 反馈的问题、分析错误日志与堆栈、调查性能问题或异常、关联多个服务之间的错误、识别反复出现的错误模式、设置错误监控与告警，以及进行事故复盘分析时，都可以使用该技能。

主要能力

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

辅助脚本

该技能在 scripts/ 目录中包含 Python 辅助脚本：

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

用法：

python scripts/parse_logs.py /var/log/app.log

使用方式

可以直接提出调试请求，例如：

“调试这个错误：TypeError: Cannot read property 'x' of undefined”
“调查 test_user_service.js 中测试失败的原因”
“分析 /var/log/app.log 中的错误日志并找出根因”
“调查 API 返回 500 错误的原因”
“找出过去 24 小时这些错误日志中的模式”
“关联 API 服务与数据库之间的错误”

调试过程包括以下步骤：

捕获错误信息：读取完整错误消息，记录错误类型（如 TypeError、ReferenceError），识别错误位置（文件和行号）；分析调用栈，识别函数调用顺序，找到错误起源；检查最近代码变更、相关代码文件并理解执行流程。
错误提取（日志分析）：使用辅助脚本解析日志，或手动使用 grep 模式，例如：

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 日志做结构化解析，按 level 过滤出 error 或 critical 条目并映射出 timestamp、message、stack、context。
堆栈跟踪分析：识别 JavaScript/Node.js、Python、Java 等语言的常见堆栈格式，示例包括 TypeError 提示、py 的 Traceback 与 KeyError、Java 的 NullPointerException。
错误关联：按时间戳分组，识别错误峰值与模式，关联部署或变更，检查级联故障；跨服务边界映射错误，识别上下游关系，跟踪错误传播路径并找到共同故障点。
模式识别：识别常见错误模式，例如 N+1 查询问题（循环中多次数据库查询）、内存泄漏（内存持续增长不释放）、竞态条件（并发请求下才出现的间歇失败）、超时问题（特定时长后报错，如 30 秒）。
复现问题：找出触发错误的确切条件，创建最小测试用例复现，确认问题可稳定复现，并清晰记录步骤。
隔离失败位置：阅读错误位置附近代码，追踪执行路径，识别假设失效之处，检查变量状态；使用策略性日志、调试器断点、检查变量状态与返回值、核对数据结构等技巧。
形成并测试假设：思考可能原因、可能错误的假设、未考虑的边界情况、可能缺失的依赖；通过添加日志、测试边界情况、检查输入校验、验证依赖可用性、用不同数据测试来验证假设。
根因分析：从症状开始，反推错误前发生了什么，检查模式是复发还是孤立，关联同时发生的事件，识别底层问题。分析框架包括错误描述、频率、时间线、受影响服务、用户影响、根因假设、支持假设的证据以及建议的即时修复与长期预防措施。
实施最小修复：修复根因而非症状，做尽可能小的改动，保留现有功能，不引入新复杂度，添加适当的错误处理；用复现用例测试修复，验证无回归，检查边界情况，确认错误处理合适且修复完整。
记录解决方案：包括根因说明、支持诊断的证据、具体代码修复、测试方法和预防建议。

示例

示例 1：空引用错误

输入：Error: TypeError: Cannot read property 'name' of undefined

输出分析指出错误类型为 TypeError，位置在 src/services/user.js:45，根因是 getUser() 在用户不存在时返回 undefined，但代码假定总会返回用户对象。代码位置与修复方式为添加空值检查：

const user = getUser(userId); if (!user) { throw new Error(User ${userId} not found); } console.log(user.name);

预防建议包括：始终校验可能返回 null/undefined 的函数返回值、使用可选链 user?.name、添加 TypeScript 类型以在编译期捕获此类问题。

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

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

输出分析检测到 PostgreSQL 的 ECONNREFUSED 错误，频率为每分钟 15 次，始于两小时前；时间线显示错误在 14:30 部署后开始。根因假设为连接池耗尽，证据包括错误与高流量时段（14:30-16:30）相关、连接池大小为 10 而并发请求 50+、错误处理器中缺少连接清理、峰值时错误激增。代码位置为 src/db/connection.js:45，修复方式是在异常处理中确保释放连接：

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 并参考相应章节。

最佳实践

调试方法：从症状入手，先理解问题再跳到解决方案；反向追溯，从错误追到原因；测试假设，不要臆断而要验证；最小改动，只修复必要之处；验证修复，始终测试修复是否有效。

日志分析技巧：使用结构化日志（JSON 更易解析分析）；在所有日志中包含请求 ID、用户 ID、时间戳等上下文；使用合适日志级别（error、warn、info、debug）；使用请求 ID 跨服务追踪错误；对相似错误分组以识别模式。

错误模式识别：

基于时间的模式：特定时间出现错误（部署窗口、高峰时段）、特定时长后出现错误（超时、内存泄漏）、特定事件期间出现错误（数据库迁移、清缓存）。
频率模式：突然激增（部署问题、流量高峰）、逐渐增加（内存泄漏、资源耗尽）、间歇出现（竞态条件、时序问题）。
关联模式：多个服务同时报错（基础设施问题）、特定用户操作后报错（应用缺陷）、与外部服务相关的错误（依赖问题）。

常见调试模式：对 null/undefined 进行检查；使用 try/catch 并在 catch 中带上下文记录错误；在操作前后添加策略性日志；进行类型检查，例如 typeof value !== 'string' 时抛出 TypeError。

监控设置：可按错误率监控，例如错误率超过 1% 阈值时告警；告警条件可包括错误率激增超过 5%、出现新错误类型、出现严重错误模式、跨服务错误关联。

预防策略：在边界处校验所有输入；使用 TypeScript 或类型检查保证类型安全；在合适层级捕获错误（错误边界）；为边界情况编写测试；代码审查常见陷阱。

限制

资料未提供该技能的收费方式、价格、平台支持范围或具体安装命令等信息，暂未提供。

技能介绍

用途