zijunchiang/opendance-android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity
34 Commits 2 Branches 4 Tags
v0.2.2
Commit Graph
12 Commits
Author SHA1 Message Date
zijunchiang c0d0937023 fix(reconnect): 合规接收端被周期性误判「链路已死」（v0.2.2）+ 可注入计时覆盖退避封顶 
一、测试抓到的真实缺陷（T-AND-017）
契约 §3.6 明确：「接收端收到任何一帧都算活动，ping **无需额外应答**即可保活，
pong 只用于诊断」—— 即"合规但不回 pong"的接收端是**合法**的。
但 PoseWebSocketClient.onOpen 里写的是 lastPongAtMs = timing.nowMs()，
于是心跳循环的守卫 if (lastPongAtMs > 0 && silentFor > limit) **恒为真**：
对任何接收端都会「判定链路已死 → 主动断链 → 重连」，默认参数
（heartbeatIntervalMs=5000）下即**每 15 秒断一次**，正是用户抱怨的「频繁重连」。

为什么以前没暴露：我们自己的接收端（Windows PoseServer）**会**回 pong
（T-WIN-020 实测 9 次 ping 全部收到 pong），这条路径在自家联调里永远走不到。

修复：onOpen 复位 lastPongAtMs = 0L（0 = 本连接还没收到过 pong），
只有「曾经回过 pong、之后又不回了」才判定链路已死 —— 这正是该诊断本来的意图。

二、可注入计时 Timing（时钟 + 等待）
契约 §7.1 的退避序列 0.5s→1→2→4→8→15s 封顶若要端到端验证，真实等待约 30 秒；
「连续 3 个心跳周期没收到 pong」也要等几十秒。抽成接口后：
  * 生产默认 SystemTiming = 真实时钟 + 真实 delay，行为与抽取前完全一致
    （10 处 System.currentTimeMillis() 与 2 处 delay() 改走 timing）；
  * 测试注入「可控时钟 + 立即返回的等待」，毫秒级跑完整条序列。

三、新增 4 项 JVM 用例（PoseWebSocketBackoffTest，无需设备）
  * 退避序列在 15 秒封顶且不无限增长：连续失败下断言第 1..8 次等待分别落在
    500/1000/2000/4000/8000/15000/15000/15000 的 ±20% 区间内，且真实耗时 < 5 秒；
  * 等待走注入实现：前三次重连真实耗时 < 1.5 秒（真实退避需 3.5 秒）；
  * **合规但从不回 pong 的接收端不会被判定链路已死**（修复前此处失败）：
    走过 6 个心跳周期仍为 streaming、无「判定链路已死」日志；
  * 曾经回过 pong 之后停止回复时判定链路已死并重连：诊断仍然有效。

实测：./gradlew :app:testDebugUnitTest → 7 个测试类 / 68 项用例 / 0 失败（原 64）。
build/verify.sh 全绿（签名、APK 元数据 0.2.2/202、native 体检、ABI、R8、dex）。
版本号 0.2.1/201 → 0.2.2/202。

写测试踩的两个坑（已写入任务文档）：
  1. 不要在瞬时重连下读 stats.nextRetryMs（等待立即返回后已被清零，与重连循环竞争），
     等待时长应取注入实现记录的事实；
  2. 虚拟时钟需要一个真实让出点（FakeTiming.await 里 2ms 真实 delay），
     否则心跳循环会在网络回调落地前把时钟推过阈值。
 2026-09-18 02:34:54 +08:00
zijunchiang 6dfd90f7ca fix(reconnect): 上一次会话的关闭码污染下一次会话（v0.2.1）+ 重连链路的真实 WebSocket 集成测试 
ReconnectPolicyTest（11 项）验的是**纯函数**「给定关闭码应该怎么退避」，而 ⑦
「连接频繁重连」的缺陷往往出在**调用点**。新增 PoseWebSocketReconnectTest（8 项）：
用 MockWebServer.withWebSocketUpgrade 在 JVM 上起**真实** WebSocket 服务端
（能按 §3.2 回 welcome、按 §3.6 回 pong、按指定关闭码关连接），无需设备即可覆盖
「该重连的」与「不该重连的」两条分支。Robolectric 只用来提供 android.os.Build 桩。

