agent_admin/docs/06-troubleshooting.md

排障指南

推荐顺序

1. 复现并记录输入、当前页面、结果码和日志。
2. 判断问题位于获取、解析、设备筛选、入库、调度还是执行阶段。
3. 检查对应模块的直接输入和输出，不先改无关层。
4. 用最小任务或最小测试复现。
5. 修复后运行受影响测试，再执行交付所需的完整验证。

构建与环境

现象	优先检查
根目录找不到 gradlew.bat	使用 .\android\gradlew.bat -p android ...
Java 版本错误	java -version 与 Gradle --version 是否均为 JDK 17
Android SDK 未找到	Android Studio SDK 配置、环境变量或本机 local.properties
依赖无法解析	网络、代理和 google() / mavenCentral() 可用性
APK 路径找不到	是否执行 assembleDebug，检查 android/app/build/outputs/apk/debug/

不要提交包含个人 SDK 绝对路径的 local.properties。

任务没有写入 SQLite

依次检查：

1. 外部列表中是否确实包含该任务；
2. JSON 是否能被 TaskParser 解析；
3. assignedAgentName 是否与本机设备名完全一致，包括大小写和空格；
4. 同步摘要中任务被计为无效、忽略还是保存；
5. 相同 task_id + revision 是否已经存在。

未分配给本机的任务本来就应被忽略，不属于故障。

无障碍服务不可用

• 确认系统设置中已启用 autoagent 服务；
• 重新进入应用检查服务状态；
• 确认 Manifest 和 accessibility_service_config.xml 声明完整；
• 服务被系统停止后重新启用，并记录设备系统版本；
• 若节点根为空，确认目标 App 在前台且页面已稳定显示。

包名或 Activity 不匹配

• 核对任务声明与设备当前前台页面；
• 确认 Activity 名称格式与 ActivityTracker 实际记录一致；
• 排查启动页、弹窗、WebView 或重定向造成的页面切换；
• 不要删除校验来掩盖错误，应修正任务或目标 App 适配逻辑。

找不到控件

• 在超时前页面是否已经加载完成；
• 选择器字段是否与当前节点树一致；
• 目标是否在滚动区域、弹窗或其他窗口；
• 节点是否由 WebView、自绘控件或虚拟节点提供；
• 包名和 Activity 是否先通过检查。

需要等待页面状态时使用有限超时，不引入无限轮询。

控件匹配歧义

TARGET_AMBIGUOUS 表示选择器命中了多个节点。应增加稳定的选择器条件或由目标 App 适配层先确认页面状态，不随意改成选择第一个节点。

点击、输入或返回失败

• 确认节点支持对应无障碍动作且处于可操作状态；
• 点击目标本身不可点击时，检查是否应由驱动定位可点击父节点；
• 输入失败时检查可编辑、焦点、输入法和节点文本能力；
• 返回失败时确认当前窗口和系统全局动作状态；
• 对照 ACTION_FAILED 前的步骤、页面和驱动日志定位。

何时停止并确认

遇到以下情况时，不继续猜测实现：

• 外部 API 契约、认证或领取语义未提供；
• 需求会改变既有任务兼容性或数据库升级策略；
• 目标 App 页面和成功条件无法确定；
• 修复需要删除数据、覆盖用户改动或扩大到当前需求之外。

整理已经确认的事实、复现方式和可选方案后，再向用户确认。