rspack-debugging

用途

rspack-debugging 用于调试 Rspack 的原生崩溃问题。Rspack 基于 Rust 实现，该技能指导用户捕获其底层崩溃状态，借助 LLDB 调试器与带调试符号的 Rspack 包，获取详细的堆栈回溯，从而精确定位问题。目标场景包括：段错误（segmentation fault）、死锁（deadlock）、构建卡死（stuck builds）等。调试流程侧重于非交互式、自动化方式，便于轻松捕获回溯。

主要能力

该技能提供以下能力：

通过 LLDB 获取详细的线程堆栈回溯，用于问题定位。
将生产环境包替换为带调试符号的调试包，以看到有用的堆栈信息。
针对不同崩溃场景提供对应的调试工作流指南。
保存调试产物（回溯、tracing 日志）到本地文件。
调试结束后恢复原始依赖配置。

使用方式

准备工作

安装 LLDB：
- macOS：xcode-select --install
- Linux：安装 lldb 包（例如 apt-get install lldb）
- 详细指南见 references/lldb.md。
替换调试包：生产包（如 @rspack/core）已剥离调试符号，必须替换为 @rspack-debug/* 系列包才能看到有用的堆栈信息。

自动替换脚本：在保持工作目录位于用户项目的前提下，相对于 Skill 根目录解析并运行脚本 scripts/setup_debug_deps.cjs：
```
node "<skill-root>/scripts/setup_debug_deps.cjs"
```
运行上述脚本会自动向 package.json 添加 pnpm.overrides 配置，将 Rspack 包指向对应的 Debug 版本。之后务必运行 pnpm install 更新依赖。

调试工作流

根据具体场景选择并阅读对应的指南：

指南 A：HMR 期间崩溃。场景：DevServer HMR 期间稳定崩溃/死锁。阅读 references/guide_a_hmr_crash.md。
指南 B：构建期间崩溃。场景：构建期间稳定崩溃/死锁（或频繁出现的不稳定构建崩溃）。阅读 references/guide_b_build_crash.md。
指南 C：附加到卡死进程。场景：构建期间的不稳定死锁（随机发生）。阅读 references/guide_c_attach_to_stuck_process.md。
指南 D：coredump 分析（开发）。场景：DevServer HMR 期间的不稳定崩溃（难以交互式捕获）。阅读 references/guide_d_coredump_analysis_dev.md。
指南 E：coredump 分析（构建）。场景：构建期间的不稳定崩溃。阅读 references/guide_e_coredump_analysis_build.md。
指南 F：异步死锁识别。场景：不稳定的异步死锁，主线程卡在 uv_run。阅读 references/guide_f_async_deadlock.md。

保存调试产物

对 Agent 的关键指示：当成功获取回溯或 tracing 日志后，必须将其保存到用户项目目录下的本地文件中，以便会话结束后仍然保留。

创建目录：确保项目根目录下存在名为 debug_artifacts 的目录。
保存回溯：将 thread backtrace all 的完整输出写入 debug_artifacts/backtrace_<timestamp>.txt。
保存 tracing 日志：（仅在使用 Tracing Skill 时）。

环境恢复

调试完成后，将 package.json 恢复为使用生产包：

node "<skill-root>/scripts/setup_debug_deps.cjs" --restore
pnpm install

使用与准备阶段相同的 <skill-root> 解析结果。

适用场景

开发环境 DevServer HMR 期间出现稳定或不稳定的崩溃、死锁。
构建（build）期间出现稳定或不稳定的崩溃、死锁。
构建期间随机出现、难以交互式捕获的死锁。
主线程卡在 uv_run 的异步死锁。

限制

依赖 LLDB 调试器，需先安装。
生产包已剥离调试符号，必须替换为 @rspack-debug/* 系列包才能获得有效堆栈信息。
使用 pnpm 的 overrides 机制替换依赖，恢复时需要重新执行安装。
资料中未提供各调试指南的具体内容，仅列出其对应文件与适用场景。