docs(win): 任务说明、DSH 约束与交付文档

2026-09-14 20:04:54 +08:00
parent 315cf79708
commit a83e4f6a1f
15 changed files with 975 additions and 0 deletions
@@ -0,0 +1,46 @@
+# T-WIN-004 239 字节帧反序列化
+
+- **状态**：done
+- **依赖**：T-WIN-001
+
+## 目标
+
+按契约实现 239 字节关键点帧的编解码。
+
+## load
+
+```
+DSH.md
+contracts/websocket-keypoints.md   # 锚点：§2 二进制帧（冻结）
+contracts/skeleton-topology.md     # 锚点：§4 坐标系
+src/net/keypoint_frame.gd
+```
+
+## 帧布局（契约冻结）
+
+```
+偏移  长度  字段
+0     2     magic    u16 = 0x4F44 ('OD')
+2     1     version  u8  = 1
+3     1     flags    u8  bit0 镜像 bit1 低置信度 bit2 上半身
+4     4     frame_id u32 LE
+8     231   keypoints 33 × 7B：s16 x, s16 y, s16 z, u8 conf
+合计  239
+```
+
+## 交付物
+
+`src/net/keypoint_frame.gd`：`PoseFrame` 内部类 + `decode` / `encode` / `validate` / `from_json_dict`。
+
+## 关键实现
+
+- 归一化系数统一 32767，与 opendance-web 的 TypeScript 参考实现逐位对齐
+- 编解码往返误差 < 1e-4（定点精度 1/32767 ≈ 3.05e-5）
+- `unmirrored_points()` 按 flags.bit0 翻转 x
+- 低置信度阈值 0.5：`is_reliable()` 与 `compute_low_confidence()`
+- 极值（±1.0）不溢出 int16
+
+## 验收
+
+`tests/test_keypoint_frame.gd`：常量与契约一致、239 字节、magic/version/flags/frame_id、
+往返精度、错误长度/magic/版本拒绝、极值、镜像翻转、置信度阈值、JSON 调试帧。