# Android Agent 后续工作建议

> [返回文档中心](README.md) · [动作目录](actions/README.md)

本文档只记录推荐顺序，不是实施门禁。具体做哪一项仍以当前需求为准。

## 当前情况

- 协议 v1 支持 `WAIT`、`CLICK`、`INPUT`、`BACK` 和 `EXTRACT_TEXT`。
- 任务可以按设备名过滤并以 `taskId + revision` 保存到 SQLite。
- `TaskGateway` 还是接口，尚未接入具体服务端。
- 当前没有自动轮询、自动执行、结果提交和取消流程。
- Gradle Wrapper 位于 `android/`，仓库中的构建命令应统一从该目录执行，或以后把 Wrapper 移到仓库根目录。

## 推荐实现顺序

### 1. 修正现有 v1

- ~~将失败原因从单一 `TASK_NOT_MATCHED` 细分~~ 已完成，见[结果码总表](actions/README.md#结果码总表)。
- 未知或不适用字段明确报错，不再静默忽略。**但这一项与“设备上报能力”是一对，必须一起做或都先不做**：严格校验一旦上线，下发端就必须知道设备支持哪些字段，否则新服务端发给旧设备的任务会整体解析失败，且事先无法预判。设备数量可控、能统一升级时，两件都可以推迟。
- 将“等待目标”和“执行动作”分开；`CLICK`、`INPUT`、`BACK` 不因驱动返回 `false` 而重复分发。
- ~~步骤超时必须给出确定结果，不能因轮询唤醒晚于截止时间被记为成功。~~ 已修正，回归测试见 `TaskExecutorTimeoutTest`。
- ~~明确 `optional` 只跳过哪些失败。~~ 已在[任务协议](protocol.md#3-当前执行语义)写明：只跳过超时类失败。
- 查询控件时补充可见、启用和有效边界判断，并正确释放节点。
- 让任务保存返回“新增、重复或失败”，同步统计不再混淆。

### 2. 完善公共能力

- 先扩展统一选择器，再让 WAIT、CLICK、INPUT 和 EXTRACT 共用。
- 增加简单 Condition，供 WAIT、`when` 和动作 `after` 使用。
- 统一简单步骤结果和任务结果。
- 真正接入单任务串行执行；是否持久化执行进度按实际运行需求决定。

### 3. 按需求增加动作

建议顺序：

1. 完善 `WAIT`、`CLICK`、`INPUT` 和 `BACK`。
2. 将 `EXTRACT_TEXT` 扩展为 `EXTRACT`。
3. 实现 `SCROLL`，再实现复合动作 `SELECT_OPTION`。
4. 需要启动或切换 App 时实现 `OPEN`。
5. 有诊断取证需求时实现 `SCREENSHOT`。
6. 出现条件流程需求时实现 `when` 和前向 `BRANCH`。

没有实际需求时，不提前实现复杂正则、多窗口、任意循环、任务租约、能力协商或崩溃恢复。

## 简单开发流程

1. 确认一个动作或公共能力的输入、成功条件、超时和结果码。
2. 同一个改动完成模型、解析、执行、驱动和测试。
3. 运行受影响测试；Android 资源或应用代码变化时再运行 `assembleDebug`。
4. 更新动作状态和示例，说明未做的真机验证。

## 测试建议

- 解析测试：合法字段、缺失字段、未知字段和范围错误。
- 执行测试：成功、超时、目标不存在、目标不唯一和驱动失败。
- 副作用测试：同一步骤不会意外点击、输入或返回多次。
- 真机测试：只覆盖本次涉及的 Android 版本、目标 App 页面和输入法。
- 文档测试：相对链接有效，JSON 示例能解析。

## 已知会推迟的设计

- **设备能力上报**（`schemaVersion`、支持的动作与选择器字段）：只在“多台设备版本不一致 + 服务端自动生成任务”时才有价值。与上面的未知字段严格校验绑定。
- **意外弹窗处理**：权限弹窗、更新提示和插屏是真实失败的主因，但当前 `BRANCH`/`GOTO` 只许向前、`onFailure` 不提供重试，缺少全局处理位置。等第一个真实目标 App 跑起来、拿到实际弹窗形态后再设计（预期形态：任务级 `interrupts`，一组“条件 → 一个消除动作”，带单条与全任务触发次数上限，且不重置步骤 `timeoutMs`）。在那之前若用大量 `optional` 步骤穷举兜底，这些任务将来需要重写；成规模出现时就是该做这件事的信号。

## 等外部信息明确后再设计

- 服务端任务接口与结果提交格式。
- 是否需要不可变 `agentId`。
- 同一任务多 revision 的保留和执行规则。
- 是否需要自动执行、取消、断点恢复或截图上传。