Maaend Issue Log Analysis

MaaEnd Issue Log Analysis

Scope

• 仅用于上游公开仓库 https://github.com/MaaEnd/MaaEnd。
• 输入可以是完整 issue URL，或 #1234 形式的 issue 编号。
• 只分析公开 issue 中可直接访问的附件。
• 如果 issue 没有形如 MaaEnd-logs-*.zip 的日志包，且明确是 bug，则直接停止分析并说明证据不足。

Workflow

1. 规范化输入。

   • #1234 视为 https://github.com/MaaEnd/MaaEnd/issues/1234
   • 如果不是 MaaEnd/MaaEnd，停止并说明此 skill 不适用。

2. 获取 issue 内容。

   • 优先读取 issue 页面正文和评论。
   • 提取这些信息：版本、控制器类型、任务名、预期行为、实际行为、复现步骤、维护者评论。
   • 如果维护者已经给出结论，不要直接照抄；仍要用日志和代码自行验证，再把维护者结论作为补强证据。

3. 提取日志附件链接。

   • 关注 MaaEnd-logs-*.zip。
   • 如果附件名形如 MaaEnd-logs-<...>-partNN.zip（例如 part01、part02），将同一前缀的所有 partNN 视为一个逻辑日志包；按去掉 -partNN.zip 后的前缀分组，先枚举 issue 正文和所有评论里的同组分包链接。
   • 发现分包日志时，不要只取 part01。必须先确认同一组全部可见 part 已被收集；如果 issue 文本或附件列表暗示还有后续 part，但当前只找到部分分包，则继续回到 issue 正文和评论查找。
   • 如果同一个 issue 有多个日志包，先看最新一次复现；如果 issue 在对比不同版本或不同控制器，再补看前面的包。
   • 如果同一个 issue 有多个分包日志组，先选择最新一次复现对应的完整分包组；如果 issue 在对比不同版本或不同控制器，再补看相关的完整分包组。
   • 如果 issue 没有日志包，且明确是 bug，则直接停止分析并说明证据不足。

4. 下载并解压日志包。

   • 二进制 zip 不能用网页抓取工具直接读取，应使用终端下载。
   • 用 curl -L 或等价方式下载到仓库内临时目录，例如 .cache/issue-logs/issue-<number>/。
   • 如果日志包是 partNN 分包，下载前先列出计划下载的 part 清单（如 part01、part02、part03），再逐个下载。
   • 必须把同一逻辑日志包的全部可见 part 下载到本地，并确认每个文件都存在且非空，才能开始解压。
   • 如果只发现 part01 但缺少后续 part，或 issue 文本暗示还有其他分包但附件未收集完整，不得解压；应返回 issue 正文和评论继续查找，仍找不到则先在正文输出提醒，再进行分析。
   • 解压分包时，如果这些 part 是独立 zip，逐个解压到同一输出目录；如果工具识别为分卷压缩包，必须先把全部 part 放在同一目录，再使用支持分卷的解压工具从入口卷解压。
   • 解压后用文件工具读取，不要把整份大日志完整塞进回复。
   • 先列一遍解压目录，不要假定结构固定。日志包可能包含：
     • 多份 mxu-agent-<index>-<pid>.log
     • 多天的 mxu-web-YYYY-MM-DD.log
     • maafw.bak.*.log
     • config/ 目录
     • 没有 on_error/，或只有部分现场图
     • .dmp 崩溃转储文件（如 MaaEnd.dmp、MaaEnd.exe.<pid>.dmp）
   • 如果发现 .dmp 文件，记录其文件名和路径，将在步骤 5 中单独处理。

