zijunchiang/opendance-windows
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
45 Commits 2 Branches 7 Tags
6ea2c93d66234ecca1d59348895819179064809a
Commit Graph
5 Commits
Author SHA1 Message Date
zijunchiang 6ea2c93d66 fix(pack): 编码取整与参考实现对齐 + 产物不再夹带测试夹具（v0.2.4） 
两个缺陷，都由上一轮的验收机制暴露：

1) 编码取整与契约参考实现不一致（T-WIN-022）
   KeypointFrame.encode() 用 GDScript 的 roundi（半数远离零），而契约参考实现
   （Web 的 keypoint-codec.ts）与**生产发送方 Android**（Kotlin Math.round）都是
   「半数朝 +∞」：-2.5 分别是 -3 与 -2。实测在 12 个跨实现向量里 1 例 33 字节不同。
   本端是接收方、encode() 只用于自测与协议回归，对产品无影响；但它让「跨实现一致性」
   只能停留在宽松口径（"差异仅限 .5 取整边界"），而宽松口径会退化成没人看的已知差异。
   修复：新增 _round_like_js(v) = floor(v + 0.5)，用于 4 处取整（坐标 ×3 + 置信度）；
   夹紧顺序对任意实数与参考实现等价。
   收紧：accept-frame-vectors.sh 的编码口径改为「必须为 0 项差异」。
   新增单测（+11 断言）：_round_like_js 的 5 个取值、端到端 -0.5/32767 → 0（roundi
   会给 -1，是有效判别用例），以及 test_reference_vectors_decode_and_encode_exactly
   —— 直接读锁定的参考向量逐值解码 + 用 f32InputPoints 重编码与 f32Hex 逐字节比对，
   让 verify.sh（只跑源码、无需 pck）也覆盖「Web ↔ Windows」这条边。

