# Zzz Od Dev Debug Automation

> 排查运行中的自动化 bug(用户反馈某玩法跑失败/卡住/行为异常)、定位根因前用

- Skill: `onedragon-anything/zzz-od-dev-debug-automation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add onedragon-anything/zzz-od-dev-debug-automation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/onedragon-anything/zzz-od-dev-debug-automation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: onedragon-anything (https://skillmd.com/u/onedragon-anything)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/onedragon-anything/zzz-od-dev-debug-automation

---


# 排查运行中自动化 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 是否复现 / 消失,从而验证假设。