zijunchiang/opendance-android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

feat(net,pose): 连接状态机与保活对齐 + MediaPipe 崩溃修复（T-AND-010/011/012）

Browse Source 
契约 websocket-keypoints 0.1.0 -> 0.2.0（向后兼容，子协议名与帧 version 不变；
先在 opendance-web 修改并提升版本，再同步三端快照）。

T-AND-011：连接状态异常、频繁重连（查实 3 个根因）
1. 保活用错了层：Windows 端有 5s 静默超时（只看应用层收到的帧），而本端只有
   OkHttp 的协议层 ping —— 它由底层库自动应答、**不暴露给应用层**，根本不能续命。
   画面里没人时 5s 必被踢、再重连，循环往复。
   - 契约新增 §1.1（welcome/config 声明 silentTimeoutMs 与 heartbeatIntervalMs，
     且心跳必须 < 静默超时的一半）与 §3.6（应用层 ping/pong）；
   - Windows 端超时 5s -> 15s、期望心跳 5s，并在 welcome/config 中下发；
   - 本端按声明发 ping，连续 3 个周期无 pong 才判定链路已死并主动重连。
2. 不该重连时也重连：契约新增 §7 关闭码策略，1000/1001/1002 与主动停止一律不重连。
3. frame_id 恒为 0：PoseDetector.detect() 算了 safeTimestamp 却忘了写回
   lastTimestampMs，接收端的丢包检测因此完全失效。已修。

其他对齐：
- 契约新增 §8 连接状态机 idle -> resolving -> connecting -> handshaking ->
  streaming -> degraded -> reconnecting -> stopped，两端同名便于对照日志；
  resolving 只对主机名生效，局域网直连 IP 直接进 connecting；
- 退避与抖动按 §7.1 冻结：0.5s -> 1 -> 2 -> 4 -> 8 -> 15s 封顶 + ±20% 抖动；
- 契约新增 §5 设备去重：hello 携带稳定 deviceId（ANDROID_ID 的 SHA-256 前 16 位，
  不含硬件序列号），Windows 端据此去重、旧连接以 1000 关闭；
- 新增 util/ConnectionLog（环形缓冲，最近 500 条：状态迁移 / close code /
  子协议协商 / 首帧时间 / 保活参数），运行页可一键导出（FileProvider）。

T-AND-012：MediaPipe 初始化崩溃（ExceptionInInitializerError: null）
- 诊断：新增 pose/PoseDiagnostics 展开 cause 链取真因（通常 UnsatisfiedLinkError）、
  区分 native 加载失败、比对设备 ABI 与 APK 内 ABI 并给出可执行结论；
- native 解压：packaging { jniLibs { useLegacyPackaging = true } }（AGP 8 release
  默认 extractNativeLibs=false，MediaPipe JNI 对它不兼容）；
- R8：补 -keepclasseswithmembernames 的 native 方法保留规则，并 -printseeds 输出
  seeds 供发布前核对（实测保留 20169 条 MediaPipe 条目）；
- 构建期新增 verifyReleaseAbi：release ABI 必须恰为 arm64-v8a/armeabi-v7a、
  每个 ABI 下必须有 MediaPipe native 库、模型资源必须存在；
- 未换库：诊断指向集成配置而非 MediaPipe 本身，保留 33 点契约零成本。

T-AND-010：版本号展示与单一来源
- 版本唯一来源 versionName（= project.yaml 的 version）；versionCode 按
  10000*主+100*次+修订 递增（0.2.0 -> 200）；
- 契约版本改为构建期解析 contracts/VERSION 后注入 BuildConfig（六项各自独立
  递增，原先的单个 CONTRACT_VERSION 常量已失真）；界面不再手写任何版本号；
- 新增 checkReleaseConsistency 并挂到 preBuild，三者不一致直接 BUILD FAILED。

README/DSH/THIRD_PARTY/tasks 同步更新（含「导出连接日志」「保活参数」
「最近断开原因」等新增可观察项与排查表）。

