82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 排障指南
|
|
|
|
## 推荐顺序
|
|
|
|
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 页面和成功条件无法确定；
|
|
- 修复需要删除数据、覆盖用户改动或扩大到当前需求之外。
|
|
|
|
整理已经确认的事实、复现方式和可选方案后，再向用户确认。
|