67 lines
3.6 KiB
Markdown
67 lines
3.6 KiB
Markdown
# 通用动作目录
|
|
|
|
> [返回文档中心](../README.md) · [任务协议](../protocol.md) · [后续工作建议](../roadmap.md)
|
|
|
|
## 动作状态
|
|
|
|
| 动作 | 当前状态 | 文档 |
|
|
|---|---|---|
|
|
| `WAIT` | **[已实现]**，条件扩展为 **[提案]** | [wait.md](wait.md) |
|
|
| `CLICK` | **[部分实现]** | [click.md](click.md) |
|
|
| `INPUT` | **[部分实现]** | [input.md](input.md) |
|
|
| `BACK` | **[已实现]**，单次分发和验证为 **[提案]** | [back.md](back.md) |
|
|
| `EXTRACT_TEXT` | **[已实现]** | [extract.md](extract.md) |
|
|
| `EXTRACT` | **[提案]** | [extract.md](extract.md) |
|
|
| `OPEN` | **[提案]** | [open.md](open.md) |
|
|
| `SCROLL` | **[提案]** | [scroll.md](scroll.md) |
|
|
| `SELECT_OPTION` | **[提案]** | [select-option.md](select-option.md) |
|
|
| `SCREENSHOT` | **[提案]** | [screenshot.md](screenshot.md) |
|
|
| `BRANCH` | **[提案]** | [流程控制](../flow-control.md#4-branch-提案) |
|
|
|
|
当前代码中的动作只有 `WAIT`、`CLICK`、`INPUT`、`BACK` 和 `EXTRACT_TEXT`。
|
|
|
|
## 结果码总表
|
|
|
|
结果码在这里统一定义，动作文档只引用不重复定义。事实来源是 [`ResultCode`](../../../android/app/src/main/java/cn/auto/agent/core/model/TaskModels.kt)。
|
|
|
|
**是否成功只看 `successful`；成功时 `code` 恒为 `OK`。** 不使用 `CLICKED`、`INPUT_SENT`、`OPEN_SENT`、`ALREADY_SELECTED` 这类“成功但不是 OK”的码——否则调用方无法用 `code` 判断成败。需要区分成功的细节时，用独立的 `detail` 字段，不占用 `code`。
|
|
|
|
| code | 状态 | 含义 |
|
|
|---|---|---|
|
|
| `OK` | **[已实现]** | 步骤或任务成功 |
|
|
| `PACKAGE_MISMATCH` | **[已实现]** | 超时内前台包始终与 `packageName` 不符 |
|
|
| `ACTIVITY_MISMATCH` | **[已实现]** | 超时内前台 Activity 始终与 `activityName` 不符 |
|
|
| `TARGET_NOT_FOUND` | **[已实现]** | 超时内 selector 没有匹配到节点 |
|
|
| `TARGET_AMBIGUOUS` | **[已实现]** | selector 匹配多个节点，立即失败 |
|
|
| `ACTION_FAILED` | **[已实现]** | 目标已找到，但动作在超时内始终未成功 |
|
|
| `TARGET_NOT_INTERACTABLE` | **[提案]** | 目标不可见、禁用或不可编辑 |
|
|
| `VERIFICATION_FAILED` | **[提案]** | 动作已分发，但 `after` 或回读验证未通过 |
|
|
| `TASK_INVALID` | **[提案]** | 任务解析失败 |
|
|
| `UNSUPPORTED_ON_DEVICE` | **[提案]** | 当前系统版本或服务配置不支持该动作 |
|
|
|
|
超时不单独设码：超时体现为“超时内没能成功”的那个具体原因（`TARGET_NOT_FOUND`、`ACTION_FAILED` 等），不再为每个动作定义 `WAIT_TIMEOUT`、`SCROLL_TIMEOUT` 这类同义码。
|
|
|
|
新增动作时，先在 `ResultCode` 与本表中登记，再在动作文档引用。
|
|
|
|
## 统一规则
|
|
|
|
每个 UI 动作遵循同一条简单流程：
|
|
|
|
1. 校验动作字段、`packageName` 和可选 `activityName`。
|
|
2. 在步骤 `timeoutMs` 内等待上下文和目标控件。
|
|
3. 默认要求目标唯一；多个目标明确失败。
|
|
4. 执行动作；有副作用的动作默认只分发一次。
|
|
5. 如果任务提供 `after`，重新读取页面并验证结果。
|
|
6. 返回 `success`、`code`、`message`、`output` 和 `elapsedMs`。
|
|
|
|
动作文件只描述动作特有参数。选择器、条件、输出和结果结构分别引用共享文档。
|
|
|
|
## 实现检查清单
|
|
|
|
- 模型包含动作和参数。
|
|
- 解析器校验必要字段、类型和范围。
|
|
- 执行器有总超时，不无限等待。
|
|
- 驱动只提供 Android 基础能力，不包含目标 App 业务规则。
|
|
- 测试覆盖成功、未找到、多个目标、超时和底层失败。
|
|
- 文档状态与 `ActionType` 一致。
|