5. DMP 崩溃转储分析（如有 .dmp 文件则必须执行此步骤）。

   如果在日志包内或 issue 附件中发现了 .dmp 文件，立即读取 .agents/skills/dmp-analysis/SKILL.md 并严格按其流程执行。不要跳过这一步，不要只凭日志文本猜测崩溃原因。

   a. 按照 dmp-analysis/SKILL.md 的完整流程完成崩溃转储分析，包括：- 解析异常类型、崩溃地址、崩溃模块 - 提取 crashing thread 的完整堆栈帧 - 下载对应版本的 PDB 符号并使用 dump_syms + minidump-stackwalk 完成符号化 b. DMP 的进程 PID（通常在文件名中，如 MaaEnd.exe.18188.dmp → PID 18188）必须与 maafw.log 中的 [Px<pid>] 标签交叉验证，确认是同一次崩溃会话。 c. 最终报告中必须包含 ## DMP 崩溃分析 区域（见 Output Format），内容包括：- 异常类型和异常码（如 0xC0000409），以及异常码的含义 - 崩溃模块和偏移 - crashing thread 的全部有效堆栈帧（module+offset 或符号化后的 function+line），不要省略或截断 - 关键模块列表 d. 如果堆栈中涉及 MaaFramework 或 MXU 的帧且已完成符号化（有函数名+源码行号），必须按对应版本 clone 上游仓库源码，定位到具体代码行，并以远端 GitHub blob 行号链接（尖括号包裹）的形式贴出。clone 命令参考：- 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 e. 如果符号化失败或无法下载 PDB，在报告中明确说明，但仍必须输出 module+offset 级别的堆栈。

6. 建立时间线。

   • 先从 issue 文本判断“用户觉得出问题的时刻”。
   • 再把 mxu-web-*、mxu-tauri.log、go-service.log、maafw.log、mxu-agent*.log 串成一条时间线。
   • 先用 mxu-tauri.log 或 maafw.log 找本次提交的 task_id，因为一个日志包里经常混有很多历史运行。
   • 如果有 on_error/ 截图，用它校验当时实际停留画面；如果没有，要检查是否是未触发 on_error，还是日志导出因体积限制把图片截断了。

7. 回溯到代码和文档。

   • 任务入口、节点名、控制器限制先看 MaaEnd 仓库。
   • Pipeline 运行语义不确定时查 MaaFramework 文档。
   • MXU 行为或日志分层不确定时，先查 MXU README / 文档；只有文档不足或证据已指向实现层时才看源码。
   • 输出给用户时，如果提到任务入口、任务说明、选项名、提示文案，先到 assets/locales/interface/zh_cn.json 查中文文案，不要直接把 task id / option id 当成最终展示文本。

8. 只有在满足条件时才下钻第三方仓库。

   • 先用 issue、日志、MaaEnd 仓库和 MaaFramework 文档做初步归因。
   • 如果怀疑问题在 MXU、MaaFramework 或 binding 实现层，且现有证据不足以确认，再按需查看对应上游仓库源码。
   • 常见对应关系：
     • MXU：https://github.com/MistEO/MXU，前端配置、Tauri 后端编排、实例/任务/agent 生命周期、mxu-tauri.log / mxu-web-*
     • MaaFramework：https://github.com/MaaXYZ/MaaFramework，Pipeline 运行时、控制器、资源加载、任务调度、maafw.log
     • maa-framework-rs：https://github.com/MaaXYZ/maa-framework-rs，Rust binding / FFI / maa_ffi 回调桥接
     • maa-framework-go：https://github.com/MaaXYZ/maa-framework-go，Go binding / Go 与 MaaFramework 的桥接
   • 只看真正相关的仓库；本地没有时再 clone 到临时目录，例如 .cache/upstream-src/<repo>/。

Log Map

maafw.log

• 模块归属：MaaFramework 核心运行时。
• 主要内容：资源加载、控制器连接、任务启动、节点识别、动作执行、超时、回调细节、C++ 源文件和函数名。
• 最适合看：
  • Pipeline 是否按预期推进
  • next / on_error 是否命中
  • 识别算法细节（模板分数、OCR 结果、动作成功失败）
  • 控制器、截图、资源加载层面的异常
• 这是分析 Pipeline/识别/动作问题时的主证据之一。

