kirl/7maHelper
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
7maHelper/SETUP.md
T
kirl 2cf3cbad56 feat: 4ma 用车计时助手 v1.0 
- 无障碍服务监听7MA出行小程序，匹配关键词自动开始/结束计时
- 事件驱动截图+ML Kit离线中文OCR兜底，解决WebView无障碍树不稳定
- 常驻计时通知(15/18/30分钟提醒)与结束用车按钮
- 浅色主题主界面：权限状态、具体实现、安全/免责/法律声明
- 电池白名单+自启动引导+onUnbind自动重绑守护
- 无网络权限，完全离线运行
2026-09-01 16:19:16 +08:00

161 lines
8.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 无障碍助手（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`
Reference in new issue View Git Blame Copy Permalink