Bug 排查
1044 字约 3 分钟
日志文件位置
| 文件 | 说明 |
|---|---|
debug/agent-bootstrap.log | Agent 启动日志 |
maafw.log | MaaFramework 运行日志（项目根目录） |
debug/ | 调试截图目录（识别过程的截图） |
日志分析工具
推荐使用 MaaLogAnalyzer 可视化分析 maafw.log：
- 从 MaaLogAnalyzer 下载并启动
- 打开
maafw.log（项目根目录）或debug/目录 - 按任务/节点过滤，查看每条识别记录的
reco_id、算法、box与细节，并结合debug/截图对照当前画面
此外，MaaEvidenceKit 是面向 MaaFramework 的证据提取与诊断工具包（CLI/SDK）：借助 MaaLogAnalyzer 从日志与项目中提取可定位的运行时与静态证据，输出 JSON/文本，供 Codex、Claude Code 等 AI 助手按需诊断。
开发调试时也可使用 Maa Pipeline Support（VSCode 插件）实时查看识别过程（见 环境搭建）。
问题分类
启动类
Agent 启动失败
现象：Python >=3.13,<3.14 is required
原因：系统 Python 版本不匹配。项目需要 Python 3.13.x。
解决：项目使用 uv 管理 Python 版本，确保已安装 uv 并执行过 uv sync。
Custom 模块未注册
现象：自定义识别或动作执行失败，返回 success: false
常见原因：agent/custom/recognition/__init__.py 的 RECOGNITION_MODULES 中没有添加新的模块名。
解决：添加模块名，例如 RECOGNITION_MODULES = ("farm_resources", "pvp", "stamina", "event_stage")（以 agent/custom/recognition/__init__.py 实际内容为准）。
运行时类
Pipeline 节点卡住
现象：任务在某节点停留不动直到超时
常见原因：
- 截图过时 — 前一个操作后画面还没稳定就截图。改用
post_wait_freezes等待画面静止，或补一个中间识别节点确认目标界面出现后再继续 - ROI 不匹配 — 游戏更新后 UI 位置变了，需更新 ROI
- 模板图片过时 — 游戏 UI 变更后模板图失效，需重新截图
- 节点没有兜底 — 重要的导航节点没加
on_error
JumpBack 节点异常
现象：JumpBack 节点执行后行为不符合预期
原因：JumpBack 节点设置了 next。参考规则：JumpBack 节点不能有 next。
清体力模式循环
现象：体力不足时一直在减次数，减到 1 后仍然继续
常见原因：清体力模式的 ExitStage 和 ExitStageConfirm 的 next 指向了 BattleStage 而不是退出路径。
解决：检查 tasks/farm_resources.json 中清体力模式的 override，确保退出路径正确。
识别类
关卡识别不到
现象：CheckResourceStage 一直返回失败
可能原因：
- 关卡未解锁（文字灰色，OCR 无法识别）— 检查
lock_icon.png模板 - 需要先向左滑动复位（关卡列表偏移了）— 确认
SwipeToBegin节点已执行 custom_recognition_param中的stage_index或resource_type不匹配
体力不足时流程卡住
现象：体力耗尽后任务不退出
原因：no_stamina.png 模板图片不存在或 ROI 不对，导致无法识别体力不足弹窗。
Schema 验证失败
现象：CI 报错 must NOT have unevaluated properties
原因：使用了不被当前 schema 支持的字段。常见如 only_rec 搭配 TemplateMatch 使用。
解决：检查 tools/schema/ 下的 schema 定义，移除不支持的字段。
日志分析
运行日志（maafw.log）中包含每次识别的详细结果：
{
"reco_id": 400000431,
"algorithm": "Custom",
"box": null,
"detail": {"all": [], "best": null},
"name": "PVP.ReadResult"
}box: null— 识别未命中box: [x, y, w, h]— 识别成功，返回区域坐标detail.all— 所有识别结果detail.best— 最佳匹配结果
查看 debug/ 目录下的截图可以确认当前画面是否与预期一致。
验证修复
修复后应验证，而不是直接提交：
- 本地检查：
pnpm check（改动 Python 时同时执行pnpm check:py） - 实机复跑：在 GUI 中勾选对应任务，连续运行 2–3 次，确认问题不再出现
- 回归确认：检查
debug/截图与maafw.log，确认识别结果符合预期、无on_error异常路径触发 - 边界场景：如改动涉及流程分支，额外验证相邻状态（启动页/主页/弹窗等）未被破坏