核心程序疑難排解
設備與 ADB
| 現象 | 原因 | 處理 |
|---|---|---|
adb devices 為空 | 模擬器未開調試，或 adb server 未啟動 | 模擬器設定裏開啟 ADB；adb start-server |
設備 offline | adb 版本衝突（多個模擬器自帶不同版本） | 用模擬器自帶的 adb，或統一版本 |
| 多個設備時連錯 | Serial 寫錯 / auto 猜錯 | 手動填 host:port |
| 頻繁掉線 | 模擬器省資源、USB 選擇性掛起 | 關閉模擬器省電，改用 ADB_nc |
| 重新啟動模擬器無效 | 未登記安裝路徑或實例名 | 填寫 EmulatorInfo.name / path |
截圖
| 現象 | 原因 | 處理 |
|---|---|---|
| 全黑 | 模擬器用獨立渲染後端，ADB 截圖拿不到 | 換 DroidCast_raw、nemu_ipc（MuMu）或 ldopengl（雷電） |
| 超時 | 後端卡死 | 換方案；開「檢測不到設備時重新啟動 adb」 |
| 花屏/撕裂 | 編碼或縮放問題 | 關閉「去除圖片色彩抖動」再試 |
| 尺寸不是 1280×720 | 模擬器解像度/DPI 被改 | 改成 1280×720，重新啟動遊戲 |
| 截圖正常但點擊偏移 | 縮放與座標映射不一致 | 恢復預設解像度與 DPI，避免系統縮放 |
識別
| 現象 | 原因 | 處理 |
|---|---|---|
| 找不到按鈕 | 皮膚/裝備遮擋、UI 改版 | 恢復預設外觀；更新核心資源 |
| OCR 讀錯數字 | 字色預處理不匹配、字體縮放 | 確認解像度；換模型版本（OcrModelVersion*） |
| 卡在未知頁面 | 彈出視窗未處理 | 看錯誤截圖；手動關掉彈出視窗後重跑 |
| 識別在真機正常、模擬器異常 | 渲染差異 | 換截圖方案，而不是改模板 |
先看錯誤現場
log/error/<实例>/<时间戳>/ 裏的截圖就是腳本當時看到的畫面。它比你的記憶可靠。
調度
| 現象 | 原因 | 處理 |
|---|---|---|
| 任務完全不跑 | 未啟用、NextRun 在未來、隊列為空 | 檢查 Enable 與時間 |
| 總是先跑某個任務 | 優先級更高且已到期 | 調整自定義優先級或時間 |
| 反覆重新啟動遊戲 | GameStuckError / 頁面無法識別 | 查截圖與伺服器維護狀態 |
| 實例自己停了 | 敏感任務失敗 / ScriptError 3 次 | 看日誌最後 100 行 |
| 卡在同一任務幾小時 | 邏輯死循環，日誌仍在動 | 開運行監護（Watchdog*） |
| 任務延後到明天 | 觸發 TaskRestartLimit | 修復根因，或臨時調大上限 |
| 多實例互相干擾 | 同一 Serial 或同一實例名 | 一實例一模擬器一進程 |
日誌關鍵詞
| 關鍵詞 | 含義 |
|---|---|
连续失败 | 失敗計數上升，可能升級為重新啟動模擬器 |
Restart | 注入重新啟動任務 |
EmulatorOpBusy | 已有啟停操作在跑，本輪跳過 |
ScriptError | 代碼異常 |
RequestHumanTakeover | 無法安全判斷，嘗試自動恢復 |
[服务器检查] | 維護檢測 |
配置
| 現象 | 原因 | 處理 |
|---|---|---|
| 改了沒生效 | 任務執行中，配置在邊界才重載 | 等任務結束或重新啟動實例 |
| 值自動回退 | 被 override.yaml 強制覆蓋 | 查該字段是否用戶可改 |
| 儲存衝突 | 兩個頁面同時編輯 | 刷新後重試 |
| 匯入後缺字段 | 跨版本遷移 | 逐頁檢查關鍵開關 |
| 中文變鍵名 | i18n 缺翻譯 | 更新核心或補翻譯 |
遠程訪問
| 現象 | 原因 | 處理 |
|---|---|---|
| 區域網絡打不開 | 監聽 127.0.0.1 或防火牆 | 改 WebuiHost，放行連接埠 |
固定入口 302 到 /error | 設備離線、租約過期、Tunnel 失效 | 看遠程訪問頁狀態 |
| 一直轉圈 | WebSocket 被中間網絡阻斷 | 換網絡；確認 7844 連接埠 |
| 配對碼過期 | 超過 5 分鐘 | 重新生成 |
| 撤銷後仍能連 | 只在本機移除了入口 | 在主機側撤銷配對 |
| MCP 401 | 未帶密碼或改密碼後未重新啟動 | 帶 Bearer；重新啟動 WebUI |
性能
| 現象 | 原因 | 處理 |
|---|---|---|
| 識別慢 | 截圖方案慢、OCR 用 CPU | 跑性能測試；換方案；調 OCR 設備 |
| CPU 打滿 | 多實例 + 高幀率 | 降併發，錯開任務 |
| 記憶體增長 | 長時間運行、截圖快取 | 開每日重新啟動，限制錯誤現場保留 |
| 磁盤滿 | 日誌/截圖/備份堆積 | 調 RetentionDays、KeepDays |
更新後異常
- 記錄更新前的提交（
git log）。 - 看
frontend/dist是否重建成功。 - 檢查
pip/uv依賴是否同步。 - 回滾代碼後
uv sync --frozen再啟動。
bash
git log --oneline -5
git checkout <上一个可用提交>
uv sync --frozen不要用 git reset --hard 清掉本地修改。
升級疑難排解順序（推薦）
text
1. 截图测试 → 能拿到画面？
2. 手动点一次 → 控制方案有效？
3. 单任务「立即执行」→ 能完成？
4. 开调度 → 能按时触发？
5. 加第二个任务 → 不互相干扰？
6. 加第二个实例 → 资源够？每一步通過後再進下一步，比一次性開滿所有任務更容易定位問題。