goauto/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting wiki_revision: a8d4790811aa825c78830cb9c71c6b21723e4584 synchronized_at: 2026-08-28T03:35:05Z

故障排查

排查顺序

1. 先确认现象可复现，并记录设备、App 版本、任务号和规则快照。
2. 从服务端结构化任务日志与错误码入手，不先猜测 Android 端实现。
3. 再看设备心跳、租约与任务状态是否自洽。
4. 最后才进入 Android 侧控件与页面证据排查。
5. 涉及创建订单、权限、凭据或数据删除时立即停止并等待人工确认，不通过重试获取反馈。

以下按现象归类，均已实测确认。

设备显示离线

1. 检查服务器 API 地址和 HTTPS 证书。
2. 检查 Device Token 是否属于该设备且未吊销。
3. 检查 Android 网络、电池限制、自启动和 Portal 进程。
4. 对比服务端 last_seen_at 与最近心跳失败原因。

一加通过 ADB 安装一直不返回

ColorOS 开启“安装增强防护”时，电脑端未知来源 APK 可能不会直接失败，而是让 adb install 一直等待系统确认：

1. 保持手机解锁，查看系统弹出的 Mobile Agent 安装详情页。
2. 点右上角“更多” → “开始深度扫描”。
3. 查看扫描结论后点“继续安装”。
4. 更新同一签名 APK 通常可直接执行；首次安装仍以手机实际提示为准。

不要为方便联调长期关闭系统安装防护，也不要用脚本修改系统安全策略。若只是局域网 Debug 联调，确认安装的是 Debug APK；Release 仍只连接 HTTPS 服务端。

Debug 局域网地址提示 Cleartext HTTP 不允许

• 确认使用包含 src/debug/AndroidManifest.xml 的最新 Debug APK，而不是 Release APK。
• 重新运行 assembleDebug 并覆盖安装；应用诊断页会显示具体错误。
• 正式部署不要放开明文 HTTP，应为服务端配置可信 HTTPS 证书。

无法打开 PDD

1. 检查 Portal 无障碍是否 Enabled 且 Bound。
2. 一加检查后台运行、电池优化和浏览器跳转权限。
3. 检查浏览器“打开拼多多APP”和系统“打开”是否被最新控件树唯一识别。
4. 动作后验证包名和 Activity，不只检查 RPC success。

控件树数据不全

• 在系统设置页与 PDD 页分别对照。
• 一加/ColorOS 若只剩根节点，先重启设备验证 UiAutomation 状态。
• 不通过放宽业务选择器掩盖系统抓树故障。

任务一直运行

1. 检查设备租约是否过期。
2. 检查 Android 本地是否仍持有执行锁。
3. 检查最后心跳、步骤名、任务规则快照和错误码。
4. 网络断开应由超时器把任务置为失败，不能静默回到待领取。

采集结果不完整

保存已有结果并标记 completed_partial；展示缺失维度和值。不要伪造缺失 SKU，也不要自动重试。

规则疑似失效

复制现有规则创建或编辑可用规则，用测试任务验证。删除旧规则只阻止创建新任务，已经创建的任务仍按自身快照执行。

Android 颜色采集诊断

Agent 0.9.13 起，颜色发现阶段在本地 goauto_diagnostics.db 的 agent_diagnostic 表保存一条脱敏 COLOR_DISCOVERY 记录。数据库最多保留最近 50 条、最长 7 天；不得将数据库文件上传工单。

记录只包含颜色行数、各行值数量、可点击颜色数、不可点击候选数、首次颜色点击前的颜色/尺码选中数、是否存在“已选”摘要、横向滑动次数、终止原因和耗时，不保存规格文案、价格、摘要原文、坐标、链接、goods_id、控件树、XML 或截图。

只对 Debug APK 使用以下读取流程：

adb shell run-as cn.ilapage.goauto.agent ls databases
adb exec-out run-as cn.ilapage.goauto.agent cat databases/goauto_diagnostics.db > agent-diagnostics.db
sqlite3 -readonly agent-diagnostics.db "SELECT task_id,reason,color_row_count,color_row_value_counts,clickable_color_count,non_clickable_color_candidate_count,initial_selected_color_count,initial_selected_size_count,selected_summary_present,horizontal_swipe_count,elapsed_ms,agent_version,created_at FROM agent_diagnostic WHERE stage='COLOR_DISCOVERY' ORDER BY id DESC LIMIT 1;"

读取时记录设备、Agent 版本、任务号和规则快照；工单只回写查询得到的脱敏聚合数值。读取完成后删除本地导出副本。正式 APK 若不允许 run-as，停止排查并确认安全的只读诊断出口，不通过放宽应用安全配置或上传完整数据库绕过。