# 无障碍助手（Accessibility Helper）最小开发环境

> 日期：2026-09-01
> 目标：用**不依赖 Android Studio** 的最简命令行环境开发一个申请无障碍权限的辅助小工具。
> 全部工具链均位于本工作区（`c:\Users\Tan\Desktop\7maHelper`），自包含、可复现。

---

## 一、环境总览

| 组件 | 版本 | 是否必需 | 说明 |
|------|------|---------|------|
| JDK | 17.0.20.1 LTS | ✅ | 编译 Java/Kotlin；AGP 8.x 要求 JDK 17+ |
| Android SDK cmdline-tools | latest (11076708) | ✅ | 提供 `sdkmanager` / `avdmanager` |
| platform-tools (adb) | 37.0.1 | ✅ | 设备连接、APK 安装 |
| Android 平台 | android-35 | ✅ | `compileSdk 35` 需要 |
| build-tools | 35.0.0 / 34.0.0 | ✅ | 34 为 AGP 8.7 默认，自动补装 |
| Gradle | 8.10.2 | ✅ | 构建工具（含 Wrapper） |
| Android Gradle Plugin | 8.7.2 | ✅ | 自动下载 |
| Android Studio | — | ❌ | **本方案不使用** |

---

## 二、已安装组件及路径

### 1. JDK 17 (Microsoft OpenJDK)
- **安装方式**：`winget install Microsoft.OpenJDK.17`
- **路径**：`C:\Program Files\Microsoft\jdk-17.0.20.101-hotspot`
- **验证**：`java -version` → `openjdk version "17.0.20.1" 2026-08-18 LTS`

### 2. Android SDK（位于工作区）
- **根目录**：`c:\Users\Tan\Desktop\7maHelper\android-sdk`
- **cmdline-tools**：`android-sdk\cmdline-tools\latest`（含 `bin\sdkmanager.bat`）
- **platform-tools**：`android-sdk\platform-tools\adb.exe`
- **platforms**：`android-sdk\platforms\android-35`
- **build-tools**：`android-sdk\build-tools\35.0.0`、`android-sdk\build-tools\34.0.0`
- **licenses**：`android-sdk\licenses`（已接受全部许可）
- **下载来源**：`https://dl.google.com/android/repository/commandlinetools-win-11076708_latest.zip`

### 3. Gradle 8.10.2（位于工作区）
- **发行版**：`c:\Users\Tan\Desktop\7maHelper\tools\gradle-8.10.2`
- **可执行**：`tools\gradle-8.10.2\bin\gradle.bat`
- **下载来源**：`https://services.gradle.org/distributions/gradle-8.10.2-bin.zip`
- **Wrapper**：项目内有 `gradlew.bat`（首次使用会从其下载源拉取发行版到 `%USERPROFILE%\.gradle\wrapper\dists`）

### 4. 已配置的持久化环境变量（`setx`）
```
JAVA_HOME        = C:\Program Files\Microsoft\jdk-17.0.20.101-hotspot
ANDROID_HOME     = C:\Users\Tan\Desktop\7maHelper\android-sdk
ANDROID_SDK_ROOT = C:\Users\Tan\Desktop\7maHelper\android-sdk
```
- `setx` 只对**新打开的终端**生效；当前会话需手动加载。
- 免重启方式：在项目根目录运行 `.\env.ps1`（推荐）或 `.\env.cmd`。

---

## 三、项目结构

```
7maHelper\
├── SETUP.md                     ← 本文件（环境记录）
├── env.ps1 / env.cmd            ← 会话环境变量脚本
├── build.cmd                    ← 一键构建脚本
├── settings.gradle
├── build.gradle                 ← 声明 AGP 版本 8.7.2
├── gradle.properties            ← jvmargs / androidX
├── local.properties             ← sdk.dir 指向工作区 SDK
├── gradlew / gradlew.bat / gradle\wrapper\   ← Gradle Wrapper
├── android-sdk\                 ← Android SDK（自包含）
├── tools\                       ← Gradle 发行版 & 下载缓存
└── app\
    ├── build.gradle             ← 应用模块（无第三方依赖）
    └── src\main\
        ├── AndroidManifest.xml  ← 声明 MainActivity 与无障碍服务
        ├── java\com\example\accessibilityhelper\
        │   ├── MainActivity.java
        │   └── MyAccessibilityService.java
        └── res\
            ├── layout\activity_main.xml
            ├── values\strings.xml / styles.xml
            └── xml\accessibility_service_config.xml
```

---

## 四、构建与产物

- **构建命令（推荐）**：`.\build.cmd`
  - 注：脚本已改为先 `cd /d "%BASE%"` 再执行 `gradle assembleDebug`，避免 `-p "<路径>"` 因路径结尾反斜杠导致引号被吞、Gradle 把 `assembleDebug` 误并入项目目录的问题。
