goauto/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting wiki_revision: 18744477bfd17f396e8c76ec7a2fcc6720acdf6f synchronized_at: 2026-09-11T09:10:00Z

故障排查

排查顺序

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，停止排查并确认安全的只读诊断出口，不通过放宽应用安全配置或上传完整数据库绕过。

Android 采购规格入口本地诊断（#249）

实现绑定 99faf5a，Agent 0.9.67（versionCode 80）。单元测试与 Debug 构建已通过，新增版本真机留存/读取尚待验证；本节不属于上文既有实测结论。

采购执行器启动后，在应用私有 files/purchase_diagnostics/<taskId>_<attemptId>.jsonl 保存白名单结构化入口诊断。元数据包含 taskId、attemptId、deviceId、agentVersion、phase、ruleHash（当前任务规则快照 SHA-256）、timestamp 和 elapsedMs。现有任务接口只有 attemptId，没有 attemptNumber；用 attemptId 对照服务端历史，不推算重试序号。

证据仅包含入口来源枚举、候选数、点击结果/原因枚举、等待轮数、面板结构布尔值/计数，以及受控恢复是否执行及固定拒绝原因。没有商品标题、规格原文、地址、手机号、Cookie、Token、链接、原始控件树或截图。entryWaitMillis 是该等待循环累计的计划等待量；elapsedMs 才是自本次采购执行器诊断起点计量的实际耗时，timestamp 是后台写入时间。

复用现有单线程诊断队列异步写入，写入/排队失败不改变采购结果；不新增点击、滑动、等待或采购门禁。最多保留最近 5 个 attempt 文件、每文件最后 128 条事件，超过 7 天的文件在服务启动或下次写入时清理。异常断电或存储故障仍可能丢失诊断，不能将日志缺失当成动作未执行；不上传 Admin，不增加服务端接口。

仅对允许 run-as 的 Debug APK，在设备已连接且选定准确序列号后只读提取：

adb -s <device-serial> shell run-as cn.ilapage.goauto.agent ls files/purchase_diagnostics
adb -s <device-serial> exec-out run-as cn.ilapage.goauto.agent cat files/purchase_diagnostics/<taskId>_<attemptId>.jsonl

先列出文件，再读取本次任务/attempt 的准确文件名；不得扩大为导出所有应用数据或完整数据库。新版安装前的失败不会补生成日志；需要用户授权后重试才能产生新证据。Release 若禁止 run-as 则停止，不更改权限绕过；首版没有导出界面。该功能用于确定拒绝分支，并不代表已经修复对应采购故障。