104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# 任务协议与设计原则
|
|
|
|
> [返回文档中心](README.md) · [动作目录](actions/README.md) · [后续工作建议](roadmap.md)
|
|
|
|
## 1. 状态约定
|
|
|
|
- **[已实现]**：当前协议 v1 可用。
|
|
- **[部分实现]**：动作存在，但部分检查或扩展未实现。
|
|
- **[提案]**：后续设计，当前任务不要使用。
|
|
|
|
当前解析器会拒绝未知动作，但会忽略部分未知字段。后续应增加字段校验；这属于协议正确性，不需要额外审批流程。
|
|
|
|
## 2. 协议 v1 **[已实现]**
|
|
|
|
~~~json
|
|
{
|
|
"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。
|
|
|
|
新增字段只有在模型、解析器、执行器和测试同时支持后，才把状态改为“已实现”。暂不引入单独的能力协商协议；出现多版本设备同时运行的实际需求时再设计。
|