kirl/7maHelper
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
7maHelper/README.md
T
kirl dda86fbcc4
Android CI / Build APK (push) Has been cancelled
Details
fix: 移除 README 中的硬编码用户路径，改为通用说明
2026-09-01 16:58:47 +08:00

11 KiB
Raw Permalink Blame History

4ma — 7MA 出行用车计时助手

Version License Android

📱 简介

4ma 是一款 Android 无障碍服务应用，通过监听微信中的「7MA出行」小程序用车界面，自动开始/结束计时，并在 15/18/30 分钟提醒用户，帮助用户及时完成还车操作。

  • 🎯 自动计时：无需手动记录，监听小程序关键词自动开始/结束
  • 🔔 智能提醒：15/18/30 分钟定时提醒，结束用车一键操作
  • 🔒 完全离线：无网络权限，不收集任何个人数据
  • 🚀 轻量级：纯 Java 实现，无第三方依赖（除 ML Kit 离线 OCR）
  • 📴 后台守护：开启后自动恢复，即使重启手机也保持运行

✨ 核心特性

1. 事件驱动计时

  • 监听无障碍事件树检测用车界面关键词：我要还车 / 预计费用 / 助力车编号 → 开始计时
  • 检测到 还车成功 → 自动结束计时

2. OCR 兜底方案

  • 微信 WebView 无障碍树不稳定时，自动截图 + 本地 ML Kit 中文离线 OCR 识别
  • 全程不联网，无延迟

3. 通知与提醒

  • 计时期间常驻通知栏显示实时用车时长
  • 15/18/30 分钟各弹一次提醒通知
  • 通知上直接按「结束用车」按钮，一键结束计时

4. 后台守护

  • 电池优化白名单 + 自启动配置，防止系统冻结
  • 系统强制终止服务时自动重新绑定（onUnbind 返回 true）

📋 系统要求

项目 要求
Android 版本 8.0（API 26）及以上
权限 无障碍服务 + 通知权限 + 电池优化白名单（推荐）
微信版本 支持小程序的版本（8.0+）
网络 无需网络（完全离线）

🔧 安装方法

方式 1：从 GitHub Release 下载（推荐）

  1. 访问 4ma GitHub Release
  2. 下载最新版本的 app-debug.apk（DEBUG 版本无签名，仅供学习使用）或等待有签名的 app-release.apk
  3. 在 Android 手机上打开，允许安装

方式 2：从源码编译（开发者）

# 克隆仓库
git clone https://github.com/kirltrz/4ma.git
cd 4ma

# 构建 Debug APK（需要 JDK 17 + Android SDK）
./gradlew assembleDebug

# APK 位置：app/build/outputs/apk/debug/app-debug.apk

📖 使用说明

初次启动

  1. 打开应用
    首屏显示权限状态：无障碍服务 / 通知权限 / 电池白名单 / 自启动

  2. 开启无障碍服务（必需）

    • 点击「无障碍服务」行 → 跳转 Android 设置
    • 找到「4ma」→ 开启无障碍服务

  3. 授予通知权限（推荐）

    • 点击「通知权限」行 → 系统权限弹窗 → 允许

  4. 配置电池优化白名单（强烈推荐，防止后台冻结）

    • 点击「电池优化白名单」行
    • Vivo 用户：跳转 Vivo 自启动管理页 → 允许 4ma 后台运行
    • 其他品牌：跳转系统设置 → 电池优化 → 将 4ma 排除

  5. 配置自启动（推荐）

    • 点击「自启动权限」行 → 手机品牌管理页

日常使用

  1. 打开 7MA 出行小程序
    开启用车，确保你的手机无障碍服务已开启

  2. 自动计时开始
    应用检测到用车界面后，自动开始计时，通知栏显示计时时长（如 00:05）

  3. 定时提醒

    • 15 分钟：通知栏提醒「已用车 15 分钟」
    • 18 分钟：通知栏提醒「已用车 18 分钟」
    • 30 分钟：通知栏提醒「已用车 30 分钟」

  4. 结束计时

    • 自动：应用检测到「还车成功」后自动结束，通知栏消失
    • 手动：点击计时通知上的「结束用车」按钮，立即结束

遇到问题

问题 解决方案
未检测到用车 检查无障碍服务是否开启；尝试滑动 7MA 小程序界面，触发无障碍事件
提醒未按时出现 检查通知权限；确保通知不被系统管家禁用
计时突然中断 检查电池优化白名单；国产系统可能强制冻结后台，建议加入白名单
应用容易被杀死 开启自启动权限；某些系统需要在自启动管理中允许

🏗️ 项目结构

7maHelper/
├── app/                                 # Android 应用模块
│   ├── src/main/
│   │   ├── java/com/example/accessibilityhelper/
│   │   │   ├── MyAccessibilityService.java        # 无障碍服务主类
│   │   │   ├── RideSessionManager.java            # 计时单例管理
│   │   │   └── MainActivity.java                  # 主界面
│   │   ├── res/
│   │   │   ├── values/strings.xml                 # 应用字符串与法律声明
│   │   │   ├── drawable/                          # 图标与矢量资源
│   │   │   └── layout/                            # 界面布局
│   │   └── AndroidManifest.xml                    # 权限与组件声明
│   └── build.gradle                               # 应用级构建配置
├── .github/workflows/build.yml          # GitHub Actions CI 配置
├── gradle/wrapper/                      # Gradle Wrapper
├── gradlew / gradlew.bat                # Gradle 启动脚本
├── build.gradle                         # 根级 Gradle 配置
├── settings.gradle                      # Gradle 设置
├── gradle.properties                    # Gradle 属性
├── local.properties                     # 本地 SDK 路径（.gitignore）
└── README.md                            # 本文件

