初始化 AutoAgent 代码与文档

2026-09-04 15:42:16 +08:00
commit 6458419730
50 changed files with 2747 additions and 0 deletions
@@ -0,0 +1,37 @@
+# Android Agent 文档中心
+
+本目录集中维护 Android Agent 的任务协议、通用动作和实现建议。根目录的 [`agent_common_action.md`](../agent_common_action.md) 是兼容入口。
+
+## 文档状态
+
+| 标记 | 含义 |
+|---|---|
+| **[已实现]** | 当前协议和代码已支持 |
+| **[部分实现]** | 动作可用，但部分检查或扩展尚未实现 |
+| **[提案]** | 后续设计，当前任务不要使用 |
+
+当前解析器会拒绝未知动作，但仍会忽略部分未知字段。任务编写应只使用“已实现”字段，解析器后续应补充未知字段校验，避免参数被静默忽略。
+
+## 文档目录
+
+| 文档 | 内容 |
+|---|---|
+| [任务协议](protocol.md) | v1 任务结构、步骤字段和当前差距 |
+| [动作目录](actions/README.md) | 动作状态、统一规则和各动作入口 |
+| [统一选择器](selector.md) | 控件定位、状态和候选数量 |
+| [值与输出](values-and-outputs.md) | 输入值、简单引用和步骤输出 |
+| [执行与结果](execution.md) | 执行顺序、结果码、重试和幂等 |
+| [流程控制](flow-control.md) | 条件执行、有限分支和失败处理 |
+| [基本运行约定](security.md) | 包名核对、日志和截图的基本边界 |
+| [后续工作建议](roadmap.md) | 推荐实施顺序和测试方式 |
+| [参考文档](references.md) | Android API 与能力边界 |
+
+## 事实来源
+
+当前能力以 [`ActionType`](../../android/app/src/main/java/cn/auto/agent/core/model/TaskModels.kt)、[`TaskParser`](../../android/app/src/main/java/cn/auto/agent/core/protocol/TaskParser.kt)、[`TaskExecutor`](../../android/app/src/main/java/cn/auto/agent/core/executor/TaskExecutor.kt) 和 `ActionDriver` 的实际代码为准。
+
+- 编写任务：先读任务协议，再读对应动作的“当前行为”。
+- 扩展动作：同时更新模型、解析器、执行器、驱动、测试和文档。
+- 共享语义只在共享文档定义，动作文件直接引用，不重复设计。
+
+文档修改后检查相对链接、JSON 示例和动作状态即可，不设置额外审批或文档门禁。
@@ -0,0 +1,43 @@
+# 通用动作目录
+
+> [返回文档中心](../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`。
+
+## 统一规则
+
+每个 UI 动作遵循同一条简单流程：
+
+1. 校验动作字段、`packageName` 和可选 `activityName`。
+2. 在步骤 `timeoutMs` 内等待上下文和目标控件。
+3. 默认要求目标唯一；多个目标明确失败。
+4. 执行动作；有副作用的动作默认只分发一次。
+5. 如果任务提供 `after`，重新读取页面并验证结果。
+6. 返回 `success`、`code`、`message`、`output` 和 `elapsedMs`。
+
+动作文件只描述动作特有参数。选择器、条件、输出和结果结构分别引用共享文档。
+
+## 实现检查清单
+
+- 模型包含动作和参数。
+- 解析器校验必要字段、类型和范围。
+- 执行器有总超时，不无限等待。
+- 驱动只提供 Android 基础能力，不包含目标 App 业务规则。
+- 测试覆盖成功、未找到、多个目标、超时和底层失败。
+- 文档状态与 `ActionType` 一致。
@@ -0,0 +1,71 @@
+# BACK
+
+> [返回动作目录](README.md) · [任务协议](../protocol.md) · [执行与结果](../execution.md)
+
+## 1. 当前行为 **[已实现]**
+
+~~~json
+{
+  "id": "go-back",
+  "action": "BACK",
+  "packageName": "com.example.target",
+  "timeoutMs": 3000
+}
+~~~
+
+当前 BACK：
+
+- 不需要 selector。
+- 等待前台包和可选 Activity 匹配。
+- 调用 `GLOBAL_ACTION_BACK`。
+- 不验证返回后的页面。
+- 调用返回 `false` 时会在超时内重复调用，这是需要修正的现有问题。
+
+## 2. 简单扩展 **[提案]**
+
+BACK 保持“单次系统返回”，只增加可选前后条件：
+
+~~~json
+{
+  "id": "return-to-list",
+  "action": "BACK",
+  "packageName": "com.example.target",
+  "before": {
+    "state": "VISIBLE",
+    "selector": {
+      "text": "详情页面"
+    }
+  },
+  "after": {
+    "state": "VISIBLE",
+    "selector": {
+      "text": "列表页面"
+    }
+  },
+  "timeoutMs": 5000
+}
+~~~
+
+关闭页面内按钮使用 CLICK；HOME、RECENTS 等其他系统导航不并入 BACK。关闭输入法如果需要，可以在以后增加明确参数，不在当前动作中猜测意图。
+
+## 3. 执行规则
+
+1. 在总超时内满足包名、Activity 和 before。
+2. 最多调用一次 `GLOBAL_ACTION_BACK`。
+3. 调用返回 false 时立即失败。
+4. 丢弃旧页面节点。
+5. 提供 after 时等待新页面满足条件。
+
+after 超时不会自动再次返回。连续返回需要编写多个 BACK 步骤，每一步都可以声明自己的页面条件。
+
+## 4. 结果码
+
+- `BACK_SENT`：系统接受返回请求，未声明 after。
+- `OK`：返回后 after 满足。
+- `PRECONDITION_FAILED`
+- `ACTION_FAILED`
+- `VERIFICATION_FAILED`
+
+## 5. 测试
+
+覆盖前置页面不符、调用成功、调用失败、单次分发、after 成功/超时和多个显式 BACK 步骤。
@@ -0,0 +1,88 @@
+# CLICK
+
+> [返回动作目录](README.md) · [任务协议](../protocol.md) · [统一选择器](../selector.md) · [执行与结果](../execution.md)
+
+## 1. 当前行为 **[部分实现]**
+
+~~~json
+{
+  "id": "click-continue",
+  "action": "CLICK",
+  "packageName": "com.example.target",
+  "selector": {
+    "resourceId": "com.example.target:id/continue_button"
+  },
+  "timeoutMs": 5000
+}
+~~~
+
+当前实现：
+
+- 等待 selector 匹配唯一节点。
+- 节点自身不可点击时，向上查找最近的可点击祖先。
+- 调用 `ACTION_CLICK`。
+- 不检查可见、启用和有效边界。
+- 不验证点击后的页面。
+- 驱动返回 `false` 时会再次查询并重复点击，这是需要修正的现有问题。
+
+## 2. 简单扩展 **[提案]**
+
+~~~json
+{
+  "id": "click-submit",
+  "action": "CLICK",
+  "packageName": "com.example.target",
+  "selector": {
+    "text": {
+      "mode": "CONTAINS_ANY",
+      "values": ["提交", "确认"]
+    },
+    "state": {
+      "visible": true,
+      "enabled": true
+    }
+  },
+  "click": {
+    "type": "SINGLE",
+    "method": "AUTO"
+  },
+  "after": {
+    "state": "VISIBLE",
+    "selector": {
+      "text": "操作完成"
+    }
+  },
+  "timeoutMs": 5000
+}
+~~~
+
+首批只需要：
+
+- `type`：`SINGLE`、`LONG`。
+- `method`：`ACCESSIBILITY`、`CENTER_GESTURE`、`AUTO`。
+- 默认目标必须唯一。
+- `AUTO` 先使用节点动作；只有目标已唯一确认且边界有效时，才使用中心手势兜底。
+
+位置排序、重叠候选归并等复杂策略按实际页面需要再增加。
+
+## 3. 执行规则
+
+1. 等待包名、可选 Activity 和唯一可交互目标。
+2. 解析最近的可点击祖先。
+3. 最多分发一次点击。
+4. 丢弃旧节点。
+5. 提供 after 时读取新页面并验证；未提供时只表示点击请求成功。
+
+## 4. 结果码
+
+- `CLICKED`：点击已分发，未声明 after。
+- `OK`：点击已分发且 after 满足。
+- `TARGET_NOT_FOUND`
+- `TARGET_AMBIGUOUS`
+- `TARGET_NOT_INTERACTABLE`
+- `ACTION_FAILED`
+- `VERIFICATION_FAILED`
+
+## 5. 测试
+
+覆盖节点点击、可点击祖先、多个目标、不可见/禁用、手势兜底、单次分发和 after 成功/超时。
@@ -0,0 +1,96 @@
+# EXTRACT_TEXT 与 EXTRACT
+
+> [返回动作目录](README.md) · [统一选择器](../selector.md) · [值与输出](../values-and-outputs.md)
+
+## 1. EXTRACT_TEXT **[已实现]**
+
+~~~json
+{
+  "id": "read-status",
+  "action": "EXTRACT_TEXT",
+  "packageName": "com.example.target",
+  "selector": {
+    "resourceId": "com.example.target:id/status"
+  },
+  "outputField": "status",
+  "timeoutMs": 3000
+}
+~~~
+
+当前行为：
+
+- 等待 selector 匹配唯一节点。
+- 优先读取 text，空时读取 contentDescription。
+- trim 后为空则继续等待。
+- 把非空文字追加到 `outputField` 对应的字符串列表。
+- 不自动滚动。
+
+## 2. EXTRACT **[提案]**
+
+EXTRACT 用于读取一个或多个节点的明确字段：
+
+~~~json
+{
+  "id": "read-items",
+  "action": "EXTRACT",
+  "packageName": "com.example.target",
+  "selector": {
+    "className": "android.widget.TextView",
+    "state": {
+      "visible": true
+    }
+  },
+  "cardinality": "MANY",
+  "fields": [
+    {
+      "name": "text",
+      "source": "TEXT",
+      "type": "TEXT",
+      "trim": true
+    }
+  ],
+  "outputField": "items",
+  "timeoutMs": 5000
+}
+~~~
+
+首批字段来源：
+
+- `TEXT`
+- `CONTENT_DESCRIPTION`
+- `RESOURCE_ID`
+- `CLASS_NAME`
+- `BOUNDS`
+- `CHECKED`、`SELECTED`、`ENABLED`
+
+首批类型只需 `TEXT`、`INTEGER`、`DECIMAL` 和 `BOOLEAN`。转换失败明确返回错误，不使用默认值代替。
+
+`cardinality` 支持 `ONE` 和 `MANY`。MANY 按控件树顺序输出；排序、去重和复杂对象分组等到实际需求出现时再增加。
+
+## 3. 执行规则
+
+1. 等待包名、Activity 和 selector。
+2. 按 cardinality 校验数量。
+3. 从同一页面快照读取声明字段。
+4. 完成 trim 和简单类型转换。
+5. 所有值都成功后一次性发布 output。
+
+EXTRACT 不点击、不滚动、不读取未声明字段，也不保存完整控件树。
+
+## 4. 结果码
+
+- `OK`
+- `TARGET_NOT_FOUND`
+- `TARGET_AMBIGUOUS`
+- `FIELD_NOT_AVAILABLE`
+- `CONVERSION_FAILED`
+- `OUTPUT_EMPTY`
+- `EXTRACT_TIMEOUT`
+
+## 5. 兼容方式
+
+EXTRACT_TEXT 保留现有字符串列表结果。实现 EXTRACT 后，可以在内部把 EXTRACT_TEXT 转换为 ONE + TEXT 读取，但对外结果结构保持不变。
+
+## 6. 测试
+
+覆盖 text、contentDescription 回退、空文本、多个节点、MANY、字段缺失、类型转换、总超时和不自动滚动。
@@ -0,0 +1,89 @@
+# INPUT
+
+> [返回动作目录](README.md) · [任务协议](../protocol.md) · [统一选择器](../selector.md) · [值与输出](../values-and-outputs.md)
+
+## 1. 当前行为 **[部分实现]**
+
+~~~json
+{
+  "id": "input-keyword",
+  "action": "INPUT",
+  "packageName": "com.example.target",
+  "selector": {
+    "resourceId": "com.example.target:id/input"
+  },
+  "value": "测试内容",
+  "timeoutMs": 5000
+}
+~~~
+
+当前实现对唯一节点调用 `ACTION_SET_TEXT`：
+
+- value 只能是字符串。
+- 不主动请求焦点。
+- 不检查节点是否可编辑。
+- 不回读验证输入结果。
+- 驱动返回 `false` 时会重复输入，这是需要修正的现有问题。
+
+## 2. 简单扩展 **[提案]**
+
+~~~json
+{
+  "id": "input-keyword",
+  "action": "INPUT",
+  "packageName": "com.example.target",
+  "selector": {
+    "resourceId": "com.example.target:id/input",
+    "state": {
+      "visible": true,
+      "enabled": true
+    }
+  },
+  "value": {
+    "source": "TASK_INPUT",
+    "key": "keyword"
+  },
+  "mode": "REPLACE",
+  "verify": "EXACT",
+  "timeoutMs": 5000
+}
+~~~
+
+首批模式：
+
+- `REPLACE`：替换全部文本。
+- `CLEAR`：清空。
+- `APPEND`：在现有文本后追加。
+
+验证：
+
+- `NONE`：只检查系统是否接受输入请求。
+- `EXACT`：回读文本与目标值相同。
+- `NON_EMPTY`：只检查结果非空。
+
+密码节点不回读原文，可使用 NONE 或 NON_EMPTY。复杂格式化、剪贴板和模板输入等到实际需要时再增加。
+
+## 3. 执行规则
+
+1. 等待唯一、可见、启用且可编辑的目标。
+2. 需要时请求焦点。
+3. 计算最终输入文本。
+4. 最多调用一次输入动作。
+5. 按 verify 回读；提供 after 时继续验证页面条件。
+
+`timeoutMs` 包含等待、焦点、输入和验证。
+
+## 4. 结果码
+
+- `INPUT_SENT`：输入已分发但未回读验证。
+- `OK`：输入验证通过。
+- `INPUT_VALUE_INVALID`
+- `TARGET_NOT_FOUND`
+- `TARGET_AMBIGUOUS`
+- `TARGET_NOT_EDITABLE`
+- `ACTION_FAILED`
+- `VERIFICATION_FAILED`
+
+## 5. 测试
+
+覆盖 REPLACE、CLEAR、APPEND、目标不可编辑、输入失败、回读不一致、密码节点和单次分发。WebView、自定义输入框与常用输入法需要真机验证。
@@ -0,0 +1,77 @@
+# OPEN **[提案]**
+
+> [返回动作目录](README.md) · [任务协议](../protocol.md) · [Condition](../flow-control.md#2-condition-提案)
+
+OPEN 用于启动 App、把 App 带到前台或打开 URI。当前代码尚未实现。
+
+## 1. 打开 App
+
+~~~json
+{
+  "id": "open-target",
+  "action": "OPEN",
+  "target": {
+    "type": "APP",
+    "packageName": "com.example.target"
+  },
+  "expectedPackageName": "com.example.target",
+  "after": {
+    "state": "PAGE_STABLE",
+    "stableForMs": 300
+  },
+  "timeoutMs": 10000
+}
+~~~
+
+APP 已经在前台时不重复启动，直接执行 after。否则通过 PackageManager 获取启动 Intent，并从 Service 上下文使用 `FLAG_ACTIVITY_NEW_TASK`。
+
+## 2. 打开 URI
+
+~~~json
+{
+  "id": "open-link",
+  "action": "OPEN",
+  "target": {
+    "type": "URI",
+    "uri": "exampleapp://items/123",
+    "handler": "PACKAGE",
+    "packageName": "com.example.target"
+  },
+  "expectedPackageName": "com.example.target",
+  "timeoutMs": 10000
+}
+~~~
+
+`handler` 首批支持：
+
+- `PACKAGE`：由指定包处理，推荐用于已知深链。
+- `DEFAULT`：使用系统默认处理程序。
+
+如果需要限制 URI 的 scheme、host 或来源页面，可以作为部署配置或任务字段增加，不作为首版通用动作的固定门禁。
+
+## 3. 执行规则
+
+1. 解析目标并确认 App 已安装或 URI 有处理程序。
+2. 目标已经在前台时跳过 Intent 分发。
+3. 最多分发一次 Intent。
+4. 等待 `expectedPackageName` 成为前台。
+5. 提供 after 时继续验证页面条件。
+
+`timeoutMs` 覆盖解析、启动、等待前台和 after。Intent 返回成功不等于目标页面已经准备完成。
+
+OPEN 不写入任何具体 App 的页面文案、深链或恢复流程；这些内容由任务或目标 App 适配层提供。
+
+## 4. 结果码
+
+- `OPEN_ALREADY_FOREGROUND`
+- `OPEN_SENT`：目标包已进入前台，未声明 after。
+- `OK`：目标包和 after 都满足。
+- `TARGET_NOT_INSTALLED`
+- `NO_HANDLER`
+- `ACTION_FAILED`
+- `PACKAGE_MISMATCH`
+- `VERIFICATION_FAILED`
+
+## 5. 测试
+
+单元测试覆盖已在前台、冷启动、无处理程序、单次分发、目标包不符和 after 超时。任务栈恢复、后台启动限制和厂商系统差异需要真机验证。
@@ -0,0 +1,82 @@
+# SCREENSHOT **[提案]**
+
+> [返回动作目录](README.md) · [统一选择器](../selector.md) · [基本运行约定](../security.md)
+
+SCREENSHOT 用于诊断或人工复核。当前代码尚未实现。
+
+## 1. 任务结构
+
+截取控件区域：
+
+~~~json
+{
+  "id": "capture-result",
+  "action": "SCREENSHOT",
+  "packageName": "com.example.target",
+  "scope": {
+    "type": "ELEMENT",
+    "selector": {
+      "resourceId": "com.example.target:id/result"
+    },
+    "paddingDp": 8
+  },
+  "format": "PNG",
+  "outputField": "resultImage",
+  "maxBytes": 5242880,
+  "timeoutMs": 5000
+}
+~~~
+
+首批范围：
+
+- `SCREEN`：当前显示屏。
+- `ELEMENT`：唯一控件边界。
+- `REGION`：显式屏幕比例区域。
+
+首批格式支持 PNG；需要控制体积时再增加 JPEG 和质量参数。
+
+## 2. 执行规则
+
+1. 确认系统版本和无障碍服务具备截图能力。
+2. 等待 packageName 和可选元素 selector。
+3. 调用系统截图接口。
+4. 在内存中按 scope 裁剪。
+5. 编码并检查 `maxBytes`。
+6. 保存到应用私有目录，返回生成的 artifactId。
+
+任务不能提供任意文件系统路径。是否遮盖、上传或定期清理按实际部署需求增加，不作为首版动作的固定流程。
+
+Android 无障碍截图从 API 30 开始可用；服务配置还需要声明对应能力。API 不支持时返回明确结果。
+
+## 3. 输出
+
+~~~json
+{
+  "output": {
+    "resultImage": {
+      "artifactId": "generated-id",
+      "format": "PNG",
+      "width": 1080,
+      "height": 720,
+      "bytes": 245000
+    }
+  }
+}
+~~~
+
+结果只返回产物标识和基本元数据，不把图片字节放入普通任务日志。
+
+## 4. 结果码
+
+- `OK`
+- `UNSUPPORTED_ON_DEVICE`
+- `TARGET_NOT_FOUND`
+- `TARGET_AMBIGUOUS`
+- `CAPTURE_FAILED`
+- `CROP_INVALID`
+- `IMAGE_TOO_LARGE`
+- `STORE_FAILED`
+
+## 5. 测试
+
+单元测试覆盖 scope 校验、裁剪、大小限制和输出元数据。系统回调、不同 API、屏幕方向、FLAG_SECURE 和厂商差异需要真机验证。
@@ -0,0 +1,78 @@
+# SCROLL **[提案]**
+
+> [返回动作目录](README.md) · [统一选择器](../selector.md) · [执行与结果](../execution.md)
+
+SCROLL 是统一滚动动作。当前代码尚未实现。
+
+## 1. 滚动到目标
+
+~~~json
+{
+  "id": "scroll-to-target",
+  "action": "SCROLL",
+  "packageName": "com.example.target",
+  "mode": "TO_TARGET",
+  "target": {
+    "text": "目标选项"
+  },
+  "container": {
+    "resourceId": "com.example.target:id/list"
+  },
+  "direction": "DOWN",
+  "maxAttempts": 8,
+  "timeoutMs": 10000
+}
+~~~
+
+目标出现且可见时成功；每次滚动后重新读取页面。
+
+## 2. 按方向滚动
+
+~~~json
+{
+  "id": "scroll-down",
+  "action": "SCROLL",
+  "packageName": "com.example.target",
+  "mode": "DIRECTION",
+  "container": {
+    "resourceId": "com.example.target:id/list"
+  },
+  "direction": "DOWN",
+  "amount": "PAGE",
+  "maxAttempts": 1,
+  "timeoutMs": 3000
+}
+~~~
+
+首批字段：
+
+- `mode`：`TO_TARGET`、`DIRECTION`、`TO_EDGE`。
+- `direction`：`UP`、`DOWN`、`LEFT`、`RIGHT`。
+- `amount`：`SMALL`、`PAGE`。
+- `maxAttempts`：有限正整数。
+- `container`：可选；省略时要求页面中只有一个可滚动容器。
+
+## 3. 执行规则
+
+1. 找到唯一、可见且可滚动的容器。
+2. TO_TARGET 先检查目标是否已经可见。
+3. 优先调用节点滚动动作；不支持时可使用容器内手势。
+4. 每次滚动后重新读取容器和目标。
+5. 达到目标、页面边缘、`maxAttempts` 或总超时时停止。
+
+容器内容连续两次不变可以视为到达边缘。滚动次数和持续时间始终受步骤 `timeoutMs` 限制。
+
+## 4. 结果码
+
+- `OK`
+- `SCROLL_SENT`：方向滚动成功。
+- `TARGET_NOT_FOUND`
+- `CONTAINER_NOT_FOUND`
+- `CONTAINER_AMBIGUOUS`
+- `EDGE_REACHED`
+- `ACTION_FAILED`
+- `SCROLL_TIMEOUT`
+
+## 5. 测试
+
+覆盖目标已可见、滚动后出现、唯一容器、多个容器、边缘检测、最大次数、总超时和节点动作/手势两种实现。真实 RecyclerView、WebView 和横向列表需要真机验证。
@@ -0,0 +1,63 @@
+# SELECT_OPTION **[提案]**
+
+> [返回动作目录](README.md) · [统一选择器](../selector.md) · [SCROLL](scroll.md) · [CLICK](click.md)
+
+SELECT_OPTION 是“查找选项、必要时滚动、点击并验证选中”的复合动作。当前代码尚未实现。
+
+## 1. 任务结构
+
+~~~json
+{
+  "id": "select-value",
+  "action": "SELECT_OPTION",
+  "packageName": "com.example.target",
+  "target": {
+    "text": {
+      "mode": "EXACT",
+      "value": "选项 A"
+    }
+  },
+  "container": {
+    "resourceId": "com.example.target:id/options"
+  },
+  "search": {
+    "direction": "DOWN",
+    "maxAttempts": 6
+  },
+  "selectedWhen": {
+    "state": "SELECTED",
+    "selector": {
+      "text": "选项 A"
+    }
+  },
+  "timeoutMs": 10000
+}
+~~~
+
+`target` 可以直接使用 selector，也可以在值引用实现后使用任务输入生成文字条件。
+
+## 2. 执行规则
+
+1. 先检查 selectedWhen；已经选中时直接成功。
+2. 在当前容器中查找唯一目标。
+3. 未找到且配置 search 时，按 SCROLL 规则有限滚动。
+4. 找到后按 CLICK 规则最多点击一次。
+5. 重新读取页面并验证 selectedWhen。
+6. 达到最大次数、边缘或总超时时停止。
+
+没有可观察的选中状态时，不应使用 SELECT_OPTION；改用 CLICK，并由页面 after 验证。
+
+## 3. 结果码
+
+- `ALREADY_SELECTED`
+- `OK`
+- `OPTION_NOT_FOUND`
+- `OPTION_AMBIGUOUS`
+- `CONTAINER_NOT_FOUND`
+- `ACTION_FAILED`
+- `VERIFICATION_FAILED`
+- `SELECT_TIMEOUT`
+
+## 4. 测试
+
+覆盖已选中、当前页找到、滚动后找到、没有目标、多个目标、不可用选项、点击失败、验证失败和边缘停止。
@@ -0,0 +1,80 @@
+# WAIT
+
+> [返回动作目录](README.md) · [任务协议](../protocol.md) · [Condition](../flow-control.md#2-condition-提案) · [统一选择器](../selector.md)
+
+## 1. 当前行为 **[已实现]**
+
+~~~json
+{
+  "id": "wait-ready",
+  "action": "WAIT",
+  "packageName": "com.example.target",
+  "selector": {
+    "text": "准备完成"
+  },
+  "timeoutMs": 5000,
+  "optional": false
+}
+~~~
+
+当前 WAIT：
+
+- 约每 100 毫秒查询一次。
+- selector 匹配一个节点时成功。
+- 没有匹配时等待到超时。
+- 多个匹配时立即返回 `TASK_AMBIGUOUS`。
+- 超时返回 `TASK_NOT_MATCHED`；optional=true 时继续下一步。
+
+## 2. Condition 扩展 **[提案]**
+
+~~~json
+{
+  "id": "wait-result",
+  "action": "WAIT",
+  "packageName": "com.example.target",
+  "condition": {
+    "state": "VISIBLE",
+    "selector": {
+      "text": {
+        "mode": "CONTAINS_ANY",
+        "values": ["操作完成", "处理成功"]
+      }
+    },
+    "cardinality": "ANY"
+  },
+  "pollIntervalMs": 200,
+  "timeoutMs": 10000
+}
+~~~
+
+首批状态：
+
+- `PRESENT`：存在匹配节点。
+- `GONE`：不存在匹配节点。
+- `VISIBLE`、`ENABLED`、`SELECTED`、`CHECKED`：节点满足对应状态。
+- `PAGE_STABLE`：页面结构在指定时间内保持不变。
+
+`cardinality` 支持 `ONE` 和 `ANY`。v1 兼容格式仍保持 ONE，不能改变现有任务语义。
+
+## 3. 执行规则
+
+1. 在总 `timeoutMs` 内等待包名和可选 Activity。
+2. 每轮重新读取当前页面。
+3. 求值 Condition。
+4. 条件满足时成功，否则按 `pollIntervalMs` 继续。
+5. 读取或条件错误立即失败，不无限重试。
+
+`timeoutMs` 是总时间，不因轮询或稳定性判断重新计时。
+
+## 4. 结果码
+
+- `OK`：条件满足。
+- `WAIT_TIMEOUT`：超时未满足。
+- `TARGET_AMBIGUOUS`：要求 ONE 但匹配多个。
+- `CONDITION_ERROR`：条件无法正常求值。
+
+v1 对外仍可映射为现有 `OK`、`TASK_AMBIGUOUS` 和 `TASK_NOT_MATCHED`。
+
+## 5. 测试
+
+覆盖立即满足、等待后满足、超时、多目标、GONE、状态变化、页面稳定和 optional 兼容行为。
@@ -0,0 +1,103 @@
+# 执行与结果
+
+> [返回文档中心](README.md) · [动作目录](actions/README.md) · [任务协议](protocol.md)
+
+## 1. 当前执行流程 **[已实现]**
+
+当前 `TaskExecutor` 按以下方式执行每一步：
+
+1. 计算步骤截止时间。
+2. 等待 `packageName` 和可选 `activityName` 匹配。
+3. BACK 直接调用全局返回；其他动作查询 selector。
+4. 没有目标时继续等待，多个目标立即失败。
+5. 执行动作；成功后进入下一步。
+6. 到达超时时，optional 步骤跳过，其他步骤停止任务。
+
+当前结果：
+
+~~~json
+{
+  "successful": true,
+  "code": "OK",
+  "message": "任务执行完成",
+  "extracted": {
+    "status": ["准备完成"]
+  }
+}
+~~~
+
+当前结果码只有：
+
+| code | 含义 |
+|---|---|
+| `OK` | 任务执行完成 |
+| `TASK_AMBIGUOUS` | selector 匹配多个节点 |
+| `TASK_NOT_MATCHED` | 包名、Activity、目标或动作在超时内未成功 |
+
+## 2. 简单步骤结果 **[提案]**
+
+为了便于排查，可将每一步记录为简单结构：
+
+~~~json
+{
+  "stepId": "click-submit",
+  "action": "CLICK",
+  "success": false,
+  "code": "ACTION_FAILED",
+  "message": "点击未成功",
+  "output": {},
+  "elapsedMs": 1200
+}
+~~~
+
+建议只保留：
+
+- `stepId`、`action`：定位步骤。
+- `success`、`code`：供程序判断。
+- `message`：供排障，不参与流程判断。
+- `output`：动作输出，没有输出时为空对象。
+- `elapsedMs`：步骤耗时。
+
+暂不引入 phase、effect、transition 和独立结果协议版本。以后确实需要断点恢复或复杂流程审计时再扩展。
+
+建议逐步细分以下 code：
+
+- `TASK_INVALID`
+- `PACKAGE_MISMATCH`
+- `ACTIVITY_MISMATCH`
+- `TARGET_NOT_FOUND`
+- `TARGET_AMBIGUOUS`
+- `ACTION_FAILED`
+- `VERIFICATION_FAILED`
+- `UNSUPPORTED_ON_DEVICE`
+
+## 3. 动作执行规则
+
+- `timeoutMs` 是整个步骤的总时间，包括等待和验证。
+- 每轮查询都读取当前页面，不长期保存旧节点。
+- WAIT 和只读提取可以轮询。
+- CLICK、INPUT、BACK、OPEN 等有副作用动作默认只分发一次。
+- 提供 `after` 时，动作后重新读取页面并验证。
+- 动作失败不会自动回到初始页面；需要返回或重新打开时由任务显式增加步骤。
+
+## 4. 并发与幂等
+
+当前 SQLite 以 `taskId + revision` 防止同一版本重复入库，但自动执行尚未实现，`TaskExecutionMutex` 也尚未接入。
+
+简单目标：
+
+- 同一时刻只执行一个任务。
+- 已成功执行的相同 `taskId + revision` 不自动重复。
+- 更高 revision 是否替代旧版本，等调度需求明确后决定。
+- 暂不实现抢占、租约、断点恢复和自动回滚。
+
+## 5. 测试
+
+至少覆盖：
+
+- 每个失败原因得到稳定 code。
+- optional 只跳过约定的失败。
+- 多目标不会执行动作。
+- 有副作用动作在一个步骤内最多调用一次。
+- after 使用动作后的新页面状态。
+- 失败结果仍保留此前已经完成的提取输出。
@@ -0,0 +1,127 @@
+# 任务流程控制
+
+> [返回文档中心](README.md) · [任务协议](protocol.md) · [执行与结果](execution.md)
+
+## 1. 当前状态
+
+协议 v1 只支持线性 `steps` 和 `optional`。`when`、`BRANCH`、`nextStepId` 和 `onFailure` 均为 **[提案]**。
+
+流程控制只在出现实际条件流程时实现，不提前引入循环、脚本表达式或复杂工作流引擎。
+
+## 2. Condition **[提案]**
+
+WAIT、动作 `after`、`when` 和 BRANCH 共用简单 Condition。
+
+节点条件：
+
+~~~json
+{
+  "state": "VISIBLE",
+  "selector": {
+    "text": {
+      "mode": "CONTAINS",
+      "value": "操作完成"
+    }
+  }
+}
+~~~
+
+组合条件：
+
+~~~json
+{
+  "mode": "ALL",
+  "items": [
+    {
+      "type": "PACKAGE_IS",
+      "value": "com.example.target"
+    },
+    {
+      "state": "VISIBLE",
+      "selector": {
+        "resourceId": "com.example.target:id/result"
+      }
+    }
+  ]
+}
+~~~
+
+首批只需要：
+
+- `ALL`、`ANY`。
+- 节点状态：`PRESENT`、`GONE`、`VISIBLE`、`ENABLED`、`SELECTED`、`CHECKED`。
+- 上下文：`PACKAGE_IS`、`ACTIVITY_IS`。
+- 结果：`STEP_SUCCESS_IS`、`STEP_CODE_IS`。
+- 输出比较：`EQ`、`NE`，需要时再增加数值比较。
+
+Condition 返回 `MATCHED`、`NOT_MATCHED` 或 `ERROR`。引用缺失和读取失败属于 ERROR，不能当成条件不成立。
+
+## 3. when **[提案]**
+
+~~~json
+{
+  "id": "click-confirm",
+  "action": "CLICK",
+  "packageName": "com.example.target",
+  "when": {
+    "type": "STEP_SUCCESS_IS",
+    "stepId": "prepare",
+    "value": true
+  },
+  "selector": {
+    "text": "确认"
+  }
+}
+~~~
+
+- MATCHED：执行动作。
+- NOT_MATCHED：跳过步骤。
+- ERROR：步骤失败。
+- when 只判断当前状态，不等待；需要等待时使用 WAIT。
+
+## 4. BRANCH **[提案]**
+
+~~~json
+{
+  "id": "route-result",
+  "action": "BRANCH",
+  "cases": [
+    {
+      "condition": {
+        "state": "VISIBLE",
+        "selector": {
+          "text": "操作完成"
+        }
+      },
+      "targetStepId": "read-result"
+    }
+  ],
+  "defaultStepId": "handle-unknown"
+}
+~~~
+
+BRANCH 按顺序选择第一个匹配项。目标步骤必须存在并位于当前步骤之后，避免循环和无限执行。没有匹配项且没有 default 时返回 `BRANCH_NO_MATCH`。
+
+## 5. onFailure **[提案]**
+
+首版只需要三种处理：
+
+- `STOP`：停止任务，默认值。
+- `CONTINUE`：继续下一步。
+- `GOTO`：跳到后续指定步骤。
+
+~~~json
+{
+  "onFailure": {
+    "codes": ["TARGET_NOT_FOUND"],
+    "action": "GOTO",
+    "targetStepId": "handle-missing"
+  }
+}
+~~~
+
+不提供自动重试动作或整个任务。需要再次尝试时，在任务中写一个明确的后续步骤，并继续受总超时限制。
+
+## 6. 最小校验
+
+解析时确认步骤 id 唯一、跳转目标存在且只向前。跨分支输出和复杂汇合规则等到实际需要时再设计。
@@ -0,0 +1,101 @@
+# 任务协议与设计原则
+
+> [返回文档中心](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 只匹配一个节点；多个节点立即返回 `TASK_AMBIGUOUS`。
+- 普通失败当前统一返回 `TASK_NOT_MATCHED`。
+- 非 optional 步骤失败后停止任务；optional 步骤超时后继续。
+- 当前只搜索 `rootInActiveWindow`。
+
+已知差距：
+
+- 未知字段会被忽略。
+- CLICK、INPUT 和 BACK 在驱动返回 `false` 后可能重复执行。
+- 节点匹配没有统一检查可见、启用和有效边界。
+- 节点生命周期管理不完整。
+- 动作没有统一的 after 验证。
+
+## 4. 设计原则
+
+- 通用协议只描述跨 App 动作，不包含具体 App 页面和业务流程。
+- 选择器只负责找控件，动作负责使用控件。
+- 默认唯一匹配，不自动选择第一个。
+- 所有等待、滚动和重试都有总超时或最大次数。
+- 动作结果使用结构化 code，不依赖 message 文本判断流程。
+- 页面文字、资源 ID 和成功条件保留在任务或目标 App 适配层。
+
+## 5. 后续扩展
+
+后续可以按需求增加：
+
+- `inputs` 和简单值引用。
+- WAIT 的 Condition。
+- 动作的 `after`。
+- `when`、前向 `BRANCH` 和简单 `onFailure`。
+- OPEN、SCROLL、SELECT_OPTION、EXTRACT 和 SCREENSHOT。
+
+新增字段只有在模型、解析器、执行器和测试同时支持后，才把状态改为“已实现”。暂不引入单独的能力协商协议；出现多版本设备同时运行的实际需求时再设计。
@@ -0,0 +1,38 @@
+# 能力边界与参考文档
+
+> [返回文档中心](README.md) · [动作目录](actions/README.md)
+
+## 1. 不迁移的浏览器专属动作
+
+以下能力依赖浏览器 DOM、JavaScript 或 Chrome DevTools Protocol，不适合作为原生 Android Agent 的通用动作：
+
+- CSS 选择器、浏览器 XPath、iframe 和 Shadow DOM 切换。
+- JavaScript Evaluate、修改 DOM 属性、注入脚本。
+- 等待网络空闲、拦截请求、Cookie、下载、上传文件控件。
+- 生成 PDF、浏览器标签页和弹窗事件。
+- Hover、鼠标右键和多次鼠标点击。
+
+若目标 App 内嵌 WebView 且确实需要这些能力，应在独立 WebView 适配器中实现，不能让核心执行器依赖浏览器语义。
+
+
+## 2. 参考文档
+
+Android 侧（规范性）：
+
+- Android AccessibilityService：https://developer.android.com/reference/android/accessibilityservice/AccessibilityService
+- Android AccessibilityService.takeScreenshot：https://developer.android.com/reference/android/accessibilityservice/AccessibilityService#takeScreenshot(int,%20java.util.concurrent.Executor,%20android.accessibilityservice.AccessibilityService.TakeScreenshotCallback)
+- Android AccessibilityServiceInfo 截图能力：https://developer.android.com/reference/android/accessibilityservice/AccessibilityServiceInfo#CAPABILITY_CAN_TAKE_SCREENSHOT
+- Android canTakeScreenshot 属性：https://developer.android.com/reference/android/R.attr#canTakeScreenshot
+- Android AccessibilityNodeInfo：https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo
+- Android Intent 与 FLAG_ACTIVITY_NEW_TASK：https://developer.android.com/reference/android/content/Intent#FLAG_ACTIVITY_NEW_TASK
+- Android PackageManager 启动入口：https://developer.android.com/reference/android/content/pm/PackageManager#getLaunchIntentForPackage(java.lang.String)
+- Android 后台 Activity 启动限制：https://developer.android.com/guide/components/activities/secure-bal
+
+浏览器自动化（仅作动作命名与参数形态的横向参考，语义不适用于本协议，见本文件的[不迁移能力](#1-不迁移的浏览器专属动作)）：
+
+- chromedp 包文档：https://pkg.go.dev/github.com/chromedp/chromedp
+- chromedp 官方仓库：https://github.com/chromedp/chromedp
+- chromedp 官方示例：https://github.com/chromedp/examples
+- Rod 官方包文档：https://pkg.go.dev/github.com/go-rod/rod
+- Rod 官方仓库：https://github.com/go-rod/rod
+- Rod 输入动作说明：https://github.com/go-rod/go-rod.github.io/blob/main/input.md
@@ -0,0 +1,66 @@
+# Android Agent 后续工作建议
+
+> [返回文档中心](README.md) · [动作目录](actions/README.md)
+
+本文档只记录推荐顺序，不是实施门禁。具体做哪一项仍以当前需求为准。
+
+## 当前情况
+
+- 协议 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 的保留和执行规则。
+- 是否需要自动执行、取消、断点恢复或截图上传。
@@ -0,0 +1,29 @@
+# 基本运行约定
+
+> [返回文档中心](README.md) · [动作目录](actions/README.md)
+
+本项目是内部系统，不设置额外的安全审批、操作白名单门禁或文档门禁。以下只保留动作正常运行所需的基本约定。
+
+## 1. 操作上下文
+
+- 每个 UI 步骤在执行前核对任务声明的 `packageName`。
+- 提供 `activityName` 时同时核对，但它只作为辅助信息。
+- 节点来源包与当前前台包不一致时不执行动作。
+- 通用动作不使用 shell、root 或脚本注入。
+
+是否增加额外包名范围、URI 范围或系统页面限制，按具体部署需求决定，不作为当前通用协议的前置条件。
+
+## 2. 日志
+
+- 日志记录任务 id、步骤 id、动作、结果码和耗时。
+- INPUT 原值、完整控件树和截图内容默认不写入日志。
+- message 用于排障，不参与程序分支判断。
+- 需要更细的数据处理规则时，在具体服务端和部署方案明确后补充。
+
+## 3. 截图
+
+SCREENSHOT 如果实现，默认保存到应用私有目录，任务结果返回标识而不是任意文件路径。是否遮盖、上传和定期清理按实际使用场景配置。
+
+## 4. 页面稳定判断
+
+PAGE_STABLE 可以比较页面结构、节点数量和稳定属性；不需要保存完整页面文本。首版只用于等待页面不再变化，不作为长期指纹或审计数据。
@@ -0,0 +1,91 @@
+# 统一选择器
+
+> [返回文档中心](README.md) · [动作目录](actions/README.md)
+
+选择器只负责从当前页面中找出匹配节点，不等待、不点击，也不默认选择第一个。
+
+## 1. 当前字段 **[已实现]**
+
+~~~json
+{
+  "resourceId": "com.example.target:id/continue_button",
+  "text": "继续",
+  "contentDescription": "继续操作",
+  "className": "android.widget.Button",
+  "clickable": true
+}
+~~~
+
+规则：
+
+- 已提供字段按 AND 组合。
+- `resourceId`、`text`、`contentDescription` 和 `className` 精确匹配。
+- `clickable` 匹配节点自身状态。
+- 至少提供一个字段。
+- 当前只遍历 `rootInActiveWindow`。
+
+## 2. 简单扩展 **[提案]**
+
+~~~json
+{
+  "resourceId": "com.example.target:id/continue_button",
+  "text": {
+    "source": "TEXT_OR_DESCRIPTION",
+    "mode": "CONTAINS_ANY",
+    "values": ["继续", "下一步"]
+  },
+  "state": {
+    "visible": true,
+    "enabled": true
+  },
+  "region": {
+    "minXRatio": 0.0,
+    "maxXRatio": 1.0,
+    "minYRatio": 0.5,
+    "maxYRatio": 1.0
+  }
+}
+~~~
+
+首批扩展建议只支持：
+
+- 文字来源：`TEXT`、`CONTENT_DESCRIPTION`、`TEXT_OR_DESCRIPTION`。
+- 文字模式：`EXACT`、`CONTAINS`、`CONTAINS_ANY`。
+- 状态：`visible`、`enabled`、`clickable`、`selected`、`checked`、`focused`、`scrollable`。
+- 区域：屏幕比例矩形，节点中心点落在区域内即匹配。
+
+`visible` 统一定义为 `isVisibleToUser == true`，且屏幕边界非空并与屏幕相交。
+
+正则、祖先/后代关系、逻辑嵌套和多窗口查询等到出现明确场景时再增加。
+
+## 3. 候选数量
+
+不同动作决定如何使用匹配结果：
+
+- WAIT v1 要求恰好一个。
+- CLICK、INPUT 和 BACK 以外的单目标动作默认要求一个。
+- EXTRACT 可以显式声明 `ONE` 或 `MANY`。
+- 多个候选时不默认选第一个。
+
+CLICK 可以把文字节点向上解析为最近的可点击祖先；这是 CLICK 的规则，不改变基础选择器结果。
+
+## 4. 查询接口
+
+建议公共接口保持简单：
+
+~~~kotlin
+fun findAll(
+    root: AccessibilityNodeInfo,
+    selector: NodeSelector,
+): List<UiNodeRef>
+~~~
+
+每次轮询读取新 root。同一轮查询结束后释放不再使用的节点；动作完成后不保留旧节点引用。
+
+## 5. 实现顺序
+
+1. 保留 v1 精确匹配。
+2. 增加可见、启用和边界检查。
+3. 增加 `TEXT_OR_DESCRIPTION` 和 `CONTAINS_ANY`。
+4. 增加屏幕比例区域。
+5. 只有实际任务需要时再扩展复杂选择器。
@@ -0,0 +1,102 @@
+# 值与步骤输出
+
+> [返回文档中心](README.md) · [任务协议](protocol.md)
+
+## 1. 当前行为 **[已实现]**
+
+- INPUT 的 `value` 是步骤内字符串。
+- EXTRACT_TEXT 把文本追加到 `outputField`。
+- 最终结果中的 `extracted` 类型是 `Map<String, List<String>>`。
+- 当前没有任务输入区、跨步骤引用或类型化输出。
+
+## 2. 任务输入 **[提案]**
+
+变化频繁的值可以集中放在任务 `inputs`：
+
+~~~json
+{
+  "inputs": {
+    "keyword": "测试内容",
+    "quantity": 2
+  }
+}
+~~~
+
+首版只支持 `TEXT`、`INTEGER`、`DECIMAL` 和 `BOOLEAN`。手机号、邮编和外部编号等需要保留格式的值使用 TEXT。
+
+## 3. 值引用 **[提案]**
+
+字面量：
+
+~~~json
+{
+  "value": {
+    "source": "LITERAL",
+    "value": "固定内容"
+  }
+}
+~~~
+
+任务输入：
+
+~~~json
+{
+  "value": {
+    "source": "TASK_INPUT",
+    "key": "keyword"
+  }
+}
+~~~
+
+步骤输出：
+
+~~~json
+{
+  "value": {
+    "source": "STEP_OUTPUT",
+    "stepId": "read-code",
+    "field": "code"
+  }
+}
+~~~
+
+首版不提供模板语言或表达式执行。引用不存在时返回 `VALUE_NOT_FOUND`。
+
+## 4. 步骤输出 **[提案]**
+
+~~~json
+{
+  "output": {
+    "code": {
+      "type": "TEXT",
+      "value": "A-100"
+    }
+  }
+}
+~~~
+
+一个步骤可以输出多个命名值，但只有整个步骤成功时输出才生效。后续步骤只能引用已经完成的前置步骤。
+
+复杂对象、列表合并和跨分支数据流等到实际需要时再设计。
+
+## 5. 建议模型
+
+~~~kotlin
+enum class ValueType {
+    TEXT,
+    INTEGER,
+    DECIMAL,
+    BOOLEAN,
+}
+
+data class StepValue(
+    val type: ValueType,
+    val value: Any,
+)
+
+data class StepOutput(
+    val values: Map<String, StepValue>,
+)
+~~~
+
+输入约束先支持必要的长度、数值范围和枚举即可，不提前加入复杂格式系统。
@@ -0,0 +1,33 @@
+# Android Agent 通用动作定义
+
+本文档保留为兼容入口。完整内容已经拆分到 [Android Agent 文档中心](agent/README.md)。
+
+## 当前能力
+
+当前协议 v1 支持：
+
+- `WAIT`
+- `CLICK`
+- `INPUT`
+- `BACK`
+- `EXTRACT_TEXT`
+
+其中 CLICK 和 INPUT 只实现了基础能力，尚无完整可交互检查和动作后验证。动作现状以代码中的 `ActionType`、`TaskParser` 和 `TaskExecutor` 为准。
+
+## 文档入口
+
+- [任务协议](agent/protocol.md)
+- [动作目录](agent/actions/README.md)
+- [统一选择器](agent/selector.md)
+- [值与输出](agent/values-and-outputs.md)
+- [执行与结果](agent/execution.md)
+- [流程控制](agent/flow-control.md)
+- [基本运行约定](agent/security.md)
+- [后续工作建议](agent/roadmap.md)
+- [参考文档](agent/references.md)
+
+## 后续动作
+
+OPEN、SCROLL、SELECT_OPTION、EXTRACT、SCREENSHOT 和 BRANCH 都是提案，当前任务不要使用。是否实现以及实现顺序以实际需求为准。
+
+通用动作保持简单：有限超时、包名核对、默认唯一目标、结构化结果；不在核心协议中加入具体 App 业务流程、审批门禁或未确认的调度机制。