dmp-analysis

# Windows DMP Analysis for MaaFramework / MXU Projects ## Scope - Windows minidump (`.dmp`) files from MaaFramework / MXU based projects. - 崩溃通常可能来自 MaaFramework C++ 运行时、MXU Rust/Tauri 层、控制器模块、第三方视觉/推理依赖，或项目自身扩展。 - 默认覆盖 x86_64；aarch64 需要替换对应下载包架构。 ## Prerequisites 需要 `minidump-stackwalk` 和 `dump_syms`。 检查： ```powershell Get-Command minidump-stackwalk Get-Command dump_syms ``` 若本地缺失，按当前项目 CI / workflow / 文档安装；不要在未经用户同意时擅自安装全局工具。 ## Workflow ### 1. 获取 DMP 将 `.dmp` 放到临时分析目录，例如： ```text .cache/dmp-analysis/issue-<number>/ .cache/dmp-analysis/local-<timestamp>/ ``` 来源可能是： - issue 附件中的 `.dmp`。 - 日志包内部的 `.dmp`。 - 用户本地提供的崩溃转储文件。 ### 2. 无符号快速分析 ```powershell minidump-stackwalk "<path-to-dmp>" ``` 先获取： - OS 信息。 - 异常类型和异常码。 - 崩溃线程。 - 模块列表。 - 崩溃地址和模块偏移。 根据异常地址或 crashing thread 顶部帧识别疑似崩溃模块。 ### 3. 与日志关联 DMP 文件名常包含崩溃进程 PID，例如： ```text Project.exe.18188.dmp → PID 18188 ``` 用该 PID 与日志交叉验证： - `maafw.log` 中的 `[Px18188]`。 - `mxu-tauri.log` 中的实例 / agent / 进程生命周期。 - `go-service.log` 或 agent stdout/stderr 中的启动信息。 确认 DMP 对应的运行会话，避免把不同时间的日志混在一起。 ### 4. 确定关键版本 DMP 模块版本字段可能为空，优先从日志和配置获取： | 优先级 | 来源 | 线索 | | ------ | ---------------- | --------------------------------------------- | | 1 | `mxu-tauri.log` | MXU / MaaFramework 初始化版本 | | 2 | `go-service.log` | PI environment / client version | | 3 | config 文件 | `interface.json`、`maa_option.json`、项目配置 | | 4 | issue 正文 | 用户报告版本 | | 5 | DMP 模块列表 | 模块 version 字段，可能为 `?` | 记录： - MaaFramework version。 - MXU version。 - 项目自身版本。 - 控制器类型（Win32 / ADB / 其他）。 ### 5. 下载 PDB 符号 #### MaaFramework ```powershell $MaaVersion = "<version>" $Work = "<analysis-dir>" Invoke-WebRequest "https://github.com/MaaXYZ/MaaFramework/releases/download/v$MaaVersion/MAA-win-x86_64-v$MaaVersion.zip" -OutFile "$Work\maa-fw.zip" Expand-Archive "$Work\maa-fw.zip" "$Work\maa-fw" -Force ``` 常见 PDB： | PDB | 模块 | | ------------------------- | ----------------------- | | `MaaFramework.pdb` | MaaFramework.dll | | `MaaUtils.pdb` | MaaUtils.dll | | `MaaToolkit.pdb` | MaaToolkit.dll | | `MaaWin32ControlUnit.pdb` | MaaWin32ControlUnit.dll | | `MaaAdbControlUnit.pdb` | MaaAdbControlUnit.dll | | `MaaAgentServer.pdb` | MaaAgentServer.dll | | `MaaAgentClient.pdb` | MaaAgentClient.dll | #### MXU ```powershell $MxuVersion = "<version>" Invoke-WebRequest "https://github.com/MistEO/MXU/releases/download/v$MxuVersion/MXU-win-x86_64-v$MxuVersion.zip" -OutFile "$Work\mxu.zip" Expand-Archive "$Work\mxu.zip" "$Work\mxu" -Force ``` `mxu.pdb` 通常位于压缩包根目录。 ### 6. PDB 转 Breakpad `.sym` ```powershell $PdbDir = "$Work\pdb" $Symbols = "$Work\symbols" New-Item -ItemType Directory -Force $Symbols | Out-Null Get-ChildItem $PdbDir -Filter *.pdb | ForEach-Object { $name = $_.BaseName $header = & dump_syms $_.FullName 2>$null | Select-Object -First 1 $debugId = ($header -split '\s+')[3] $dest = Join-Path $Symbols "$name.pdb\$debugId" New-Item -ItemType Directory -Force $dest | Out-Null & dump_syms $_.FullName > (Join-Path $dest "$name.sym") } ``` ### 7. 符号化 stackwalk ```powershell minidump-stackwalk "<path-to-dmp>" "$Work\symbols" ``` 输出应包含函数名、源码路径和行号。如果符号化失败，报告原因并保留 module+offset 堆栈。 ### 8. 分析重点 #### 异常类型 - `EXCEPTION_ACCESS_VIOLATION` (`0xC0000005`)：空指针、悬垂指针、use-after-free。 - `EXCEPTION_STACK_OVERFLOW` (`0xC00000FD`)：无限递归或栈对象过大。 - `EXCEPTION_ILLEGAL_INSTRUCTION` (`0xC000001D`)：CPU 指令集、二进制损坏或错误模块。 - `STATUS_STACK_BUFFER_OVERRUN` (`0xC0000409`)：Windows fast-fail，不一定是真缓冲区溢出。 - 参数 `0x7` 常见于 `std::terminate()` / `abort()`，可能是未捕获 C++ 异常。 - 需要看调用者帧，而不是只归因到 `ucrtbase.dll`。 - `EXCEPTION_BREAKPOINT` (`0x80000003`)：断点、assert、panic 或主动触发崩溃。 #### 模块归属 - `Maa*.dll`：MaaFramework 运行时或控制器。 - `mxu.exe`：MXU/Tauri/Rust 层。 - `onnxruntime_*.dll`、`opencv_*`、OCR/推理库：第三方依赖。 - `DirectML.dll`、显卡驱动相关模块：图形/推理运行时。 - `ntdll.dll`、`KERNELBASE.dll`、`ucrtbase.dll`：通常要看上层调用者。 ### 9. 关联源码 如果符号化帧涉及 MaaFramework 或 MXU，并能确定版本，按需 clone 对应 tag 到临时目录： ```powershell git clone --depth 1 --branch "v<VERSION>" "https://github.com/MaaXYZ/MaaFramework.git" ".cache\upstream-src\MaaFramework" git clone --depth 1 --branch "v<VERSION>" "https://github.com/MistEO/MXU.git" ".cache\upstream-src\MXU" ``` 定位到具体源码行后，在报告中给出远端 GitHub blob 链接。 ## 输出格式 ````markdown ## DMP 分析结果 - DMP 文件：`<filename>` - 操作系统：`<OS version>` - 异常类型：`<EXCEPTION_*>` (`<hex>`) - 崩溃模块：`<module>+<offset>` - 符号化状态：已符号化 / 仅 module+offset ## 崩溃堆栈（crashing thread） ```text Frame 0: ... Frame 1: ... ``` ## 关键模块版本 | Module | Version | | ------------------ | ------- | | MaaFramework.dll | ... | | mxu.exe | ... | | Project executable | ... | ## 根因判断 - 崩溃归属：MaaFramework / MXU / 项目扩展 / 第三方依赖 / 未知 - 分析：... - 置信度：高 / 中 / 低 ## 建议 - 用户可尝试：... - 开发者修复方向：... - 还缺的证据：... ```` ## Cleanup 分析完成后可删除临时目录；删除前确认没有用户需要保留的附件或中间产物。