Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 kirl
|
dda86fbcc4 | ||
|
kirl
|
77313b521c | ||
|
kirl
|
38c6db1e45 |
No files matched your search
@@ -0,0 +1,93 @@
|
||||
# Android CI — 7maHelper (4ma 用车计时助手)
|
||||
#
|
||||
# 触发条件:
|
||||
# - push / pull_request 到 main 或 master
|
||||
# - 手动触发 (Actions 页面的 Run workflow 按钮)
|
||||
#
|
||||
# 任务:
|
||||
# 1. JDK 17 + Android SDK (platforms;android-35, build-tools;35.0.0)
|
||||
# 2. Gradle wrapper 校验 + 依赖缓存 (gradle/actions/setup-gradle)
|
||||
# 3. 构建 Debug / Release APK
|
||||
# 4. 上传 APK 为 Actions artifact
|
||||
|
||||
name: Android CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, master ]
|
||||
pull_request:
|
||||
branches: [ main, master ]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: Build APK
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up JDK 17
|
||||
uses: actions/setup-java@v4
|
||||
with:
|
||||
distribution: temurin
|
||||
java-version: '17'
|
||||
|
||||
- name: Set up Android SDK
|
||||
run: |
|
||||
# GitHub 托管 runner 已预装 Android SDK (ANDROID_HOME 默认已设置)，
|
||||
# 这里只显式安装本项目所需的平台与构建工具，并接受所有许可。
|
||||
yes | sdkmanager --licenses >/dev/null 2>&1 || true
|
||||
sdkmanager "platforms;android-35" "build-tools;35.0.0"
|
||||
|
||||
- name: Set up Gradle
|
||||
uses: gradle/actions/setup-gradle@v4
|
||||
|
||||
- name: Grant execute permission for gradlew
|
||||
run: chmod +x gradlew
|
||||
|
||||
- name: Build with Gradle
|
||||
# local.properties 已被 .gitignore 忽略，CI 上不存在；
|
||||
# AGP 自动使用 ANDROID_HOME 环境变量定位 SDK。
|
||||
run: ./gradlew assembleDebug assembleRelease --no-daemon
|
||||
|
||||
- name: Upload APK artifacts
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: apk
|
||||
path: |
|
||||
app/build/outputs/apk/debug/*.apk
|
||||
app/build/outputs/apk/release/*.apk
|
||||
if-no-files-found: error
|
||||
|
||||
# 可选：对 Release APK 进行正式签名。
|
||||
# 启用方法（在仓库 Settings -> Secrets and variables -> Actions 中配置）:
|
||||
# KEYSTORE_BASE64 - base64 编码的 keystore 文件内容
|
||||
# KEYSTORE_PASSWORD / KEY_ALIAS / KEY_PASSWORD
|
||||
# 未配置时此步骤自动跳过。
|
||||
- name: Sign Release APK (optional)
|
||||
if: env.KEYSTORE_BASE64 != ''
|
||||
env:
|
||||
KEYSTORE_BASE64: ${{ secrets.KEYSTORE_BASE64 }}
|
||||
KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
|
||||
KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
|
||||
KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
|
||||
run: |
|
||||
APK="app/build/outputs/apk/release/app-release-unsigned.apk"
|
||||
if [ -f "$APK" ]; then
|
||||
echo "$KEYSTORE_BASE64" | base64 -d > release.keystore
|
||||
"$ANDROID_HOME/build-tools/35.0.0/apksigner" sign \
|
||||
--ks release.keystore \
|
||||
--ks-pass "pass:${KEYSTORE_PASSWORD}" \
|
||||
--key-pass "pass:${KEY_PASSWORD}" \
|
||||
--ks-key-alias "$KEY_ALIAS" \
|
||||
--out app/build/outputs/apk/release/app-release.apk \
|
||||
"$APK"
|
||||
echo "已签名: app/build/outputs/apk/release/app-release.apk"
|
||||
else
|
||||
echo "未找到 release 未签名 APK，跳过签名"
|
||||
fi
|
||||
@@ -7,6 +7,10 @@ app/build/
|
||||
*.apk
|
||||
local.properties
|
||||
|
||||
# 签名密钥
|
||||
release.keystore
|
||||
release.keystore.b64
|
||||
|
||||
# 自包含的工具链（体积大，若用 git 建议忽略；重装见 SETUP.md）
|
||||
android-sdk/
|
||||
tools/*
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,316 @@
|
||||
# 4ma — 7MA 出行用车计时助手
|
||||
|
||||
  
|
||||
|
||||
## 📱 简介
|
||||
|
||||
**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](https://github.com/kirltrz/4ma/releases)
|
||||
2. 下载最新版本的 `app-debug.apk`（DEBUG 版本无签名，仅供学习使用）或等待有签名的 `app-release.apk`
|
||||
3. 在 Android 手机上打开，允许安装
|
||||
|
||||
### 方式 2：从源码编译（开发者）
|
||||
```bash
|
||||
# 克隆仓库
|
||||
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）：
|
||||
```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：
|
||||
```bash
|
||||
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 需要创建密钥库：
|
||||
|
||||
```bash
|
||||
keytool -genkeypair -v -keystore release.keystore \
|
||||
-alias 4ma -keyalg RSA -keysize 2048 -validity 10000
|
||||
```
|
||||
|
||||
输入密钥库口令 (两次确认)，记住此密码。
|
||||
|
||||
### 在 GitHub Actions 中启用签名
|
||||
|
||||
1. **转换密钥为 Base64**
|
||||
```bash
|
||||
[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](LICENSE) 文件。
|
||||
|
||||
MIT License 允许你自由地使用、修改、分发本代码，包括商业用途，但必须附带原许可证声明。
|
||||
|
||||
---
|
||||
|
||||
## 📜 安全性与隐私
|
||||
|
||||
### 数据收集
|
||||
- ❌ **不收集任何用户数据**
|
||||
- ❌ **不发送任何请求到服务器**
|
||||
- ❌ **不联网**（无网络权限）
|
||||
|
||||
### 权限说明
|
||||
| 权限 | 用途 | 是否必需 |
|
||||
|------|------|--------|
|
||||
| `BIND_ACCESSIBILITY_SERVICE` | 绑定无障碍服务，读取界面内容 | ✅ |
|
||||
| `POST_NOTIFICATIONS` | 显示计时通知与提醒 | ✅ |
|
||||
| `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` | 白名单，防止后台冻结 | 🟡 |
|
||||
| **无网络权限** | — | ✅ 安全 |
|
||||
|
||||
### 隐私保证
|
||||
- 截图仅在识别瞬间生成，**识别完成立即释放**，不保存任何图片
|
||||
- 无障碍服务只**读取**界面内容，不修改、不点击
|
||||
- 所有识别计算在本地完成，无云端依赖
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ 法律声明
|
||||
|
||||
本应用为**非官方第三方工具**，与「7MA出行」及腾讯微信无任何关联。使用者自行承担风险。
|
||||
|
||||
- **计时准确性**：计时与提醒结果**仅供参考**，实际用车时长与费用以 7MA 出行官方账单为准
|
||||
- **免责**：因手机系统限制、微信或小程序版本更新、无障碍服务被强制终止等原因导致的检测失败或提醒遗漏，开发者**不承担任何责任**
|
||||
- **使用范围**：仅限个人学习与使用，严禁商业用途
|
||||
- **合规要求**：使用时请遵守中华人民共和国法律法规及 7MA 出行的服务协议
|
||||
|
||||
**如平台规则变化，请立即停止使用本应用。**
|
||||
|
||||
---
|
||||
|
||||
## 📌 开发说明
|
||||
|
||||
- **CI/CD**：本项目未启用 GitHub Actions CI（GitHub 账户受限），APK 由开发者手工构建并上传发布
|
||||
|
||||
---
|
||||
|
||||
## 🔗 链接
|
||||
|
||||
- **GitHub 仓库**：[https://github.com/kirltrz/4ma](https://github.com/kirltrz/4ma)
|
||||
- **GitHub Release**：[https://github.com/kirltrz/4ma/releases](https://github.com/kirltrz/4ma/releases)
|
||||
|
||||
---
|
||||
|
||||
## 📝 版本历史
|
||||
|
||||
### v1.0 (2026-09-01)
|
||||
- ✨ 首个正式版本
|
||||
- 🎯 完整的无障碍服务 + OCR 兜底
|
||||
- 🔔 三阶段提醒（15/18/30 分钟）
|
||||
- 🔐 离线运行，完全无网络
|
||||
|
||||
---
|
||||
|
||||
## 📧 反馈与支持
|
||||
|
||||
如有问题或建议，请在仓库提交 Issue 或 Discussion。
|
||||
|
||||
**免责声明再次强调**：本工具仅供个人学习与使用，使用时自行承担风险。
|
||||
|
||||
---
|
||||
|
||||
**© 2026 · 非官方应用 · 请合规使用**
|
||||
Reference in new issue
Block a user