5.1 问题反馈

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

NOTE

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

工作目录

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

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

日志文件

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

日志位置

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

上传前请确认

打开日志文件，翻到末尾检查时间戳是否为问题发生时间
若文件明显过短（可能已被 flush），请同时上传 debug/maa.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 仓库

问题反馈清单

通用问题

完整的 maa.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 提交问题。

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

5.1 问题反馈 ​

工作目录 ​

日志文件 ​

日志位置 ​

上传前请确认 ​

上传要求 ​

Pipeline 配置 ​

崩溃问题 ​

识别问题 ​

开启调试图像 ​

需要提供的图片 ​

最小复现 ​

问题反馈清单 ​

通用问题 ​

崩溃问题（额外提供） ​

识别问题（额外提供） ​

加分项 ​

其他沟通渠道 ​

提交 Issue ​