- **等同命令**：
  ```
  $env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-17.0.20.101-hotspot"
  $env:ANDROID_HOME = "c:\Users\Tan\Desktop\7maHelper\android-sdk"
  c:\Users\Tan\Desktop\7maHelper\tools\gradle-8.10.2\bin\gradle.bat assembleDebug
  ```
- **产物 APK**：`app\build\outputs\apk\debug\app-debug.apk`（约 10.5 KB）

---

## 五、安装到设备 / 调试

ADB 已在 `android-sdk\platform-tools\adb.exe`（或系统已有的 37.0.1）：
```
adb install -r app\build\outputs\apk\debug\app-debug.apk
adb shell am start -n com.example.accessibilityhelper/.MainActivity
```
应用内点击按钮会跳转到系统「无障碍设置」，开启 `MyAccessibilityService` 后即生效。

---

## 六、功能说明（当前示例）

- `MainActivity`：入口，点击按钮打开系统无障碍设置。
- `MyAccessibilityService`：继承 `AccessibilityService`，在 `onAccessibilityEvent` 中可读取窗口内容、模拟点击等辅助操作（示例中为占位）。
- 服务配置 `res/xml/accessibility_service_config.xml`：监听窗口状态/内容变化。

---

## 七、扩展建议（进阶）

- 若需 AndroidX/Compose，可在 `app/build.gradle` 添加依赖并保留 `android.useAndroidX=true`。
- 建议将 `android-sdk\` 与 `tools\` 加入 `.gitignore`，避免提交到版本库。
- 卸载/清理：删除本目录即可（不含系统级安装的 JDK，JDK 卸载需用 winget 或控制面板）。

---

## 八、真机测试记录（2026-09-01）

**设备**：V2403A（Vivo），Android 16（API 36，`getprop ro.build.version.sdk = 16`）
**连接**：`adb devices` → `10AE742Z7C00148 device` ✅

### 测试流程与结果
| 步骤 | 命令 | 结果 |
|------|------|------|
| 1. 安装 APK | `adb install -r app\build\outputs\apk\debug\app-debug.apk` | ✅ Success |
| 2. 启动应用 | `adb shell am start -n com.example.accessibilityhelper/.MainActivity` | ✅ 主界面显示（标题「ASIST - 验证助手」+「打开无障碍设置」按钮） |
| 3. 无障碍设置 | 应用出现在系统「无障碍设置」的已下载应用列表 | ✅ 服务注册成功 |
| 4. 启用服务 | `adb shell settings put secure enabled_accessibility_services "com.example.accessibilityhelper/.MyAccessibilityService"` | ✅ `Enabled services` / `Bound services` 均包含本服务 |
| 5. 事件日志 | `adb logcat -d -s A11yHelper` | ⚠️ 见下方说明 |

### 关键说明：关于事件日志为空 —— 其实是日志级别被过滤
- 最初通过 adb `settings put` 启用服务后，`dumpsys accessibility` 显示服务**已绑定**且**无崩溃**，但 `logcat` 看不到 `A11yHelper` 日志。
- **真正的根因**：该设备默认日志级别为 `log.tag = I`（INFO），会**屏蔽 `Log.d`（DEBUG 级）**。服务其实一直在正常接收事件，只是日志被隐藏了（logcat 缓冲里完全没有 `D` 级条目，`getprop log.tag` 显示 `[I]`）。
- **解决办法（无需重编译）**：为指定标签单独开启 DEBUG 级：
  ```
  adb shell setprop log.tag.A11yHelper D
  ```
  之后 `adb logcat -d -s A11yHelper` 即可看到事件日志。
- 你也可以在代码里把 `Log.d` 改成 `Log.i`（INFO 级，默认就能看到）来规避此问题。
- **已在真机验证到的事件**：`type=32`（TYPE_WINDOW_STATE_CHANGED）、`type=2048`（TYPE_WINDOW_CONTENT_CHANGED），来源包括 `com.android.settings`、`com.bbk.launcher2` 等。
- 注意：Vivo ROM 建议在系统「无障碍设置」里**手动打开开关**（`settings put` 只是进入名单，未必真正分派）。

### 真机验证步骤（已跑通）
1. 打开应用 → 点「打开无障碍设置」；在系统无障碍设置中找到「ASIST - 验证助手」→ 打开开关并确认。
2. `adb shell setprop log.tag.A11yHelper D`（仅影响当前会话，重启失效）。
3. 切换任意 App/页面，`adb logcat -d -s A11yHelper` 即看到事件日志。

### 日志查看速查
- 查看设备默认日志级别：`adb shell getprop log.tag`
- 临时开启 DEBUG：`adb shell setprop log.tag.A11yHelper D`