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

5.8 KiB

Raw Permalink Blame History

DSH.md -- opendance-android(OpenDance Studio 项目三：Android 辅助 App)

0. 本文件的作用

本文件是 opendance-android 仓库内的 DSH 执行约束。顶层说明书见《DSH 开发文档：OpenDance Studio》，二者冲突时以顶层文档为准。

1. 项目定位

功能最单一的一端：用手机摄像头做端侧姿态推理，把 33 个骨骼关键点通过 WebSocket 推给 Windows 客户端。

手机摄像头 ──▶ MediaPipe Pose（端侧）──▶ 33 点关键点 ──▶ 239 字节帧
                                                          │
                                                          ▼
                                        ws://<windows-host>:8765/pose

画面不离开设备 -- 只有关键点坐标经网络发送。

2. 技术栈

组件	选型
语言	Kotlin 2.0.21
构建	AGP 8.7.3 + Gradle 8.9 + JDK 17
相机	CameraX 1.4.0 (Apache 2.0)
推理	MediaPipe Tasks Vision 0.10.35 (Apache 2.0)
通信	OkHttp 4.12.0 (Apache 2.0)
UI	Jetpack Compose(BOM 2024.10.01, Material3)

3. 单次会话加载范围

允许加载：

本文件 DSH.md
project.yaml
当前 tasks/xxx.md
该任务文件中 load 列出的文件
contracts/ 中被明确引用的锚点片段

禁止加载：

opendance-web / opendance-windows 的任何源码
非当前任务的 tasks/*.md
完整 contracts/ 目录（只引用锚点）
.gradle/、app/build/、*.apk、keystore/

4. 上下文预算

项	建议值
单任务文件数	<= 6
单任务代码行数	<= 1500
单任务 Token	<= 12K
契约引用	只引用锚点，不加载全文

5. 目录结构

opendance-android/
├── settings.gradle.kts / build.gradle.kts / gradle.properties
├── gradlew / gradle/wrapper/          # Gradle 8.9 wrapper
├── project.yaml / DSH.md
├── tasks/                             # 001~009 单任务说明书
├── contracts/                         # 只读契约快照(来源 opendance-web；六项各自独立版本)
├── app/
│   ├── build.gradle.kts               # 依赖、签名、R8、ABI
│   ├── proguard-rules.pro             # MediaPipe / OkHttp 的 keep 规则
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── assets/pose_landmarker_lite.task
│       │   └── java/com/opendance/studio/
│       │       ├── MainActivity.kt            # 三页导航
│       │       ├── OpenDanceApp.kt            # Application 单例容器
│       │       ├── model/                     # 239 字节帧 + 33 点拓扑
│       │       ├── camera/                    # CameraX
│       │       ├── pose/                      # MediaPipe 推理
│       │       ├── net/                       # WebSocket + 主机发现
│       │       ├── data/                      # 设置
│       │       └── ui/                        # 连接页 / 运行页 / 关于页
│       └── test/java/com/opendance/studio/    # JVM 单元测试
└── build/                             # 打包与验证脚本

6. 硬性约束

视频帧绝不离开设备。只发送 33 个关键点坐标；这是本项目的隐私底线，也是与「上传视频做云端推理」方案的本质区别。
239 字节帧格式冻结。任何字段改动都要先改 opendance-web 的 contracts/websocket-keypoints.md 并提升版本。本端序列化器有金标准字节向量测试守护（见 8）。
33 点顺序冻结。MediaPipe Pose 的原始索引顺序就是契约顺序，不得重排或插入。
镜像语义：发送未镜像的原始坐标，是否镜像由 flags.bit0 声明；叠加层绘制时才按镜像显示。接收端据此决定如何还原。
签名材料绝不入库。keystore/、keystore.properties、local.properties 均已在 .gitignore 中。
关于页与 THIRD_PARTY.md 必须与 contracts/open-source-credits.md 一致。

7. 验证（每任务执行）

export JAVA_HOME=<JDK 17 路径>     # AGP 8.7 需要 JDK 17
export ANDROID_HOME=<Android SDK 路径>

./gradlew testDebugUnitTest        # JVM 单元测试，无需设备
bash build/build-apk.sh all        # debug + release APK，并校验签名与产物
bash build/verify.sh               # 一键跑完上述全部并附加产物校验

首次部署（前置条件、本地配置、安装到手机、配置联通、自检清单、常见问题）见 README.md 的「初次部署（从零跑起来）」与 README.txt 对应小节。文档中的地址、路径、口令一律使用占位符，真实值不得写入仓库。

8. 跨端一致性验证（本项目最重要的测试）

KeypointFrameTest.goldenVectorMatchesWebImplementation 使用 opendance-web 已通过验收的 TypeScript 实现生成的 239 字节金标准向量，断言 Kotlin 实现产出逐位相同的字节。

这条测试同时守护三端：TypeScript（服务端参考实现）、GDScript(Windows 端)、 Kotlin（本端）。任何一端私自改动字段布局都会立刻失败。

生成金标准向量的方法见 tasks/004-keypoint-serializer.md。

9. 上下文超标时的拆分策略

超标原因	拆分方式
单任务涉及多个界面	按界面拆（连接/运行/关于）
单文件过大	按类拆，先生成接口再分实现
契约全文加载	改用锚点引用
需要参考其他项目	只读契约，不读源码
UI 与逻辑耦合	UI 只调用已定义接口（相机/推理/网络各自独立类）
测试与实现同任务	测试单独任务，共享接口摘要

5.8 KiB Raw Permalink Blame History