# 本地开发与验证

## 环境要求

- Windows 10 或兼容开发环境；
- JDK 17；
- Android SDK，包含 API 34 对应平台和构建工具；
- Git；
- PowerShell 7 优先，Windows PowerShell 也可使用。

本机 Android SDK 路径可以由 Android Studio、环境变量或未提交的 `local.properties` 配置，不要把个人绝对路径提交到业务代码或版本库。

## 首次检查

从仓库根目录执行：

```powershell
java -version
.\android\gradlew.bat -p android --version
.\android\gradlew.bat -p android test
```

确认 Gradle 使用 Java 17。如果依赖下载或 SDK 检查失败，先按错误信息补齐环境，再修改代码。

## 常用命令

运行 JVM 单元测试：

```powershell
.\android\gradlew.bat -p android test
```

构建 Debug APK：

```powershell
.\android\gradlew.bat -p android assembleDebug
```

同时验证测试和构建：

```powershell
.\android\gradlew.bat -p android test assembleDebug
```

Debug APK 输出到：

```text
android/app/build/outputs/apk/debug/app-debug.apk
```

也可以先进入 `android/`，再使用 `./gradlew.bat test` 等标准命令。

## 测试范围

当前 JVM 测试位于 `android/app/src/test/java/cn/auto/agent/`：

| 测试 | 覆盖重点 |
|---|---|
| `TaskParserTest` | JSON 解析、字段校验和协议约束 |
| `TaskSynchronizerTest` | 设备名筛选、无效任务统计和入库 |
| `TaskExecutorTest` | 步骤执行、包/Activity、唯一节点和结果 |
| `TaskExecutorTimeoutTest` | 有限超时及相关失败行为 |

只运行某个测试类时，可使用：

```powershell
.\android\gradlew.bat -p android testDebugUnitTest --tests "cn.auto.agent.TaskParserTest"
```

交付涉及核心逻辑的改动前，仍应运行完整 `test`。

## 真机验证

无障碍节点树、输入法、不同系统版本和目标 App 页面无法完全由 JVM 测试覆盖。涉及 `AutoAccessibilityService`、Manifest、无障碍配置或目标 App 适配时，至少记录并验证：

1. 应用可安装和启动；
2. 系统设置中可启用 `autoagent` 无障碍服务；
3. 前台包名和 Activity 能被正确识别；
4. 目标页面的选择器匹配数量符合预期；
5. 点击、输入、返回或提取动作返回正确结果；
6. 超时和失败不会无限等待。

交付时明确写出真机型号、Android 版本、目标 App/页面和实际验证步骤；没有真机验证时也要明确说明。

## 文档验证

文档改动至少检查：

- 相对链接指向存在的文件；
- 命令从所写目录可以执行；
- 版本和能力状态与代码一致；
- 示例 JSON 符合协议，并且不会把规划中动作写成已实现。

不需要为了文档改动重复发布 APK，但涉及路径或构建说明时应实际运行对应命令。