Mooncontroller ｜ 基于 FxxkMoondrop 的二次开发版 ｜ 版本：alpha2.48（versionCode 288） ｜ 许可证：GPL-3.0
本项目是第三方非官方项目，与 水月雨（Moondrop） 及其关联公司 没有任何隶属、合作、赞助或背书关系。 「Moondrop」「水月雨」及产品型号名称为其各自权利人的商标，此处仅作指称性使用。 本项目不包含 Moondrop 官方 App 的任何代码、资源或反编译产物。
AI 辅助开发声明：本项目代码部分使用 AI 辅助生成，已经人工审查与实机验证， 但仍可能存在逻辑错误、安全缺陷或兼容性问题。请仔细核对代码后再使用，风险自负。
逆向声明：本项目借助 Moondrop 官方 App（
com.moondroplab.moondrop.moondrop_app） 所使用的私有蓝牙协议（高通 GAIA、Moondrop 私有9ECA0000）实现耳机控制与 状态读取，仅供学习与研究使用。使用后果自负。
Mooncontroller 是一个 Android 蓝牙耳机助手，用于水月雨（Moondrop）系列耳机： 耳机连接后自动通过 GAIA BLE 协议直连耳机，读取左右耳电量、控制降噪模式与空间音频， 并在状态栏挂一条常驻通知控制中心。
| 上游 FxxkMoondrop | 本分支 Mooncontroller | |
|---|---|---|
| 项目形态 | LSPosed / Xposed 模块 + 独立 App | 纯 App |
| 是否需要 Root / LSPosed | 是（需在 LSPosed 中启用并勾选作用域） | 否，完全不需要 |
| 依赖 Google Play 服务 | 是（Hook GMS 的 BLE 扫描 + 弹窗） | 否 |
| 连接耳机时的交互 | Google Fast Pair 半屏弹窗 | 常驻通知控制中心 |
| 系统蓝牙详情页注入 | 是（Hook com.android.settings） |
否，已移除 |
| 「关于」页 | 有 | 已移除（改由「开源许可」页承担） |
| 包名 | com.fxxkmoondrop.secret |
不变，com.fxxkmoondrop.secret |
包名保持不变，因此两者无法共存安装：签名不同，安装新版时会提示
INSTALL_FAILED_UPDATE_INCOMPATIBLE，需先卸载旧版（本应用allowBackup=false， 卸载会清空应用数据，包括已学习的耳机 LE 地址缓存）。
- 蓝牙监听 + GAIA 直连：BLE GATT 直连耳机，读取左右耳电量，控制降噪
- 常驻通知控制中心：状态栏常驻一条通知，直接显示电量、切换降噪四模式 （关闭 / 降噪 / 抗风 / 透传）、控制空间音频（开关 + 3 档头部追踪），点击打开应用
- 通知显示设置编辑页（设置 → 通知显示设置）：自定义常驻通知显示哪些类别 —— 设备名 / 电量明细 / 降噪快捷按钮 / 空间音频等
- 本机 BLE 自扫发现耳机：不依赖任何 Hook，自行扫描发现耳机的 LE 地址并直连； 地址变化时自动重新发现（地址全动态发现）
- ANC 型号档案库（
AncProfileLib）：按设备名自动套用实测设备码映射 （如 GA2 实测 1=关/2=降/3=抗风/4=透传），未实测型号回退默认映射； 设置页可自定义映射并优先生效 - 扩展设备控制（DC）：空间音频 / 头部追踪 / 增益 / 指示灯控制，
设备码映射由
AncProfileLib.DcProfile按型号提供 - 三协议自动识别：GAIA V3（BLE）/ GAIA V4（RFCOMM/SPP，如布丁）/ Moondrop 私有
9ECA0000自动路由；dual-mode 设备 BLE 失败自动回退 RFCOMM/SPP - 9ECA 私有协议客户端：音源切换 / EQ / MIC / SN（复用同一 GATT 连接，与 GAIA 并存）
- 非 root 保活与自启动：开机自启广播 + 30 秒心跳自检 + 电池白名单引导； 另有可选的「Root 强力保活」（无 Root 也完全够用）
- 权限检查页（整页二级界面）：蓝牙权限 / 通知权限 / 电池优化白名单 / 后台监听服务 / Root 环境 / GAIA 直连 6 项实时检查，缺失一键跳转修复
- 日志抓取：一键收集系统信息 / 应用设置 / 蓝牙 / 运行环境 / logcat / 应用内日志 六类日志打包为 ZIP，便于反馈设备适配问题
- M3 界面：概览页（状态圆点 + 英雄卡 + 电量面板 + 降噪控制）与设置页， 跟随系统深浅色、Material You 动态取色、AMOLED 纯黑可选
- 中英文切换：语言偏好（跟随系统 / 中文 / English），界面与通知文案随之切换
- 模拟测试：设置页内置「模拟连接 / 断开耳机」，无需真机即可预览常驻通知
| 项目 | 说明 |
|---|---|
| 语言 | Kotlin |
| 构建链 | Gradle 8.9（wrapper 固定）+ AGP 8.5.2 + Kotlin 1.9.22，JDK 17 |
| UI | Material 3，Theme.Material3.DayNight.NoActionBar + 动态取色，双 Tab Fragment 架构 |
| 最低/目标 SDK | minSdk 26（Android 8.0）/ targetSdk 36 |
| 包名 | com.fxxkmoondrop.secret |
| 运行时依赖 | 仅 AndroidX + Material Components + Kotlin 标准库/协程（无第三方 SDK） |
# 1) 准备 release 签名密钥（仓库不包含 keystore，需自备）
keytool -genkeypair -v -keystore app2.keystore -alias fxxk \
-keyalg RSA -keysize 2048 -validity 10000
# 2) Release 构建（签名口令通过 Gradle 属性传入）
./gradlew :app:assembleRelease -PfxxkKeypass=<签名密码>
# 产物：app/build/outputs/apk/release/app-release.apk
# 或者只要 Debug 构建（无需 keystore）
./gradlew :app:assembleDebugWindows 环境补充：
$env:JAVA_HOME="C:\Program Files\Zulu\zulu-17"
$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
.\gradlew.bat :app:assembleDebug首次构建需
build-tools;34.0.0与platforms;android-34。 若使用命令行工具安装 build-tools，注意解压出的目录名需为34.0.0。
- 签名方式：
app/build.gradle.kts中的signingConfigs.release读取app2.keystore，口令来源优先级为环境变量FXXK_KEYPASS→ Gradle 属性-PfxxkKeypass=（CI 中走 Secrets）
- 下载 APK 并安装（首次需在系统设置中允许「安装未知来源应用」）
- 打开 App，进入 设置 → 检查权限，按提示授予：
- 蓝牙权限（必需的
BLUETOOTH_CONNECT+BLUETOOTH_SCAN） - 通知权限（常驻通知控制中心需要）
- 电池优化白名单（否则息屏后系统可能杀掉后台监听）
- 蓝牙权限（必需的
- 打开耳机盖，App 会自动发现并直连，状态栏出现常驻通知控制中心
无需 Root，无需 LSPosed，无需 Google Play 服务。
部分国产 ROM（ColorOS / MIUI / HyperOS 等）会激进冻结后台进程， 如果发现耳机连上后不自动重连，请在系统设置中为本应用开启 「允许后台活动」/「自启动」/「无限制电量」，并在 App 内开启 设置 → 保活与自启动 → 无连接时也常驻。
下表理论上支持与未知的型号多为芯片级推断，尚未逐一实机验证。 欢迎拥有对应耳机的用户连接一次并把结果反馈到 Issue。
兼容性判定基于蓝牙传输层与服务指纹，不依赖型号名：
- 耳机暴露高通 GAIA 服务 via BLE GATT → 走 GAIA V3 协议
- 耳机暴露高通 GAIA 服务 via Classic BT RFCOMM/SPP → 走 GAIA V4 协议（如布丁 PUDDING）
- 耳机暴露 Moondrop 私有
9ECA0000服务 → 走私有协议（音源切换 / EQ / MIC / SN）因此只要主控为高通 QCC 或中科蓝讯（Bluetrum），理论上即可接入。
| 状态 | 耳机型号 | 主控 / 协议 | 依据 |
|---|---|---|---|
| 已实测 | 梦回2 / Golden Ages 2（GA2） | TWS-01 定制 SoC（GAIA） | 实机验证通过（ANC 设备码 1=关/2=降/3=抗风/4=透传 已入库） |
| 理论上支持 | 爱丽丝 ALICE | QCC5151（GAIA） | 芯片理论支持 |
| 理论上支持 | 火花 SPARKS | QCC3040（GAIA） | 芯片理论支持 |
| 理论上支持 | 旅行者 VOYAGER（颈挂） | QCC5144（GAIA） | 芯片理论支持 |
| 理论上支持 | 梦回1979 / Golden Ages | 与梦回2同平台同款主控（GAIA） | 芯片理论支持 |
| 理论上支持 | 猫饼 NEKOCAKE | BT8922E（9ECA） | 芯片理论支持 |
| 已实测 | 太空漫游2 / Space Travel 2 | BT8932F（9ECA） | 实机验证通过（ANC 设备码 1=关/2=降/3=抗风/4=透传；增益 设备码 0=高/1=中/2=低 已入库） |
| 理论上支持 | 音乐胶囊 PILL | BT8932F（9ECA） | 芯片理论支持 |
| 理论上支持 | 超声波 ULTRASONIC | BT8952F（9ECA） | 芯片理论支持 |
| 理论上支持 | 知更鸟 Robin | BT8952F（9ECA） | 芯片理论支持 |
| 未知 | 太空漫游 / Space Travel（一代） | 疑似中科蓝讯（型号未确认） | 待实机验证 |
| 未知 | 猫咖 MOCA | 疑似蓝讯（蓝牙 5.4 / LC3 特征） | 待实机验证 |
| 未知 | 方糖 BLOCK | 疑似蓝讯 BT8922 系 | 待实机验证 |
| 应该支持 | 布丁 PUDDING（MD-TWS-056） | 国产 SoC（GAIA V4，RFCOMM/SPP） | 借助 PuddingPods 协议文档完成适配，5 档 ANC + 三路电量 + 增益 + 指示灯 |
| 未知 | 太空漫游2 ULTRA | 国产 SoC（型号未公开） | 待实机验证 |
| 未知 | 羽翼 EDGE / EDGE2 | 国产 SoC（型号未公开） | 待实机验证 |
- 已实测：开发者实机验证过
- 理论上支持：主控芯片已确认且协议侧能自动识别，但尚未逐一实机跑通
- 未知：主控未公开或被疑为蓝讯系，需连接耳机后看日志 GATT 指纹
（
GAIA/9ECA0000）定论
Mooncontroller/
├── app/ # Gradle 应用模块（sourceSets 指向 ../src）
│ └── src/main/ # AndroidManifest.xml / res / assets
├── src/ # 全部 Kotlin / Java 源码（包 com.fxxkmoondrop.secret）
├── gradle/ # Gradle wrapper（8.9）
├── build.gradle.kts # AGP 8.5.2 + Kotlin 1.9.22（apply false）
├── settings.gradle.kts # 模块声明与仓库
├── NOTICE.md # 版权、许可与修改声明
├── ADAPTATION.md # 设备适配说明（协议知识 / 踩坑 / 实测数据）
├── DEVELOPMENT.md # 开发文档
└── CHANGELOG.md # 更新日志
注意：
src/是源码的单一权威目录，app/src/main/java/下不重复存放代码。 新增.kt文件请直接放入src/com/fxxkmoondrop/secret/。
| 文档 | 内容 | 对本分支的适用性 |
|---|---|---|
| ADAPTATION.md | 协议知识、踩坑经验、实测数据、BLE/9ECA 帧格式、ANC 设备码映射 | 协议部分仍有效；连接策略章节部分过时 |
| DEVELOPMENT.md | 构建环境、签名、目录结构、版本号规范、依赖、组件、调试、发布清单 | ✅ 有效（已按本分支单进程纯 App 形态重写，剔除 LSPosed 模块章节） |
| CHANGELOG.md | 按 alpha.x.y 逐条记录 |
✅ 有效（本分支条目已补在文件顶部） |
| NOTICE.md | 版权归属、许可证、本分支的逐项修改声明 | ✅ 有效 |
版本号格式沿用上游约定
alpha.x.y：x为里程碑、y为迭代，versionCode单调递增。
本项目以 GNU GPL-3.0 授权发布。完整版权归属与修改声明见 NOTICE.md，也可在 App 内 设置 → 开源许可 中查看。
- bqj6666/FxxkMoondrop —— 本项目的上游。 上游完成了 GAIA / 9ECA0000 协议的逆向与设备适配，本分支的协议层几乎全部继承自上游。 Copyright (C) 2026 bqj6666 及 FxxkMoondrop 贡献者。
- lingbai-rong/PuddingPods —— 通过该项目的 协议逆向文档，完成了对水月雨布丁 PUDDING（MD-TWS-056）的适配（GAIA v4 over RFCOMM/SPP、5 档 ANC 设备码、三路电量含充电盒、增益与指示灯控制协议）。
- JingMatrix 及其维护的 LSPosed 生态 —— 上游的界面与交互风格参考了 LSPosed Manager 的设计；本分支已移除 LSPosed 依赖， 但保留对上游设计来源的致谢。
- 各 AI 工具协助开发。
App 运行时包含 AndroidX、Material Components、Kotlin 标准库与协程等 Apache-2.0 组件。 完整清单、版本与版权信息见 NOTICE.md 第 6 节。
完整变更记录见 CHANGELOG.md。本分支自 alpha2.42 起独立演进：
| 版本 | 变更要点 |
|---|---|
| alpha2.50 | GAIA 下行命令 1 秒窗口去重；断连恢复链路全量落 AppLog |
| alpha2.49 | 修复「透传 / 抗风按钮互换」；补齐断连诊断日志 |
| alpha2.48 | 分发收尾：新增 NOTICE.md、RELEASING.md、App 内开源许可页；README 改写；隐私清理 |
| alpha2.47 | 轮询失败落 AppLog；断开差集按设备族去重 |
| alpha2.46 | 修复 GAIA 连接每 10~11 秒被自行掐断的抖动；后台监听开关一次性迁移；打通 release 签名 |
| alpha2.45 | profile proxy 注册自愈；广播兜底记录设备；无名设备按设备族认领 |
| alpha2.44 | 修复连接后约 20 秒才出现通知控件（LE 地址误选 LE Audio 绑定） |
| alpha2.43 | 通知加入空间音频；应用改名 Mooncontroller；替换启动图标；优化首连时延 |
| alpha2.42 | 移除 LSPosed/Xposed 形态，转为未 root 可用的纯 App；删弹窗、加常驻通知控制中心 |
alpha2.41.6 及更早 |
上游版本，见 CHANGELOG.md 后段 |
本程序按「原样」提供，不附带任何明示或默示的担保。 本项目仅供学习与研究 Android 逆向与蓝牙协议使用，请勿用于任何商业用途 或侵犯他人权益的行为。使用本项目造成的一切后果由使用者自行承担。
如需将本项目用于商业目的，请先自行联系上游作者取得明确许可 —— 详见 NOTICE.md 第 8 节。