goauto/docs/06-troubleshooting.md

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

故障排查

排查顺序

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 / #361）

#249 的 JSONL 采购诊断实现位于独立分支（历史绑定 99faf5a），未合并基线 main 64f0e49；不能假定运行该 main 的设备存在 files/purchase_diagnostics。main 已有 goauto_diagnostics.db / agent_diagnostic，本单复用它，不整体合并 #249。

#361 实现绑定 a49dc69，Agent 0.9.68（versionCode 81），当前为工单分支，未合并 main 或发布 Admin。已完成 Debug 构建和单元测试，按用户授权覆盖安装一台设备；未执行真机探测或采购重试，不能视为现场修复验收。

规格探测的入口点击/手势、快速确认恢复、颜色点击，以及原有面板/颜色/尺码发现记录接入既有异步诊断队列。来源 stage 为 SPEC_ENTRY_CLICK / SPEC_ENTRY_GESTURE / QUICK_CONFIRMATION_CLICK / COLOR_CLICK；reason 为点击结果或 SIZE_ADVICE_CLICK_BLOCKED 等固定枚举。只存候选数、可点击布尔、白名单类名和可得的祖先层级，不保存原始 trace、标签、地址、手机号、控件树或截图。

本地 SQLite schema v3 仅追加可空 task_type、task_attempt_id、device_id、phase、rule_snapshot_hash。采购记录绑定 purchase_task.id、服务端 attempt UUID、设备、阶段与规则哈希；现有 attempt 仍是动作内次数，不能当作采购 attempt ID。新采集记录标识 collection；旧记录新增字段为 NULL，不猜测或回填归属。V1/V2 自动升级保留旧数据；旧版 SQLiteOpenHelper 不保证能降级打开 v3，回退前需单独评估，不卸载清数据。

保留边界沿用全库最近 50 条及 7 天（写入时清理），日志可能因容量、断电或存储异常缺失；缺日志不能证明未点击。写入/排队失败不改变执行结果，不新增上传接口。

读取须确认准确设备、Debug APK、task ID 与 attempt UUID。设备具备 sqlite3 且允许 run-as 时可执行下面的只读查询；如缺 sqlite3/run-as，则停止并另行确认诊断读取路径，不放宽权限、不导出业务库。命令尚未在本单设备验证：

adb -s <serial> shell run-as cn.ilapage.goauto.agent sqlite3 -readonly databases/goauto_diagnostics.db "SELECT task_id,task_attempt_id,device_id,phase,rule_snapshot_hash,stage,reason,candidate_count,clickable_ancestor_depth,created_at FROM agent_diagnostic WHERE task_type='purchase' AND task_id=<taskId> AND task_attempt_id='<attemptUUID>' ORDER BY id;"

如果日志出现 SIZE_ADVICE_CLICK_BLOCKED，只能证明保护已触发，不代表正常商品探测成功；正常商品仍必须读到预期颜色尺码。禁止直接重试 live 任务作“仅探测”验证：探测匹配后任务可回 pending 并继续下单。演练按 PDD 商品创建，且可能由档案匹配直接跳过 spec_probe；必须确认实际阶段和覆盖路径，装机与真机测试分别取得授权。

SYB 商品列表查询等待（#355）

实现绑定 a24c206，仅 Web 客户端；2026-10-05 与 #353/#354 合并至 main 1b4f7cd 并配套发布 Server/Web 至现有 167 服务器。已通过本地合成测试及线上只读页面验证：列表请求实际等待预算为 60000ms，原筛选组合超过 10 秒后正常返回。发布记录和回退目标见 #355 工单。

• web/src/api/goauto/syb-products.js 的 listSybProducts 为 GET /api/admin/v1/syb-products 单独设置默认 timeout: 60000，覆盖 SYB 商品页搜索、翻页和修改每页数量。全局请求默认仍为 10000ms，其他页面及详情、AI 匹配、采购、采集、退货操作的原超时不变。
• 保留现有加载、错误提示、取消和旧请求隔离逻辑，不增加自动重试。慢请求在 10～60 秒间完成时不再被原 10 秒客户端预算提前中止；超过 60 秒仍会超时，上游更短的超时也可能先终止请求。
• 此调整不优化后端执行速度。处理阶段筛选当前先加载候选并计算阶段、后分页；不选店铺且采购类型为全部时，候选可能很大。遇到持续慢查询，应另行分析候选预筛选与数据库执行计划，不能据此认为延长前端预算已解决后端性能问题。
• 只需发布包含该提交的 Web 资源即可生效，不要求数据库迁移、Android 安装或后端参数变更；发布仍需人工授权。