dmp-analysis

name	dmp-analysis
description	分析 Windows 崩溃转储文件（.dmp），诊断 MaaFramework / MXU 项目及其依赖项的崩溃。用于 issue 日志包或附件中发现 .dmp 文件，或用户要求分析 DMP / 崩溃转储时。

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。

检查：

Get-Command minidump-stackwalk
Get-Command dump_syms

若本地缺失，按当前项目 CI / workflow / 文档安装；不要在未经用户同意时擅自安装全局工具。

Workflow

1. 获取 DMP

将 .dmp 放到临时分析目录，例如：

.cache/dmp-analysis/issue-<number>/
.cache/dmp-analysis/local-<timestamp>/

来源可能是：

• issue 附件中的 .dmp。
• 日志包内部的 .dmp。
• 用户本地提供的崩溃转储文件。

2. 无符号快速分析

minidump-stackwalk "<path-to-dmp>"

先获取：

• OS 信息。
• 异常类型和异常码。
• 崩溃线程。
• 模块列表。
• 崩溃地址和模块偏移。

根据异常地址或 crashing thread 顶部帧识别疑似崩溃模块。

3. 与日志关联

DMP 文件名常包含崩溃进程 PID，例如：

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

$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

$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

$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

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 到临时目录：

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 链接。

输出格式

## 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

分析完成后可删除临时目录；删除前确认没有用户需要保留的附件或中间产物。