• GUI 自动化
• AI 应用

本文是 M9A（重返未来：1999 小助手）官方「问题上报」指南的深度展开版。当你在使用 M9A 过程中遇到报错、闪退、任务异常时，本文将带你走完"重启自检 → 判断问题归属 → 选择上报渠道 → 准备logs与debug上报材料 → 提交给开发者"的完整流程，并深入讲解这些日志文件在 agent 日志系统 中是如何生成、落盘与轮转的，让你交出去的材料真正能帮助开发者快速定位问题。

一、为什么需要一套标准的上报流程

M9A 是一个基于 MaaFramework 的自动化助手，运行链路横跨"游戏客户端 → 模拟器 ADB 连接 → MaaFW Agent 进程 → 自定义 pipeline 与 Custom 识别/动作"，任何一个环节出问题都可能表现为任务不执行、闪退或界面卡死。开发者无法直接看到你的屏幕和操作环境，只能依靠你提供的日志与截图来还原现场。

官方在 3.问题上报.md 中明确强调："开发者不是大仙，不能靠算卦来判断出错误的原因"。因此，一套"先自检、再分类、带足材料"的上报流程，既是给开发者的支持，也是让问题更快被修复的捷径。

二、上报前的第一步：先重启，再更新到最新版

遇到问题不要急着上报，先按顺序执行两个动作：

1. 重启电脑。M9A 依赖 ADB 连接、屏幕采集与后台 Agent 服务，长时间运行后模拟器端口、资源句柄或系统级依赖可能处于异常状态，重启能排除大量偶发问题。
2. 重新下载并解压最新版。很多"问题"其实是旧版本的已知 bug，已经在新版中修复。M9A 官方提供三个获取渠道：GitHub Releases、Mirror酱与官方QQ 群（具体入口见原文档，此处不再列出链接）。

关于"版本"这一环，仓库的实现层面有两点值得了解：

• 资源数据（活动、作战、兑换码、局外演绎等）与客户端版本是分开管理的。Agent 启动时会通过 version_checker.py 读取 interface.json 中的version与mirrorchyan_rid，调用 MirrorChyan API 检查资源是否为最新，并按alpha/beta/stable通道取更激进的一方比较。
• 资源清单（manifest）支持热更新，agent_runtime.py 会把更新失败的影响范围整理成可读文本，并明确提示"若反复失败，请携带debug/custom日志反馈"。

也就是说，即使你下载的是最新客户端，资源也可能因为网络原因停留在旧版本——这本身就是一种需要上报的场景，而"日志"正是判断它发生与否的依据。

三、判断问题归属：是你的个人问题，还是需要上报？

重启并更新到最新版之后，如果问题依然存在，先做一次简单的归属判断：

• 配置类问题：连接不上模拟器、运行库缺失、资源加载失败等，多数属于环境问题。这类问题请先查阅 常见问题 faq.md 与 新手上路 newbie.md，其中按"下载/安装问题、运行中闪退、运行库问题、Agent 长时间启动无反应、资源加载问题、连接问题"六类给出了对应解法。
• 确属异常：排除了个人环境因素后，再选择上报渠道。官方渠道为GitHub Issues（适合提交带完整材料的结构化报告）与QQ 群（适合快速交流与补充信息）。

从源码结构看，M9A 的启动入口 main.py 会强制把工作目录切换到项目根目录，再经 agent_runtime.py 完成"版本检查 → 资源热更新 → 注册 Custom 动作/识别 → 启动 AgentServer"的流程。如果你在启动阶段就卡住或闪退，问题大概率集中在运行库、ADB 连接或资源热更新这三块，这也与 FAQ 的分类一一对应。

四、核心材料：logs与debug两个文件夹

上报时最重要的材料是 M9A 根目录下名为logs与debug的两个文件夹，除此之外还可以视情况录制软件运行出错过程的视频。请直接把这几个材料整体压缩后提交，不要只截图其中一两行日志。

4.1 各日志文件的落盘位置与内容

结合 开发文档 fix.md 与源码实现，M9A 的日志分布在以下位置：

4.2 日志是怎么写出来的：源码视角

