goauto/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting wiki_revision: fee37efc79b644ecfa3237283dd45f0a09796f44 synchronized_at: 2026-10-08T03:25: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 安装或后端参数变更；发布仍需人工授权。

Android 地址编辑页控件就绪等待（#366，环节②）

实现绑定 7fdfe04658d16a05ebcb016ee964a7263eb74802，位于独立工单分支，未合并 main、未装机或发布；合成测试与 APK 构建结果见 #366 工单，不代表真机采购验收。只修改点击“修改”后等待详细地址输入框就绪的环节；地址列表识别（①）仍缺真实单/多地址列表证据，保存退出（③）、返回与最终复核（④）不改。

• 标题出现不再立即触发输入框缺失失败。在“详细地址”标签的既有同排区域，统计可见 EditText 的 structural 数量（包括空值/禁用）及其 enabled、实际 text 非空且未判为 hint 的子集 ready 数量。只有 structural=1 且 ready=1 才继续，读取的地址与就绪判定来自同一帧；后续 inputFresh 仍重新定位且只尝试一次。
• 原地址只读取同帧实际 text.trim()，不使用 contentDescription 补空。API 26+ 捕获内存 hintText / showingHintText；showingHintText=true 或 text.trim() 等于非空 hintText.trim() 时不就绪，继续等待。全局 label 和其他调用方的语义保持不变，这两个新增元数据不落盘、不上报、不记日志。
• API <26 或应用未正确提供 hint 元数据时，不能完全区分非空 text 是提示还是实际值；仅凭此修复不能保证所有设备/页面的提示文字均被识别，不使用提示词猜测。
• 沿用单轮最多 50 次采样、原 200ms 暂停及点击后的既有暂停。不再叠加标题等待与控件等待，不设置“三次多候选即失败”；采样与解析另有耗时，不能将其表述为严格 10 秒墙钟超时。既有安全异常仍可提前终止。
• 等待超时使用现有错误码：从未观察到详细地址标题为 PURCHASE_ADDRESS_EDIT_TIMEOUT；曾见标题但候选未就绪/不唯一为 PURCHASE_ADDRESS_UPDATE_FAILED。titleSeen 跨帧保留，因此最后一帧空树不会抹掉此前的标题证据。
• 诊断仅含固定 stage=address_editor_ready、reason 分类以及 titleSeen、structural、ready 标量，不含地址、收货人、电话或节点文本。具体原因以实现和测试中的固定分类为准；这不是新增 SQLite 字段或上传接口。
• 收货人/电话不能作为备用目标；区域重叠造成歧义时不输入、不保存。无额外点击、滑动、返回、保存或下单重试，正常单次动作路径保持。
• 此修复不能证明历史失败均因慢加载，也不解决保存地址后返回超时。识别①不能仅凭“不是规格面板＋无提交按钮”推断已进入地址列表：两项都依赖同一个面板解析结果。

支付页返回后核单仍缺少证据（#365）

实现绑定 37714d39b5ac8ff720cfa1d0d2609f9a8af3fbd9（工单分支，未合并、安装或发布）。成功执行既有一次支付页安全返回后，在无订单上下文阶段以固定单调时钟起点观察约30秒；原预算后的新增观察不增加页面动作，待付款分支仍沿用独立读取预算。

• 先确认运行版本是否包含此提交，再区分失败码：持续支付页、空窗口、微信恢复和未授权应用等独立条件可提前结束，并非所有失败都等待30秒。
• 完整订单证据出现就结束；超时保留原订单结果未知语义，不能因为等待更久就把任务改为可重试失败或自动重下单。
• 固定期限从 Back 成功时起算，不是从提交订单或进入核单函数起算，也不会因新样本重置；capture 阻塞不能被该检查中断，待付款分支拥有独立预算。
• 不因本次延长断言历史问题就是加载慢。延长期出现必须点击才能展开的入口仍不会新增点击；页面识别/挽留弹窗等原因需要真实诊断证据另行分析。#364 的失败现场诊断不属于本单实现。