初始化 AutoAgent 代码与文档

docs/agent/execution.md

@@ -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 使用动作后的新页面状态。
+- 失败结果仍保留此前已经完成的提取输出。