feat: 4ma 用车计时助手 v1.0

- 无障碍服务监听7MA出行小程序，匹配关键词自动开始/结束计时 - 事件驱动截图+ML Kit离线中文OCR兜底，解决WebView无障碍树不稳定 - 常驻计时通知(15/18/30分钟提醒)与结束用车按钮 - 浅色主题主界面：权限状态、具体实现、安全/免责/法律声明 - 电池白名单+自启动引导+onUnbind自动重绑守护 - 无网络权限，完全离线运行
2026-09-01 16:19:16 +08:00
commit 2cf3cbad56
@@ -0,0 +1,160 @@
+# 无障碍助手（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`