maafw.bak.*.log

• 模块归属：MaaFramework 旧滚动日志。
• 主要内容：和 maafw.log 同类，但通常是更早一批运行。
• 最适合看：
  • 当前 maafw.log 不够长，复现发生在更早时间
  • 用户在 issue 里对比“前一次失败 / 后一次成功”
• 不要把 maafw.bak.*.log 里的旧结论误判成最新一次复现。

go-service.log

• 模块归属：agent/go-service。
• 主要内容：Go 侧结构化日志，包含 agent 启动、注册组件、HDR 检查、分辨率检查、自定义识别器/动作/业务扩展日志。
• 最适合看：
  • Go 自定义逻辑是否触发
  • 环境检查是否报错或预警
  • 哪个 Go 包在输出异常
• 对 Go 扩展逻辑问题，这是主证据。

mxu-tauri.log

• 模块归属：MXU 的 Tauri/Rust 后端。
• 主要内容：实例创建、控制器连接、资源加载、任务开始/停止、agent 生命周期、maa_ffi 回调、后端命令调用。
• 最适合看：
  • MXU 是否正确把 UI 操作转成 MaaFramework/Agent 调用
  • 任务有没有被用户手动停止
  • agent 是否成功启动、断开、退出
  • 回调层是否出现重复循环或状态错乱
• 对 UI 编排、实例状态、agent 生命周期问题，这是主证据。

mxu-web-YYYY-MM-DD.log

• 模块归属：MXU 的 React/TypeScript 前端。
• 主要内容：interface.json 加载、配置读写、任务列表解析、控制器选择、启动参数、高层 UI 流程日志。
• 最适合看：
  • UI 是否正确加载项目配置
  • 用户点击后前端提交了什么任务和配置
  • 配置持久化或界面状态问题
• 注意：
  • 日志包里可能有多天前端日志，要优先看 issue 当天、复现前后的日期。
• 对“界面选项没生效”“前端显示和实际行为不一致”这类问题很有用。

mxu-agent*.log

• 模块归属：MXU 捕获到的 agent 子进程标准输出/标准错误。
• 主要内容：子进程控制台输出、MaaFramework 输出到 stdout 的内容、以及面向 MXU 运行日志面板的 HTML / 纯文本消息。
• 最适合看：
  • 用户在 MXU 运行日志面板里实际看到了什么
  • 子进程 stdout/stderr 有没有明显报错
  • 自定义逻辑是否打印了辅助信息
• 注意：
  • 新版日志包里可能不是单个 mxu-agent.log，而是多份 mxu-agent-<index>-<pid>.log。
  • 要结合 issue 时间、agent 启动时间、mxu-tauri.log 中的实例/agent 生命周期来判断哪一份是本次复现。
• 注意：它很有用，但不是最权威的根因日志。涉及具体运行细节时，优先以 maafw.log 和 go-service.log 为准。

config/*

• 模块归属：MXU 配置快照。
• 常见文件：
  • config/mxu-MaaEnd.json
  • config/maa_option.json
• 最适合看：
  • 实际启用了哪些任务和选项
  • 是否开启 save_on_error
  • 用户 issue 中说的配置，是否真和本次日志一致
• 当“用户口述的任务配置”和日志行为对不上时，这一层很关键。

on_error/

• 模块归属：MaaFramework 错误现场截图。
• 主要内容：任务出错或进入 on_error 时保存的现场图。
• 最适合看：
  • 实际停留界面
  • 模板/OCR 是否根本识别错了画面
  • 是不是被弹窗、加载态、遮罩、分辨率、HDR 等环境因素干扰
• 当日志和 issue 文字描述冲突时，优先相信现场截图。
• 但要注意：
  • 没有 on_error/ 不一定代表没出错，也可能是本次没有走到 on_error
  • 也可能是导出日志时图片被体积限制截断了，需要去 mxu-tauri.log 或同层日志里找“图片已截断”之类提示