# 通用动作目录

> [返回文档中心](../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` 一致。