# Android Agent 后续工作建议

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

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

## 当前情况

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

## 推荐实现顺序

### 1. 修正现有 v1

- 未知或不适用字段明确报错，不再静默忽略。
- 将“等待目标”和“执行动作”分开；`CLICK`、`INPUT`、`BACK` 不因驱动返回 `false` 而重复分发。
- 将 `TASK_NOT_MATCHED` 逐步细分为包名不符、Activity 不符、目标未找到和动作失败。
- 明确 `optional` 只跳过哪些失败。
- 查询控件时补充可见、启用和有效边界判断，并正确释放节点。
- 让任务保存返回“新增、重复或失败”，同步统计不再混淆。

### 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 示例能解析。

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

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