debug/custom/下的日志由 agent/utils/logger.py 统一管理，默认在debug/custom目录下建两个 sink（见_setup_loguru_logger）：

• 控制台 sink：按客户端形态渲染——MFAAvalonia 面板要求每条日志带info:/warn:前缀逐行输出（见_format_mfaa_message），MXU 面板则按 HTML 渲染并做严格转义防注入（见_format_mxu_html_message）；
• 文件 sink：写入debug/custom/{time:YYYY-MM-DD}.log，固定 DEBUG 级，格式为{time} | {level} | {name}:{function}:{line} | {message}，并配置了rotation="00:00"（每天零点轮转一个新文件）、retention="2 weeks"（保留两周）与compression="zip"（旧文件自动压缩）。

也就是说，即使 GUI 里看不到的调试信息（例如 agent_runtime.py 中记录的 MaaFW 原生库版本、加载路径、PI 环境变量快照等），也都会完整落在debug/custom/*.log里——这正是它被指定为"上报必需材料"的原因。若未安装 loguru，logger.py 会回退到标准 logging 路径，将日志写入debug/custom/runtime.log，并按天轮转保留 14 份。

相关渲染分支的正确性由 test_logger_markup.py 用真实 loguru 路径逐一验证，例如 MFAAvalonia 的多行日志必须逐行补前缀、MXU 只还原白名单内的<font color>标记而其余 HTML 一律转义。

4.3 如何"录过程"

日志只能反映 Agent 侧的执行情况，画面异常（识别到了错误界面、点击位置偏移、模拟器画面卡死）则必须靠屏幕录制来还原。建议：

• 从复现问题前开始录制，到问题发生后再持续 10～20 秒，方便开发者对齐时间轴；
• 录制时尽量包含 M9A 主界面与模拟器画面同框；
• 若任务异常自动停止，debug/on_error/下已有错误截图，可一并附上。

五、选择 QQ 群上报时的注意事项

如果你选择在 QQ 群上报，官方要求@有问题看群公告，不行@我和群主，这样能确保消息被维护者及时看到。同时注意：

• 群公告可能已经包含了已知问题的临时解法，先看公告再提问；
• 提问时同样需要附上logs/debug材料，不要只发一句"我的不行了"；
• 涉及隐私（账号、设备信息）的内容，建议只在私聊或官方渠道提交。

六、材料提交后：开发者如何用这些日志定位问题

了解开发者侧的分析方式，能帮助你提供更有针对性的材料。开发文档 fix.md 给出了标准的排查流程：

1. 可视化分析：推荐使用 MaaLogAnalyzer 导入debug/maa.log（或logs/下的 MFA 日志），它可以自动识别版本、可视化展示 Pipeline 执行流程、快速定位错误与异常节点、分析节点匹配情况和执行耗时。
2. 手动分析（备用）：在maa.log中搜索Interface Version: [data.version=确认资源版本、MFAA Version/MaaPiCli确认运行方式；任务提前结束搜[ERR]查看错误信息，任务循环则搜reco hit查找异常匹配模式。
3. 问题归类：资源加载问题（如key already exists）、连接问题（如failed to connect）与 pipeline 问题（识别时机、节点流程），分别有不同的修法——pipeline 问题通常需要给节点加post_wait_freezes等待画面稳定，或调整无条件匹配/inverse node 的判断逻辑。

对你而言，这意味着：只要把完整的debug+logs压缩包原样提交，开发者就能从时间戳、版本号、执行链路和错误节点还原出完整现场，比任何口头描述都更高效。

七、上报材料自查清单

提交前请对照检查：

• 已重启电脑、已确认使用的是最新版本
• 已确认不是 FAQ 中可自愈的环境问题
• 已打包 M9A 根目录下的logs与debug两个文件夹
• 已附上问题发生过程的屏幕录制（视情况）
• 材料中已包含问题发生的大致时间点与操作步骤描述
• 选择了 GitHub Issues 或 QQ 群渠道，并按渠道要求完成 @ 或模板填写

把材料准备到位，问题才能真正"一次定位、快速修复"。

• GUI 自动化
• AI 应用