Files

T

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

契约 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 校验）

2026-09-17 01:10:06 +08:00

3.2 KiB

Raw Permalink Blame History

第三方开源项目声明

OpenDance Studio Android 辅助 App v0.2.0

本软件使用了以下开源项目，特此声明。完整锚点见 contracts/open-source-credits.md （三端共用，任一端新增依赖须回到 opendance-web 更新该表）。应用「关于」页面展示同一份声明（见 app/src/main/java/com/opendance/studio/ui/Credits.kt）。

1. MediaPipe

版权：Copyright 2023 Google LLC
许可证：Apache License 2.0
源链接：https://github.com/google-ai-edge/mediapipe
用途：本应用的端侧姿态推理(MediaPipe Tasks Vision Android, 模型文件 pose_landmarker_lite.task)

2. Three.js

许可证：MIT
源链接：https://github.com/mrdoob/three.js
用途：Web 管理端 3D 预览

3. @pixiv/three-vrm

许可证：MIT
源链接：https://github.com/pixiv/three-vrm
用途：Web 管理端 VRM 加载

4. Assimp

许可证：BSD-3-Clause
源链接：https://github.com/assimp/assimp
用途：FBX/glTF 动作转换（可选，服务端侧使用）

5. Godot Engine

版权：Copyright Godot Engine contributors
许可证：MIT
源链接：https://github.com/godotengine/godot
用途：Windows 客户端引擎

6. godot-vrm

许可证：MIT
源链接：https://github.com/V-Sekai/godot-vrm
用途：VRM humanoid 扩展（Windows 客户端侧）

7. NestJS

许可证：MIT
源链接：https://github.com/nestjs/nest
用途：Web 管理服务端

8. TypeORM

许可证：MIT
源链接：https://github.com/typeorm/typeorm
用途：Web 管理服务端 ORM

9. OkHttp

许可证：Apache License 2.0
源链接：https://github.com/square/okhttp
用途：本应用的 WebSocket 推流

10. bvh

许可证：MIT
源链接：https://github.com/aimoonchen/bvh
用途：BVH 解析参考实现

补充声明（实际引入的依赖）

11. React

许可证：MIT
源链接：https://github.com/facebook/react
用途：Web 管理端界面

12. Vite

许可证：MIT
源链接：https://github.com/vitejs/vite
用途：Web 管理端构建

13. CameraX

许可证：Apache License 2.0
源链接：https://developer.android.com/jetpack/androidx/releases/camera
用途：本应用的相机采集

14. Jetpack Compose

许可证：Apache License 2.0
源链接：https://developer.android.com/jetpack/compose
用途：本应用的界面

15. mysql2

许可证：MIT
源链接：https://github.com/sidorares/node-mysql2
用途：Web 管理服务端数据库驱动

许可合规说明

本应用代码以 MIT 许可发布。
本应用通过 Maven 依赖引入 MediaPipe Tasks Vision、CameraX、Jetpack Compose 与 OkHttp，均为 Apache License 2.0；对应许可证文本随依赖包分发，可在各依赖的 Maven 构件中找到。
随包分发的模型文件 pose_landmarker_lite.task 来自 MediaPipe (Copyright 2023 Google LLC, Apache License 2.0)。
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑，以规避 SMPL 的非商用许可限制。
本应用只在设备本地进行推理，画面不离开手机；通过网络发送的只有 33 个骨骼关键点坐标，不含任何图像数据。

3.2 KiB Raw Permalink Blame History