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

• 未知或不适用字段明确报错，不再静默忽略。
• 将“等待目标”和“执行动作”分开；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 的保留和执行规则。
• 是否需要自动执行、取消、断点恢复或截图上传。