# 5.1 问题反馈

在提交 Issue 前，请按照以下指南提供必要的信息，以便我们更快地定位和解决问题。

> [!NOTE]
> ⚠️ **请先更新到最新版本的 MaaFramework**，确认问题是否仍然存在后再提交 Issue。旧版本的问题可能已在新版本中修复。  
> 同时，请确保上传的日志、调试图像等文件来自最新版本。

## 工作目录

后文提到的日志、调试图像等文件均位于工作目录下，请先确认您的工作目录位置：

| 使用场景 | 工作目录位置 |
| ------- | ----------- |
| 通用 GUI | 可执行文件所在目录 |
| MaaDebugger | 当前启动目录（cwd） |
| VSCode 插件 | 侧边栏点击 "Open Maa Log" 可直接打开 |
| 自行集成 | 取决于您设置的 `LogDir` 路径 |

## 日志文件

日志是排查问题的关键信息，请务必提供完整的日志文件。

### 日志位置

若无特殊设置，日志文件位于：`<工作目录>/debug/maafw.log`

### 上传前请确认

1. 打开日志文件，翻到末尾检查时间戳是否为问题发生时间
2. 若文件明显过短（可能已被 flush），请同时上传 `debug/maafw.bak.log`

### 上传要求

- **提供完整日志**：直接上传 `.log` 文件，体积过大可压缩为 `.zip`
- **避免截取片段**：自行截取的日志片段往往缺失关键上下文
- **尽量提供干净日志**：若问题可稳定复现，建议删除原日志后重新运行一次，上传最新的问题日志，避免大量无关日志干扰排查。偶发性问题无需强求，直接上传即可
- **对比日志**：若某操作正常、另一操作异常，建议同时上传正常和异常时的日志，并重命名以便区分（如 `maa_ok.log` / `maa_fail.log`），便于对比定位差异

## Pipeline 配置

若问题与任务流程相关，请提供相关的 Pipeline JSON 配置：

- 出错节点的完整定义
- 相关的前后节点配置（如 `next`、`interrupt` 等引用的节点）
- 若节点较多，可只保留复现问题所需的最小节点集合

示例：

```json
{
    "问题节点": {
        "recognition": "TemplateMatch",
        "template": "xxx.png",
        "threshold": 0.7,
        "action": "Click",
        "next": ["后续节点"]
    }
}
```

## 崩溃问题

若程序崩溃，请额外提供 Crash Dump 文件：

- **Windows**：通常位于 `C:\Users\<用户名>\AppData\Local\CrashDumps\`，文件格式为 `.dmp`
- **Linux/macOS**：检查 core dump 文件，或通过 `dmesg` / 系统日志获取崩溃信息

请根据文件修改日期确认 dump 文件与崩溃时间是否对应，避免上传无关的历史 dump。

## 识别问题

识别相关问题需要提供调试图像和相关图片资源。

### 开启调试图像

在 `<工作目录>/config/maa_option.json` 中设置：

```json
{
    "save_draw": true
}
```

启用后，识别的可视化图像将保存至 `<工作目录>/debug/vision/` 目录，文件命名格式：`{节点名}_{识别ID}_{时间戳}.jpg`

Draw 图像会在原始截图上标注 ROI 区域、识别命中位置、匹配详情（如模板匹配会在图像右侧显示模板图片及匹配分数）。

### 需要提供的图片

| 类型 | 说明 | 必需 |
| --- | ---- | --- |
| Draw 图像 | `debug/vision/` 目录下对应的调试图片 | ✅ |
| 模板图片 | Pipeline 中 `template` 字段引用的图片（位于 `resource/image/`） | ✅ |
| 原始截图 | 问题发生时的完整屏幕截图 | 建议 |

同时请说明预期识别结果与实际识别结果的差异。

## 最小复现

请尽可能提供 **最小复现** 示例，这能极大加速问题定位。

- 精简到只包含触发问题的最少代码和资源
- 去除与问题无关的业务逻辑和节点
- 可独立运行并稳定复现问题

**简单场景**：在 Issue 中直接贴出关键代码片段和 Pipeline JSON  
**复杂场景**：提供可运行的最小项目压缩包，或创建 GitHub 仓库

## 问题反馈清单

### 通用问题

- [ ] 完整的 `maafw.log` 日志文件
- [ ] 问题描述（预期行为 vs 实际行为）
- [ ] MaaFramework 版本号
- [ ] Pipeline JSON（若与任务流程相关）

### 崩溃问题（额外提供）

- [ ] Crash Dump 文件（`.dmp`）
- [ ] **精确的 MaaFramework 版本号**（崩溃分析依赖对应版本的调试符号）
- [ ] 崩溃前的操作步骤

### 识别问题（额外提供）

- [ ] `debug/vision/` 下的 Draw 调试图片
- [ ] Pipeline JSON（相关节点的识别配置）
- [ ] 模板图片（若使用 TemplateMatch/FeatureMatch）
- [ ] 原始截图（可选，但建议提供）

### 加分项

- [ ] 最小复现项目
- [ ] 问题复现步骤

## 其他沟通渠道

除了 GitHub Issue，您也可以通过以下方式获取帮助：

- **QQ 群**：595990173（仅讨论开发相关议题）

简单的使用问题建议先在群里咨询，复杂的 Bug 或功能建议请提交 Issue。

## 提交 Issue

请在 [GitHub Issues](https://github.com/MaaXYZ/MaaFramework/issues) 提交问题。

提供的信息越完整，问题解决越快。感谢您的反馈！
