zijunchiang
7ebbaef631
契约 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 校验）
139 lines
5.8 KiB
Markdown
139 lines
5.8 KiB
Markdown
# 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. 单次会话加载范围
|
|
|
|
允许加载：
|
|
|
|
1. 本文件 `DSH.md`
|
|
2. `project.yaml`
|
|
3. 当前 `tasks/xxx.md`
|
|
4. 该任务文件中 `load` 列出的文件
|
|
5. `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. 硬性约束
|
|
|
|
1. **视频帧绝不离开设备**。只发送 33 个关键点坐标；这是本项目的隐私底线，
|
|
也是与「上传视频做云端推理」方案的本质区别。
|
|
2. **239 字节帧格式冻结**。任何字段改动都要先改 `opendance-web` 的
|
|
`contracts/websocket-keypoints.md` 并提升版本。
|
|
本端序列化器有金标准字节向量测试守护（见 8）。
|
|
3. **33 点顺序冻结**。MediaPipe Pose 的原始索引顺序**就是**契约顺序，
|
|
不得重排或插入。
|
|
4. **镜像语义**：发送**未镜像**的原始坐标，是否镜像由 `flags.bit0` 声明；
|
|
叠加层绘制时才按镜像显示。接收端据此决定如何还原。
|
|
5. **签名材料绝不入库**。`keystore/`、`keystore.properties`、`local.properties`
|
|
均已在 `.gitignore` 中。
|
|
6. 关于页与 `THIRD_PARTY.md` 必须与 `contracts/open-source-credits.md` 一致。
|
|
|
|
## 7. 验证（每任务执行）
|
|
|
|
```bash
|
|
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 只调用已定义接口（相机/推理/网络各自独立类） |
|
|
| 测试与实现同任务 | 测试单独任务，共享接口摘要 |
|