它抓到的真实缺陷（本版修复）：
  上一次会话的关闭码会污染下一次会话，导致重新开始推流后失去自动重连能力。
  复现：第一次连接被对端以 1001 关闭（按 §7 不重连，正确）→ 用户再点「开始推流」
  → 这一次是网络层失败（服务端还没起来），按 §7 **应当**重连 → 但 connect() 只重置了
  reconnectCounter 与 lastPongAtMs，**没有清 lastCloseCode** → scheduleReconnect()
  仍按 1001 判定 → 直接 stopped，**再也不会自动重连**。
  测试失败信息（修复前）：
    ✗ 上一次 1001 关闭后重新连接，遇到网络失败仍应按策略重连
      AssertionError: 当前 state=STOPPED，lastCloseCode=1001，attempts=0

修复（PoseWebSocketClient.kt）：
  * connect()：清掉会话级关闭状态（lastCloseCode=0、lastCloseReason=""）；
  * onFailure()：记录 recordClose(0, …)（契约 §7 中 0=未收到关闭帧 → 应重连），
    顺带让界面「最近一次断开原因」显示本次失败而不是旧值。

用例清单：握手→streaming 与 welcome 保活参数解析、按协商间隔发 ping 收 pong、
1011 按退避重连且等待落在策略 ±20% 区间、成功后计数清零、1001/1002 不重连、
主动断开不重连、上一次 1001 后再连遇网络失败仍应重连（本次回归锁）、
服务端未启动时 1.5s 内 ≤3 次尝试（退避生效）。

实测：./gradlew :app:testDebugUnitTest → 6 个测试类 / 64 项用例 / 0 失败
（原 56 项）；build/verify.sh 全绿（签名、APK 版本元数据 0.2.1/201、native 库体检、
ABI、R8、dex）。版本号 0.2.0/200 → 0.2.1/201。

踩坑：第一版 MockWebServer 夹具的 101 响应没有回显 Sec-WebSocket-Protocol
（RFC 6455 要求），客户端记录的 negotiatedProtocol 为空导致断言失败 —— 那是
**夹具**不合规而非客户端问题，已在夹具里补上。写「真实对端」夹具时要按 RFC/契约
把服务端做对，否则会把夹具缺陷误判成产品缺陷。
 2026-09-17 05:44:03 +08:00
zijunchiang 95429e8ce3 test(native): APK native 库体检——ELF 类型 / DT_NEEDED 闭包 / 16 KB 页对齐（T-AND-015） 
T-AND-012 的结论是「ExceptionInInitializerError 的根因在集成配置（native 解压 +
R8 + ABI），不是 MediaPipe 本身不稳定」，但当时的核查是**手工一次性**的（unzip 看
lib/、grep seeds、strings 找类名）——下次照样可能漏，且漏了也没人发现，只会在用户
装上手机、点开相机那一刻暴露。

新增 build/check_native_libs.py（纯 Python 标准库解析 ELF，不需要 readelf / NDK），
检查三项**无设备也能查**的「一装上就崩」根因：
  * ABI 与 ELF 类型匹配（把 x86_64 的 .so 放进 lib/arm64-v8a/ → 一加载就崩）；
  * DT_NEEDED 依赖闭包（非系统库必须同 ABI 目录内自带；MediaPipe 早期版本的
    libc++_shared.so 就是这么缺的）；
  * PT_LOAD 页对齐 ≥ 16 KB（Android 15 起部分设备页 16 KB，4 KB 对齐会直接加载失败；
    Google Play 2025-11 起也要求）。
外加 zipalign -c -P 16 -v 4（有 build-tools 时）。已接入 verify.sh 与 accept-release.sh。

实测（已发布的 opendance-android-v0.2.0.zip 内 APK）：
  双 ABI 下 6 个 .so 全部 ELF 类型匹配、依赖闭包完整（libmediapipe_tasks_jni.so 只依赖
  libdl/libjnigraphics/libEGL/libGLESv2/libm/libz/liblog/libandroid/libc，全是系统库）、
  PT_LOAD p_align=0x4000（16 KB 兼容）、zipalign -P 16 通过。
  结论：打包配置这一侧的「一装上就崩」风险已排除，剩下的只能靠真机实测。

