agent_admin/docs/agent/roadmap.md

Android Agent 后续工作建议

返回文档中心 · 动作目录

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

当前情况

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

推荐实现顺序

1. 修正现有 v1

• 将失败原因从单一 TASK_NOT_MATCHED 细分 已完成，见结果码总表。
• 未知或不适用字段明确报错，不再静默忽略。但这一项与“设备上报能力”是一对，必须一起做或都先不做：严格校验一旦上线，下发端就必须知道设备支持哪些字段，否则新服务端发给旧设备的任务会整体解析失败，且事先无法预判。设备数量可控、能统一升级时，两件都可以推迟。
• 将“等待目标”和“执行动作”分开；CLICK、INPUT、BACK 不因驱动返回 false 而重复分发。
• 步骤超时必须给出确定结果，不能因轮询唤醒晚于截止时间被记为成功。 已修正，回归测试见 TaskExecutorTimeoutTest。
• 明确 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 示例能解析。

已知会推迟的设计

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

等外部信息明确后再设计

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