测试：56 项全部通过（新增 ReconnectPolicyTest 11 项、PoseDiagnosticsTest 12 项）；
build/verify.sh 全通过（单元测试 -> 构建 -> 签名/ABI/native/seeds/dex 校验）
This commit is contained in:
zijunchiang
2026-09-17 01:10:06 +08:00
parent 392f4544f4
commit 7ebbaef631
29 changed files with 1979 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+28 -8
View File
@@ -9,15 +9,15 @@ OpenDance Studio **阶段三**: Android 辅助 App(Kotlin + CameraX + MediaPipe
## 状态
**阶段三已完成**: T-AND-001 -> T-AND-009 全部落地。
**阶段三已完成**: T-AND-001 -> T-AND-012 全部落地（含重连状态机与 MediaPipe 崩溃修复）。
| 验收项 | 结果 |
|--|--|
| 单元测试 | OK **30 项全部通过**(JVM，无需设备) |
| 单元测试 | OK **56 项全部通过**(JVM，无需设备；新增重连策略与 MediaPipe 诊断用例) |
| **跨端金标准** | OK Kotlin 序列化器与 Web 端 TypeScript 实现**逐位一致** |
| `./gradlew assembleRelease` | OK 生成**已签名** APK(28.6 MB) |
| 签名校验 | OK `apksigner` 退出码 0, v2 方案，CN=OpenDance Studio Dev |
| 包信息 | OK `com.opendance.studio` v0.1.0, minSdk 29(Android 10+)/ targetSdk 34 |
| 包信息 | OK `com.opendance.studio` v0.2.0, minSdk 29(Android 10+)/ targetSdk 34 |
| 模型随包分发 | OK `assets/pose_landmarker_lite.task` 5.7 MB(Stored 未压缩) |
| ABI 覆盖 | OK arm64-v8a + armeabi-v7a(debug 额外含 x86/x86_64) |
@@ -172,9 +172,11 @@ IP 地址：192.0.2.10 # RFC 5737 文档示例网段，实际填你电脑
| 位置 | 可观察现象 |
|--|--|
| App 运行页 | 「连接状态」为**已连接**（或短暂「连接中」后转「已连接」） |
| App 运行页 | 「目标」显示 `ws://<IP>:<端口>/pose`；服务端返回 welcome 后出现「会话」ID |
| App 运行页 | 「连接状态」为**推流中**（`streaming`；短暂经过 解析地址 → 连接中 → 握手中） |
| App 运行页 | 「目标」显示 `ws://<IP>:<端口>/pose`；服务端返回 welcome 后出现「会话」ID 与「协商子协议」 |
| App 运行页 | 「已发送」帧数持续增长；「发送帧率」「识别帧率」大于 0；「推理耗时」为毫秒数 |
| App 运行页 | 「保活」显示心跳与静默超时（由服务端在 welcome 中声明），心跳必须小于静默超时的一半 |
| App 运行页 | 断开时「最近断开」显示 close code 与原因（如 `1001 对端离开`），而不是只有"未连接" |
| App 运行页 | 「人体识别」为**已识别**，叠加层出现骨架（黄点 = 置信度好，红点 = 置信度低） |
| Windows 客户端 | 显示已连接并收到关键点，VRM 模型随动作实时动起来 |
@@ -187,7 +189,9 @@ IP 地址：192.0.2.10 # RFC 5737 文档示例网段，实际填你电脑
| 3 | `bash build/build-apk.sh all` | debug 与 release 均 `OK`; release 显示 `已签名(APK Signature Scheme v2)` |
| 4 | `$ANDROID_HOME/build-tools/34.0.0/apksigner verify app/build/outputs/apk/release/app-release.apk` | 退出码 0（无输出即通过） |
| 5 | `unzip -l app/build/outputs/apk/release/app-release.apk \| grep pose_landmarker_lite.task` | 列出 `assets/pose_landmarker_lite.task`（约 5.7 MB, Stored 未压缩） |
| 6 | `adb install -r app/build/outputs/apk/debug/app-debug.apk` | `Success` |
| 6 | `./gradlew verifyReleaseAbi` | release APK 的 ABI 恰为 `[arm64-v8a, armeabi-v7a]`，且每个 ABI 下都有 MediaPipe native 库 |
| 7 | `grep -c "^com.google.mediapipe" app/build/outputs/mapping/release/seeds.txt` | 大于 0（说明 R8 没有裁掉 MediaPipe；为 0 则 release 必崩） |
| 8 | `adb install -r app/build/outputs/apk/debug/app-debug.apk` | `Success` |
其中 `KeypointFrameTest.goldenVectorMatchesWebImplementation` 必须通过：
它断言本端 Kotlin 序列化器与 Web 端 TypeScript 实现产出**逐位相同**的 239 字节帧。
@@ -200,7 +204,10 @@ IP 地址：192.0.2.10 # RFC 5737 文档示例网段，实际填你电脑
| 相机预览正常但「人体识别」一直是「未识别到人体」 | 光线不足、人不在画面内、或分辨率/模式不合适 | 站到画面中央并改善光照；确认分辨率不是过低；观察「推理耗时」是否异常大 |
| 「连接状态」一直「已断开 / 重连中」，「测试连接」失败 | IP 或端口填错；Windows 客户端未启动；防火墙拦截入站 8765；手机与电脑不在同一网段（AP 隔离） | 核对连接页「本机地址」与电脑 IP 是否同网段；启动客户端；在 Windows 防火墙放行 OpenDance 的 TCP 8765 入站；关闭路由器 AP 隔离 |
| 「扫描局域网」扫不到主机 | 手机未连 WiFi、路由器 AP 隔离、或客户端未监听 8765 | 确认手机连的是 WiFi 而非蜂窝；改为手动填 IP；检查客户端监听端口与防火墙 |
| 点「开始推流」立即闪退，或提示 MediaPipe 初始化失败 | MediaPipe 原生库加载 / 静态初始化失败抛出的是 **Error** 子类（`UnsatisfiedLinkError`、`ExceptionInInitializerError`），不是 `Exception`；常见诱因是 ABI 不匹配（例如把只含 arm 的 release 包装到 x86 模拟器）或模型资源缺失 | 改用与设备 ABI 匹配的包（真机用 release，模拟器调试用 debug）；确认 APK 内含 `assets/pose_landmarker_lite.task`。仓库已在 `PoseDetector.initialize()` 中 `catch Throwable` 兜底并把原因显示在运行页；`CrashLogger` 会把未捕获堆栈写入应用私有目录，并在连接页展示，可截图反馈，或用 `adb logcat -s PoseDetector` 查看 |
| 点「开始推流」立即闪退，或提示 MediaPipe 初始化失败 | MediaPipe 原生库加载 / 静态初始化失败抛出的是 **Error** 子类（`UnsatisfiedLinkError`、`ExceptionInInitializerError`），不是 `Exception`；常见诱因是 ABI 不匹配（例如把只含 arm 的 release 包装到 x86 模拟器）、`extractNativeLibs=false`、R8 裁掉 MediaPipe 或模型资源缺失 | **先看 App 给出的诊断**：`PoseDiagnostics` 会把 cause 链最内层的真因、设备 ABI、APK 内 ABI 与结论一起显示在运行页（例如"APK 只包含 arm64-v8a/armeabi-v7a，而模拟器（x86_64）需要 x86_64"）。真机用 release、模拟器调试用 debug；仓库已用 `jniLibs.useLegacyPackaging = true` 处理 native 解压，并有 `-keepclasseswithmembernames` + `-printseeds` 防止 R8 裁掉 MediaPipe |
| 画面里没有人 / 相机暂停一段时间后连接被断开 | 这是**静默超时**（服务端在 welcome 里声明 `silentTimeoutMs`），即使没有关键点，App 也会按 `heartbeatIntervalMs` 发应用层 `ping` | 正常情况下不会触发。若仍频繁断开，运行页「保活」一行会显示两端的参数；契约要求心跳小于静默超时的一半，可在 Windows 端 `pose_server.gd` 调整并在两端核对日志 |
| 断网恢复后不自动重连 | 契约 §7 规定：**只有真正断开才重连**；服务端主动关闭（`1000`/`1001`）或协议错误（`1002`）以及用户主动停止都**不**重连，避免"重连风暴" | 运行页「最近断开」会写明 close code 与原因。若原因是 `1001 对端离开`，说明 Windows 客户端那边重启或主动关闭了推流，需要在电脑端恢复后再点一次「开始推流」 |
| Windows 端「已连接 N 台」忽大忽小 | 同一次闪断被计成多台设备 | 契约 §3.1 要求 hello 携带稳定的 `deviceId`（本端取 ANDROID_ID 的哈希，不含硬件序列号），接收端按它去重。核对两端日志中的 deviceId 是否一致 |
## 技术栈
@@ -233,7 +240,20 @@ app/src/main/java/com/opendance/studio/
└── ui/ 连接页 / 运行页 / 关于页
```
## 依赖的契约（opendance-web v0.1.0 冻结）
## 依赖的契约（opendance-web 冻结，逐项独立版本）
| 契约 | 版本 |
|--|--|
| `websocket-keypoints` | 0.2.0（本端为发送方） |
| `skeleton-topology` | 0.2.0 |
| `rest-api` | 0.5.0 |
| `data-models` | 0.7.0 |
| `model-formats` | 0.5.0 |
| `database` | 0.4.0 |
版本号来源统一（文档 §11.2）：应用版本取 `app/build.gradle.kts` 的 `versionName`
（= `project.yaml` 的 `version` = APK 文件名 = Git tag），契约版本在构建期从
`contracts/VERSION` 解析后注入 `BuildConfig`；Kotlin 界面代码里不出现任何版本号字面量。
- [`contracts/websocket-keypoints.md`](contracts/websocket-keypoints.md) - 239 字节关键点帧(本端为**发送方**)
- [`contracts/skeleton-topology.md`](contracts/skeleton-topology.md) - MediaPipe 33 点索引与坐标语义