与 readelf 交叉验证（6 个 .so 的 DT_NEEDED / p_align / e_machine 逐项一致）——
这次交叉验证抓到解析器自己的 bug：第一版程序头偏移写错（ELF64 的
p_offset/p_vaddr 之后第三个 QWORD 是 p_paddr 而非 p_filesz），导致 vaddr→offset
映射失败、DT_NEEDED 解析为空，页面照样打印「✓ 依赖闭包完整（系统库 0 项）」——
一句**假通过**，唯一破绽就是那个 0。教训：通过输出必须带可核对的数量/取值。

反向验证（三条分支都用真实负例证明会失败）：
  * 注入宿主 x86_64 的 libz.so.1 到 lib/arm64-v8a/libbogus.so → 同时报 ELF 类型不符、
    缺依赖 libc.so.6、页对齐 0x1000 < 16384；
  * 把 libz.so 从系统库白名单去掉 → 报缺少依赖 libz.so（证明闭包分支是活的）；
  * --expected-abis 传错 → 报 ABI 集合不符。

verify.sh 全绿；对**已发布资产**重新下载后跑完整 accept-release.sh 全部通过。
未新发版本：APK 本身未变（本任务是检查工具与文档），README 的新增项随下次发布进包。
 2026-09-17 05:25:04 +08:00
zijunchiang c207e7dadd test(accept): 发布包级端到端验收（读 zip 内 APK）+ T-AND-014 
`build/verify.sh` 验的是 app/build/outputs/ 里**刚构建**的 APK，而用户装的是 zip
里的 app-release.apk。两端都因此翻过车（Web v0.7.4 实体注册、Windows v0.2.1 的
PE 版本元数据），故三端统一：每次发布都要有一条读产物本身的验收（文档 §7.5）。

新增 build/accept-release.sh，对一个 zip（或已解压目录）跑完：
  1) sha256（有 SHA256SUMS 时）；
  2) 解压 + 文件清单（apk / README.txt / THIRD_PARTY.md / contracts/VERSION）；
  3) APK 的 AndroidManifest versionName/versionCode = 发布版本（复用
     check-apk-version.sh —— 安装界面与应用信息页读的就是它）；
  4) ABI 恰为 arm64-v8a + armeabi-v7a、无模拟器 ABI，且两个 ABI 下都有
     MediaPipe native 库（T-AND-012 崩溃根因之一）；
  5) assets/pose_landmarker_lite.task 在包内；dex 里仍有
     poselandmarker/PoseLandmarker（R8 没整体裁掉）；
  6) 有 apksigner 时顺带验签；
  7) 包内 contracts/VERSION 与仓库逐项一致（抓「APK 用旧契约构建、快照拷了新的」）。
package-release.sh 结尾打印下一步验收命令；README 补用法。

实测（对**已发布**的 v0.2.0 资产重新下载后跑）：sha256 OK、版本元数据 0.2.0/200、
ABI 恰为两个真机 ABI、两个 ABI 下都有 MediaPipe native、模型资源在、dex 命中
PoseLandmarker、apksigner 通过、契约快照与仓库一致 → 发布包级验收全部通过。

反向验证（真实负例）：
  * 篡改包内 contracts/VERSION 的 data-models=0.6.0 →
    ✗ data-models：包内 0.6.0，仓库 0.7.0，退出码 1；
  * 期望版本写 0.2.1 对 v0.2.0 的包 → ✗ versionName 是 '0.2.0'，期望 '0.2.1'
    且 ✗ versionCode 是 200，期望 201。

诚实声明：**装到真机跑 30 分钟**这条脚本替代不了，仍属设备实测项；本脚本能证明的是
「装得上、不会因打包配置而崩」。verify.sh 仍全绿。
 2026-09-17 04:51:16 +08:00
zijunchiang 31b6ddd0fa test(packaging): APK 产物版本元数据校验（T-AND-013）+ 修 die 在定义前被调用 
文档 §11.2 要求「版本号单一来源 + 可核对」。本仓库原有校验只覆盖**构建配置**
（gradle verifyReleaseVersion 比 versionName ↔ project.yaml）。但版本号真正被
系统与用户看到的地方是 **APK 的 AndroidManifest**：安装界面、应用信息页、
dumpsys package 读的都是它。构建缓存、复用旧 APK、打包时拷错文件都会造成
「配置全对、产物是旧版」——配置层校验抓不到。

这不是假设：同批工作里 Windows 端 v0.2.1 的发布包就是配置文件全一致、
exe 属性页显示 0.1.0（opendance-windows/tasks/017-pe-version.md）。