2) 产物里夹带开发/验收工具（T-WIN-023）
   export_filter="all_resources" 且 exclude_filter 没有 build/*，于是每次新增
   构建/验收脚本都被编译进 pck —— 包括**故意不合规**的坏服务端夹具 probe-ws-bad.gd
   与 frame-vectors.json。实测 OpenDance.pck 315,464 B →（排除后）145,400 B，
   即 54% 的 pck 是测试夹具。已发布的 v0.2.3 同样带着这些残留。
   修复：exclude_filter 增加 build/*；
   新增产物级防线 build/integration/list-pck.gd（遍历包内条目、标出
   res://build/ tests/ _scratch/ dist-release/ 与 *.md 残留，有残留即退出码 1），
   并接进 accept-release.sh（打印条目总数并断言「无开发残留」）——否则下次加个新
   工具目录又会重演。顺带确认 pck 没有把上一次导出的 pck 自嵌套进去。

实测（v0.2.4 发布包，三条产物级验收全绿）：
  * accept-release.sh：pck 58 项无开发残留 / PE 版本资源 0.2.4 / pck 启动 180 帧无错 /
    运行时探针（包内版本号 0.2.4、AboutScreen 显示值、15 项关键资源、契约表比对）
  * accept-ws.sh：客户端 30 通过 / 0 失败 + 服务端侧 16 项事实
  * accept-frame-vectors.sh：解码 12/12、396 点 0 差异，
    **编码器字节与参考实现完全一致（0 项差异）**
  * verify.sh：785 通过 / 0 失败（原 774）

踩坑：给 -0.5/32767 这类值写断言时，第一版按"理想有理数"期望（2.5/32767 → 3）而
失败 —— PackedVector3Array 存的是 float32，乘回 32767 后略小于半整数，与 JS 对同一
float32 输入的行为其实完全一致。断言必须基于实际存储精度，或改用有效判别用例。
 2026-09-17 05:59:54 +08:00
zijunchiang 1c5f28cd41 test(codec): 关键点帧跨实现一致性验收——包内 GDScript 解码器 × Web 参考实现（T-WIN-021） 
契约 §2 的参考实现是 opendance-web 的 keypoint-codec.ts（其 decodeBinaryFrame
注释就是「Windows 端参考实现」）。Android 已用金标准向量与它对齐；而本端的解码器
此前**只跟自己比过**（自己编码、自己解码），两个方向共用同一份错误假设也能一直绿。

新增：
  * build/integration/frame-vectors.json —— 由参考实现生成并锁定的向量
    （12 用例：i16 最小值 -32768、i16 最大值、±1 全量程、置信度 0/128/255、
    flags 低 3 位组合、frame_id 0xFFFFFFFF 与 0x80000000、取整边界）。
  * build/integration/probe-frame-vectors.gd —— 用**包内** KeypointFrame 解码同一批字节，
    与参考解码结果**逐值精确比对**（坐标/置信度先收敛到 float32 再比精确相等，
    因为本端点存 PackedVector3Array、置信度存 PackedFloat32Array）。
  * build/accept-frame-vectors.sh —— 编排：用参考实现重新生成向量并与锁定文件比对
    （参考实现变了却不同步向量即失败）→ 解包 → 包内解码比对 → 报告核对。

实测（**已发布**的 v0.2.3 资产重新下载后跑）：
  ✓ 锁定的向量与参考实现重新生成的结果逐字节一致
  ✓ 解码用例 12/12，逐点比对 396 个，解码差异 0 项
  ✓ 编码器差异 1 项，且全部属于「量化前恰好 .5」的取整边界
  关键点帧跨实现一致性验收全部通过

已测量并归类的一处差异（非缺陷）：JS Math.round 与 Kotlin（生产发送方）Math.round
对 -2.5 取 -2（半数朝 +∞），本端 roundi 取 -3（半数远离零）。Windows 是接收方，
encode() 只在自测/协议回归里用，故对产品无影响；脚本硬性要求这类差异只能出现在
取整边界用例上，否则视为新问题。若将来本端要当发送方，把 roundi 换成 floor(x+0.5) 即可。

踩坑（两处「看着通过其实没测到」，都写进任务文档）：
  1. 生成器第一版把「喂进编码器的输入」当成 points 写进向量 → 比对变成「比编码量化」，
     靠抽查数值才发现；现在向量同时含 inputPoints / f32InputPoints / f32Hex / points。
  2. 编码器比对一开始用 float64 输入编出的 hex 当基准（正数恰好 .5 那例整例 99 字节不同），
     实际只是输入从 float64 收敛到 float32 的量化差；改用同输入的 f32Hex 基准后，
     差异收敛到唯一一个真正的取整边界用例。教训：跨实现比对必须先统一输入。

package-release.sh 结尾把四条发布前验收一次列全；verify.sh 全绿（774 通过 / 0 失败）。
 2026-09-17 05:52:11 +08:00
zijunchiang cb1c293dcf chore(uid): 补探针脚本的 .uid（Godot 首次导入自动生成，与其他脚本一致入库） 2026-09-17 05:33:25 +08:00
zijunchiang 0ffb2d43bb test(ws): WebSocket 契约一致性验收（独立实现 × 包内 PoseServer）+ 故意不合规的负例服务端 
tests/test_pose_server.gd 用的是**同引擎内的客户端**（Godot WebSocketPeer），而真实
对端是 Android（Kotlin/OkHttp）——同引擎自测会共享同样的假设（超时判定、分包、
文本/二进制边界、关闭语义、子协议协商），于是「测试全绿」不等于「Android 连得上」。
契约 §7 也写明：静默超时要用保活避免，而不是靠重连掩盖；这句话只有用独立实现的
客户端实测才算验过。

新增三个文件：
  * build/integration/probe-ws.gd —— 把**包内** PoseServer 跑起来（--main-pack +
    只加载包内代码），把连接/控制帧/帧/断开事件汇总成 JSON 报告；自身不做判定
    （避免「用被测实现判定被测实现」）。支持 --stop-file 提前收尾。
  * build/integration/ws-client.mjs —— Node 实现的契约一致性客户端（用内置
    WebSocket，零依赖），逐条跑 §1 §1.1 §2 §3.1-§3.6 §5 §6 §7 的场景。
  * build/accept-ws.sh —— 编排：解包 → 起探针 → 等监听 → 跑客户端 → 收报告 →
    核对客户端看不到的那一半（frames_dropped / malformed_frames / 控制帧计数 /
    device_replaced / 关闭原因 / 静默超时消息带毫秒数与阈值）。

实测（**已发布**的 v0.2.3 资产重新下载后跑）：客户端 30 通过 / 0 失败 + 服务端侧
16 项事实全过。关键两条：
  * 保活对照：只发应用层 ping 持续 19 秒（> 静默超时 15 秒）连接**仍保持打开**；
  * 静默超时：完全不发数据 → close(1001,"timeout")，实测 15011 ms（阈值 15000 ms）；
另有：子协议协商、welcome 声明保活参数且 heartbeat(5000) < silentTimeout(15000)/2、
pong 原样回传 sentAtMs、同 deviceId 替换旧连接（1000 "replaced by new connection"）、
bye → 1000、协议不匹配 → bye + 1002、72 帧含故意跳号（服务端 frames_dropped=3）
与故意 100 字节非法帧（malformed_frames=1）。

反向验证：新增**故意不合规的服务端** build/integration/probe-ws-bad.gd
（welcome 不声明保活字段、不带 sessionId、收到 ping 不回 pong、不做 deviceId 去重），
对同一客户端 → 14 项 ✗、退出码 1，证明断言不是空转。

踩坑记录（已写入任务文档）：
  1. --script 模式下从无类型数组取 peer，peer.get_packet() 返回类型推不出来，
     var x := … 直接 Parse Error；
  2. 复核静默超时消息时写了否定式断言 !includes("静默超时 1")，把正确行为判成失败 ——
     断言应写成正向模式匹配；
  3. 探针原本只能按固定时长跑，编排脚本得猜时间；改成客户端跑完 touch stop 文件。

顺带：package-release.sh 结尾把三条发布前验收（产物自证 / WS 契约一致性 / 跨端集成）
一次列全。不影响已发布的 v0.2.3 产物，故不新发版本。
 2026-09-17 05:32:24 +08:00
zijunchiang a78a536476 feat(integration): 跨端集成验收（包内客户端 × 真实 Web 服务端）+ 修两个真实缺陷（v0.2.3） 
单测打的是假 HTTP 夹具，Web 端测试只验自己那一侧 —— 两端各自绿灯不代表契约字段
真的对得上。本版加了跨端集成验收，并在首次运行就抓到两个真实缺陷。

一、跨端集成验收（T-WIN-019）
  * build/integration/probe-integration.gd：只加载**包内**代码
    （`godot --main-pack <pck> --script <探针>` + res://），打真实服务端并逐项断言：
    /health 六个契约版本、catalog/version 指纹、catalog/export 解析出的四类资源与
    defaultModelId；**场景物理参数逐项比对**（重力/基础风/阵风/风坐标系/地面摩擦坡度/
    碰撞体/出生点/相机/环境）+ Wind.sample(0) + 场景 GLB 可下载；
    动作 NDJSON → 客户端解析帧数 == 服务端帧数、33 点、每帧服务端关节角、
    推导帧率 30 fps、时长 96.67 s；缩略图 PNG；模型 VRM 可下载。
  * build/integration/seed-catalog.mjs：用**真实素材**播种目录
    （示例文件/ 下的真 VMD → 内部标准 33 点；真 PMX → VRM；场景 GLB + 物理参数），
    并把期望值（含从 /health 取的契约版本）写成 JSON。
  * build/accept-integration.sh：编排「服务端可达 → 播种 → 包内探针 → 汇报」。
  实测（v0.2.3 包内 pck × 真实 Web v0.7.4 + 真实 MySQL）：全部通过。

二、探针抓到的两个真实缺陷
  1. `CatalogTypes.Motion` 缺 `thumbnail_url`：服务端 catalog/export 从
     data-models 0.6.0 起一直在发 thumbnailUrl（Model/Scene 都有），客户端默默丢掉。
     已补字段与解析（缺失为 ""），新增 tests/test_catalog_types.gd（4 项 20 断言）
     用**服务端真实报文形状**锁住三个资源类型的覆盖，并显式记录一处刻意不消费的差异
     （Model.usable/unusableReason —— 目录只下发可用模型，恒为 true）。
  2. `ApiClient._request()` 对**所有**响应无条件 `raw.get_string_from_utf8()`：
     数据本身没错（二进制路径返回原始字节），但每下载一个文件都会打印
     「Unicode parsing error … Invalid UTF-8 leading byte (N)」噪声，并把整个文件
     （模型可达数十 MB）解码成 String 拷贝后丢弃。改为只在需要文本时解码。

三、顺带修掉测试里的写死契约版本
  tests/test_api_integration.gd 断言 rest-api/websocket-keypoints/skeleton-topology
  均为 "0.1.0"。该用例只在服务端可达时才跑，平时一直 skip，所以契约升到 0.5.0 后
  没有任何地方发现它。改为从仓库 contracts/VERSION 读期望值并与 /health 比对
  （顺带成为「客户端契约快照 vs 服务端」的跨端校验）。

证据：verify.sh 全绿（820 通过 / 0 失败，比上版 +46，因为服务端在线时 API 集成组
真的跑了）；包内 pck 跨端集成探针全部通过；check-version/PE 版本资源 = 0.2.3。
 2026-09-17 05:18:03 +08:00