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
parent 392f4544f4
commit 7ebbaef631
29 changed files with 1979 additions and 98 deletions
@@ -71,6 +71,78 @@ class CreditsTest {

    @Test
    fun contractVersionIsPinned() {
-        assertEquals("契约版本必须与 opendance-web v0.1.0 对齐", "0.1.0", Credits.CONTRACT_VERSION)
+        // 本端是 websocket-keypoints 的发送方，这项必须与契约快照一致
+        assertEquals(
+            "websocket-keypoints 契约版本必须与 opendance-web 冻结版本一致",
+            "0.2.0",
+            Credits.CONTRACT_VERSION,
+        )
+    }
+
+    @Test
+    fun everyContractVersionMatchesTheSnapshot() {
+        // 契约版本是"单一来源"：contracts/VERSION 决定一切，界面不得手写
+        val snapshot = readContractVersionFile()
+        assertTrue("能读到 contracts/VERSION", snapshot.isNotEmpty())
+        assertEquals(
+            "契约项数与 contracts/VERSION 一致（新增契约时忘记同步会导致这里失败）",
+            snapshot.size,
+            Credits.contractVersions.size,
+        )
+        for ((name, version) in Credits.contractVersions) {
+            assertEquals(
+                "契约 $name 的版本与快照一致",
+                snapshot[name] ?: "",
+                version,
+            )
+        }
+    }
+
+    @Test
+    fun appVersionMatchesProjectYaml() {
+        // 文档 §11.2：界面展示的版本必须与 project.yaml / 产物文件名同源
+        val yaml = readProjectYamlVersion()
+        assertTrue("能读到 project.yaml 的 version", yaml.isNotEmpty())
+        assertEquals("BuildConfig.VERSION_NAME 必须等于 project.yaml 的 version", yaml, Credits.appVersion)
+        assertEquals("Credits.appVersion 与 BuildConfig 同源（不得手写）", BuildConfig.VERSION_NAME, Credits.appVersion)
+    }
+
+    @Test
+    fun contractSummaryListsAllContracts() {
+        val summary = Credits.contractSummary()
+        for ((name, version) in Credits.contractVersions) {
+            assertTrue("摘要含 $name", summary.contains(name))
+            assertTrue("摘要含 $name 的版本 v$version", summary.contains("v$version"))
+        }
+    }
+
+    // ------------------------------------------------------------ 文件读取
+
+    /** 从模块目录逐级向上找仓库根（含 contracts/VERSION 的那一级） */
+    private fun repoFile(relative: String): java.io.File? {
+        var dir: java.io.File = java.io.File(System.getProperty("user.dir")).absoluteFile
+        repeat(6) {
+            val candidate = java.io.File(dir, relative)
+            if (candidate.exists()) return candidate
+            dir = dir.parentFile ?: return null
+        }
+        return null
+    }
+
+    private fun readContractVersionFile(): Map<String, String> {
+        val file = repoFile("contracts/VERSION") ?: return emptyMap()
+        return file.readLines()
+            .map { it.trim() }
+            .filter { it.isNotEmpty() && !it.startsWith("#") && it.contains(":") }
+            .associate { it.substringBefore(":").trim() to it.substringAfter(":").trim() }
+    }
+
+    private fun readProjectYamlVersion(): String {
+        val file = repoFile("project.yaml") ?: return ""
+        return file.readLines()
+            .firstOrNull { it.trimStart().startsWith("version:") }
+            ?.substringAfter(":")
+            ?.trim()
+            ?: ""
    }
 }