新增：
  * build/check_apk_version.py：直接解析 APK 内 AndroidManifest.xml（二进制 AXML）
    的 versionName / versionCode。只依赖 Python 标准库，不需要 Android SDK/aapt2。
    AXML 解析：顶层 ResChunk_header → 字符串池（UTF-8 与 UTF-16 都要处理）→
    START_ELEMENT；属性名本身就在字符串池里，按文本匹配即可，无需资源映射表；
  * build/check-apk-version.sh：薄包装，期望版本缺省取 project.yaml，
    并校验 versionCode == 10000*主 + 100*次 + 修订（§11.1）；
  * build/verify.sh 步骤 3/3 新增「版本元数据」计分项（原先只 aapt2 打印一行）；
  * build/package-release.sh 打包前校验源 APK，不一致即 die。

交叉验证（与 aapt2 dump badging 逐项一致）：
  v0.1.0 APK -> versionCode 1 / versionName 0.1.0
  v0.2.0 APK -> versionCode 200 / versionName 0.2.0
  app/build/outputs/apk/release/app-release.apk -> 同 v0.2.0
反向验证（用真实旧产物当负例）：
  bash build/check-apk-version.sh dist-release/opendance-android-v0.1.0/app-release.apk
    ✗ versionName 是 '0.1.0'，期望 '0.2.0'
    ✗ versionCode 是 1，期望 200
    退出码 1

顺带修复：build/package-release.sh 第 31/33 行用 die 报版本不一致，但 die()
到第 40 行才定义。命中该分支时输出的是
    build/package-release.sh: 行 31: die: 未找到命令   （退出码 127）
脚本确实中止了，但用户完全看不出真实原因。现把 log()/die() 移到首次使用之前：
    [error] 版本号不一致：参数/versionName=9.9.9，project.yaml=0.2.0  （退出码 1）

未新发版本：APK 内容与 v0.2.0 完全一致（产物侧校验证明其 versionName/versionCode
本就正确），本次改动只涉及构建/校验脚本与文档，故不为它提版本号；
README.txt 的新增自检项会随下一次 Android 发布进入发布包。
 2026-09-17 04:29:52 +08:00
zijunchiang ad18427928 docs: 补齐部署必需的 Gitea 域名与属主（不再脱敏成占位符） 
域名与仓库属主属于「部署必需且非隐私」的信息，此前写成 `<Gitea 地址>/<owner>`
会让读者无法照抄 clone 命令。补成真实值：gitea.kasugano.cn / zijunchiang
（口令与访问令牌仍为占位符）。README.md 的 clone 地址与跨仓库链接、
README.txt 的 clone 地址均已更新。
 2026-09-17 03:07:25 +08:00
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
opendance 68783c37b6 docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角） 
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则
（analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记，
且 _common 表恒定生效），把说明文档中会被标记的全角标点
（，：；？！（） 等）改为半角，并保证成对括号宽度一致。
中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。
 2026-09-15 21:45:51 +08:00
zijunchiang ab88231ea0 docs: 全角 ｜ ／ ？ 改 ASCII（Gitea 混淆字符检测的剩余触发项） 2026-09-15 21:36:41 +08:00
zijunchiang 91e56135fc docs: 其余易混淆字符（x/>=/<=/~/OK 取代 × − ≥ ≤ ≈ ✓） 2026-09-15 21:34:50 +08:00
zijunchiang 264786134c docs: 新增「初次部署（从零跑起来）」；去混淆字符与真实内网信息 
- README.md / README.txt 新增初次部署章节：前置条件（JDK 17 / SDK 34 / Gradle 8.9）、
  获取代码与本地配置（local.properties 不入仓）、Debug/Release 构建、装到手机与相机权限、
  连接配置（只连 Windows 客户端，默认 8765 / /pose）、第一次跑通、自检清单、常见问题
- 单测数量按实际（30 项）修正
- 三库同源契约：':=' 写法修回、去掉真实 MariaDB 版本串
- 全文去除易被 Gitea 判为「模棱两可 Unicode」的字符
- 本机 JDK 路径与内网示例地址改占位符 / RFC 5737 文档网段
 2026-09-15 21:33:27 +08:00
zijunchiang 84da39ad17 docs(android): 任务说明、DSH 约束与交付文档 2026-09-14 20:40:16 +08:00