fix(#124): consolidate color discovery diagnostics

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting
-wiki_revision: 6c4352598e1152ed562e998aa641f38415ac71c7
-synchronized_at: 2026-08-19T01:17:13Z
+wiki_revision: a8d4790811aa825c78830cb9c71c6b21723e4584
+synchronized_at: 2026-08-28T03:35:05Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -69,3 +69,19 @@ ColorOS 开启“安装增强防护”时，电脑端未知来源 APK 可能不
 ## 规则疑似失效
 
 复制现有规则创建或编辑可用规则，用测试任务验证。删除旧规则只阻止创建新任务，已经创建的任务仍按自身快照执行。
+
+## Android 颜色采集诊断
+
+Agent 0.9.13 起，颜色发现阶段在本地 `goauto_diagnostics.db` 的 `agent_diagnostic` 表保存一条脱敏 `COLOR_DISCOVERY` 记录。数据库最多保留最近 50 条、最长 7 天；不得将数据库文件上传工单。
+
+记录只包含颜色行数、各行值数量、可点击颜色数、不可点击候选数、首次颜色点击前的颜色/尺码选中数、是否存在“已选”摘要、横向滑动次数、终止原因和耗时，不保存规格文案、价格、摘要原文、坐标、链接、goods_id、控件树、XML 或截图。
+
+只对 Debug APK 使用以下读取流程：
+
+```powershell
+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`，停止排查并确认安全的只读诊断出口，不通过放宽应用安全配置或上传完整数据库绕过。