3.7 KiB
3.7 KiB
任务协议与设计原则
1. 状态约定
- [已实现]：当前协议 v1 可用。
- [部分实现]：动作存在，但部分检查或扩展未实现。
- [提案]：后续设计，当前任务不要使用。
当前解析器会拒绝未知动作，但会忽略部分未知字段。后续应增加字段校验；这属于协议正确性，不需要额外审批流程。
2. 协议 v1 [已实现]
{
"schemaVersion": 1,
"taskId": "task-1001",
"revision": 1,
"assignedAgentName": "phone-01",
"steps": [
{
"id": "wait-ready",
"action": "WAIT",
"packageName": "com.example.target",
"selector": {
"text": "准备完成"
},
"timeoutMs": 5000,
"optional": false
}
]
}
任务字段：
| 字段 | 规则 |
|---|---|
schemaVersion |
当前必须为 1 |
taskId |
非空字符串 |
revision |
正整数，默认 1 |
assignedAgentName |
与本机设备名区分大小写、精确匹配 |
steps |
1 至 200 个，按数组顺序执行 |
步骤公共字段：
| 字段 | 规则 |
|---|---|
id |
任务内唯一 |
action |
当前只支持五个已实现动作 |
packageName |
在超时内等待前台包精确匹配 |
activityName |
可选；只作辅助判断 |
selector |
BACK 以外动作必填 |
timeoutMs |
默认 5000，范围 100..30000 毫秒 |
optional |
超时后是否继续下一步 |
动作专属字段：
- INPUT 需要字符串
value。 - EXTRACT_TEXT 需要
outputField。 - BACK 不需要 selector。
- 其他字段见对应动作文档。
3. 当前执行语义
- 步骤线性执行。
- 包名、Activity 或目标控件不匹配时，在
timeoutMs内继续等待。 - 默认要求 selector 只匹配一个节点；多个节点立即返回
TARGET_AMBIGUOUS。 - 失败返回具体原因码：
PACKAGE_MISMATCH、ACTIVITY_MISMATCH、TARGET_NOT_FOUND、TARGET_AMBIGUOUS或ACTION_FAILED。 - 步骤在
timeoutMs内没有成功时给出确定结果：非 optional 步骤停止任务并返回对应的原因码，optional 步骤跳过并继续。 optional只跳过“超时类失败”（上下文不匹配、目标未出现、动作未成功）；TARGET_AMBIGUOUS立即停止任务，不受optional影响。- 当前只搜索
rootInActiveWindow。
已知差距：
- 未知字段会被忽略。
- CLICK、INPUT 和 BACK 在驱动返回
false后可能重复执行。 - 节点匹配没有统一检查可见、启用和有效边界。
- 节点生命周期管理不完整。
- 动作没有统一的 after 验证。
4. 设计原则
- 通用协议只描述跨 App 动作，不包含具体 App 页面和业务流程。
- 选择器只负责找控件，动作负责使用控件。
- 默认唯一匹配，不自动选择第一个。
- 所有等待、滚动和重试都有总超时或最大次数。
- 动作结果使用结构化 code，不依赖 message 文本判断流程。
- 是否成功只看
successful，成功时code恒为OK。成功的细节（点击已分发但未验证、App 已在前台等）放在独立的detail字段，不占用code。 - 页面文字、资源 ID 和成功条件保留在任务或目标 App 适配层。
5. 后续扩展
后续可以按需求增加：
inputs和简单值引用。- WAIT 的 Condition。
- 动作的
after。 when、前向BRANCH和简单onFailure。- OPEN、SCROLL、SELECT_OPTION、EXTRACT 和 SCREENSHOT。
新增字段只有在模型、解析器、执行器和测试同时支持后，才把状态改为“已实现”。暂不引入单独的能力协商协议；出现多版本设备同时运行的实际需求时再设计。