🛠️ 开发环境与构建

环境要求

  • JDK：17+ （AGP 8.7 要求）
  • Android SDK：API 35（compileSdk）、API 26+（minSdk）
  • build-tools：35.0.0+
  • Gradle：8.10.2+

快速编译

Windows（PowerShell）：

# 设置 JDK 和 Android SDK 路径（根据你的实际安装位置修改）
$env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-17.0.20.101-hotspot"
$env:ANDROID_HOME = "path\to\your\android-sdk"  # 替换为你的 SDK 路径

# 或在项目目录下创建 local.properties，内容为：
# sdk.dir=/path/to/android-sdk

# 构建 Debug APK
.\gradlew assembleDebug

# 构建 Release APK（需签名密钥）
.\gradlew assembleRelease

# APK 输出目录
# Debug: app/build/outputs/apk/debug/
# Release: app/build/outputs/apk/release/

Linux / macOS：

export JAVA_HOME=$(java -XshowSettings:properties -version 2>&1 | grep java.home | awk '{print $NF}')
export ANDROID_HOME=/path/to/android-sdk

./gradlew assembleDebug

核心依赖

依赖 版本 用途
ML Kit Text Recognition Chinese 16.0.1 离线中文 OCR 识别
Android Gradle Plugin 8.7.2 Android 构建工具

项目无第三方网络库依赖，完全离线。

⚠️ 关于 APK 体积：本应用约 50-60MB，体积较大主要原因是内置了 ML Kit 的离线中文 OCR 模型（约 20-30MB）。OCR 作为无障碍树不稳定时的兜底方案，无需网络，确保识别可靠性。如需减小体积，可在 build.gradle 中移除 ML Kit 依赖，但这会导致微信 WebView 无法识别的情况下功能受限。

🔐 Release 签名配置（开发者）

生成签名密钥

首次发布 Release APK 需要创建密钥库：

keytool -genkeypair -v -keystore release.keystore \
  -alias 4ma -keyalg RSA -keysize 2048 -validity 10000

输入密钥库口令 (两次确认)，记住此密码。

在 GitHub Actions 中启用签名

  1. 转换密钥为 Base64

    [Convert]::ToBase64String([IO.File]::ReadAllBytes("release.keystore")) | `
  Set-Content -NoNewline "release.keystore.b64"

  2. 配置 GitHub Secrets 访问仓库 Settings → Secrets and variables → Actions，添加以下 4 个密钥：

    Secret 名 值
    KEYSTORE_BASE64 release.keystore.b64 的整个内容
    KEYSTORE_PASSWORD 密钥库口令
    KEY_ALIAS 4ma
    KEY_PASSWORD 密钥口令（与库口令相同）

  3. 配置 Gitea 签名（可选） 参考同样方法把密钥配置到 Gitea 服务器的相应位置。

Release 发布流程

  • GitHub：push tag 时自动触发 CI，构建并发布到 GitHub Releases
  • Gitea：手动从本地上传 APK 到 Release，或配置 CI runner 自动构建

📜 许可证

本项目采用 MIT License。详见 LICENSE 文件。

MIT License 允许你自由地使用、修改、分发本代码，包括商业用途，但必须附带原许可证声明。

📜 安全性与隐私

数据收集

  • ❌ 不收集任何用户数据
  • ❌ 不发送任何请求到服务器
  • ❌ 不联网（无网络权限）

权限说明

权限 用途 是否必需
BIND_ACCESSIBILITY_SERVICE 绑定无障碍服务，读取界面内容 ✅
POST_NOTIFICATIONS 显示计时通知与提醒 ✅
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS 白名单，防止后台冻结 🟡
无网络权限 — ✅ 安全

隐私保证

  • 截图仅在识别瞬间生成，识别完成立即释放，不保存任何图片
  • 无障碍服务只读取界面内容，不修改、不点击
  • 所有识别计算在本地完成，无云端依赖

⚖️ 法律声明

本应用为非官方第三方工具，与「7MA出行」及腾讯微信无任何关联。使用者自行承担风险。

  • 计时准确性：计时与提醒结果仅供参考，实际用车时长与费用以 7MA 出行官方账单为准
  • 免责：因手机系统限制、微信或小程序版本更新、无障碍服务被强制终止等原因导致的检测失败或提醒遗漏，开发者不承担任何责任
  • 使用范围：仅限个人学习与使用，严禁商业用途
  • 合规要求：使用时请遵守中华人民共和国法律法规及 7MA 出行的服务协议

如平台规则变化，请立即停止使用本应用。

📌 开发说明

  • CI/CD：本项目未启用 GitHub Actions CI（GitHub 账户受限），APK 由开发者手工构建并上传发布

🔗 链接

📝 版本历史

v1.0 (2026-09-01)

  • ✨ 首个正式版本
  • 🎯 完整的无障碍服务 + OCR 兜底
  • 🔔 三阶段提醒（15/18/30 分钟）
  • 🔐 离线运行，完全无网络

📧 反馈与支持

如有问题或建议，请在仓库提交 Issue 或 Discussion。

免责声明再次强调：本工具仅供个人学习与使用，使用时自行承担风险。

© 2026 · 非官方应用 · 请合规使用

Reference in new issue View Git Blame Copy Permalink