zzz-od-dev-debug-automation

name	zzz-od-dev-debug-automation
description	排查运行中的自动化 bug(用户反馈某玩法跑失败/卡住/行为异常)、定位根因前用

排查运行中自动化 bug(项目专属判据)

基座:superpowers:systematic-debugging(通用 Phase 1-4:读错误 / 复现 / 找根因 / 验证)。本 skill 只叠加项目专属判据 —— 通用流程不管、但本项目排查运行中 bug 会踩的坑。定位到根因后,决定怎么修见 zzz-od-dev-deciding-a-fix。

1. 先分清进程,找对日志

排查"用户反馈某次跑失败"前,先确认日志是哪个进程的(两者文件不同,看错就什么都找不到):

• GUI / 一条龙调度器(用户日常自动跑):项目根 .log/log.txt(TimedRotating,按天轮转成 log.txt.YYYY-MM-DD)。
• MCP server(daemon 拉起,给 mcp__zzz_od__* 用):.debug/zzz_od_mcp/main_server.log。

用户反馈的运行失败几乎都在前者;MCP 工具调用本身的问题才看后者。

run_record(config/<实例>/app_run_record/<app>.yml)的 run_status:0 未运行 / 1 成功 / 2 失败 / 3 运行中,配合 daily_run_times / weekly_run_times 计数判成功与否。⚠️ run_status=3(运行中)有歧义(还在跑 / 中断没复位)→ 交叉验活日志:末条时间还在推进 = 还在跑;停在很久前 = 中断没复位。

2. 定位故障环节(节点级)

• 从日志节点流转(节点 X -> Y 返回状态 Z)看卡在哪 —— 末尾几条流转指向故障节点。
• 数重复记录判「循环 vs 进展」:在日志里数某句反复出现的状态/动作 —— 同一句爆炸增长(例如某条状态出现几千次)= 卡死循环;节点流转在跳转推进 = 还在跑。
• 对照被测 op 代码里 @operation_node 装饰器连成的流转图(每个节点 + @node_from 边),看 bot 落在哪个分支、该分支预期会走到哪。

3. 识别类 bug 专项判据(画面 / OCR)

• 验证用的识别路径 = bot 运行时路径:分析工具(analyze_screen 等)与 bot 运行时的画面识别可能用不同识别参数(裁剪方式等),边界 case 上结论会不一致 —— 分析工具说"匹配"、bot 可能"不匹配"(或反之)。别拿分析工具的结论当作 bot 运行时的结论;要么读 bot 的识别路径代码确认参数,要么用 bot 同参数离线复现。
• OCR / 画面识别 bug 先离线验识别参数:写离线脚本(用采集的截图 / 测试仓 fixture)遍历裁剪方式(裁后 OCR vs 全图 OCR)× 匹配阈值 × 区域宽度三者组合,锁定根因,别凭感觉猜。误匹配类 bug 常是「区域过宽 + 阈值过松 → 部分文字重叠也命中」。

4. 采集证据(让 bot "看见的" 可观察)

• 临时加「识别到画面就截图存盘」:在被测 op「识别到某个画面、正要分发去处理」的位置,临时插一行 —— 把当前游戏画面截图存到磁盘(用 is_debug 开关包起来,只在调试开关打开时才存,免得正常运行时疯狂刷屏)→ 配合日志时间戳,事后能回看 bot 当时实际看到的是哪一帧画面。排查完删掉这行临时代码,别留在主线。
• 离线复现:写个独立脚本,读采集的截图 / 测试仓 fixture,用跟 bot 运行时一样的识别方式(同样参数)跑一遍,改参数看 bug 是否复现 / 消失,从而验证假设。