From 77313b521c9d4ade1012914126ba375c18de047d Mon Sep 17 00:00:00 2001
From: kirl <18827922006@163.com>
Date: Tue, 1 Sep 2026 16:55:13 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=EF=BC=8C?=
 =?UTF-8?q?=E6=94=B9=20MIT=20license=EF=BC=8C=E5=88=A0=E9=99=A4=E7=A7=81?=
 =?UTF-8?q?=E6=9C=89=E6=9C=8D=E5=8A=A1=E5=99=A8=E7=9B=B8=E5=85=B3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 改用 MIT License（允许商业使用）
- 删除私有服务器相关信息，仅推荐 GitHub Release
- 添加 OCR 库体积说明
- 说明未启用 CI 是因为 GitHub 账户受限
---
 LICENSE   |  21 ++++
 README.md | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 333 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..14fac91
--- /dev/null
+++ b/LICENSE
@@ -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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e2b18c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,312 @@
+# 4ma — 7MA 出行用车计时助手
+
+![Version](https://img.shields.io/badge/version-1.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Android](https://img.shields.io/badge/android-26%2B-brightgreen)
+
+## 📱 简介
+
+**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 http://git.imtan.cn/kirl/7maHelper.git
+cd 7maHelper
+
+# 构建 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
+$env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-17.0.20.101-hotspot"
+$env:ANDROID_HOME = "c:\Users\Tan\Desktop\7maHelper\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 · 非官方应用 · 请合规使用**