GOAI Episode 三维回放生成器

把 GOAI / RoboDojo 录制的机械臂 episode 变成可交互的 3D 回放网站（three.js，纯静态，无需构建）。

输入

• episode 文件（.hdf5），两种格式都支持、自动识别：
  • 官方数据集格式：state/left_arm_joint_states (n,6)、state/left_ee_joint_states (n,1)、 state/right_*、vision/cam_*/colors（每帧 JPEG 字节）、instructions；
  • eval-runner 录制格式：left_arm/joint、left_arm/gripper、cam_*/color 等。
• 模板站目录（piperx_replay 查看器），调用时显式传入路径。

工作流程

1. 组装站点骨架：

   python scripts/build_site.py --template <模板站目录> --out <输出目录> --task <任务标识> \
     --entry-file <入口.json>
   

   入口.json 是 UTF-8 编码的 {"key","zh","en","tag"}（任务显示名）。 中文名必须通过文件传入——Windows 控制台会把命令行里的中文损毁成乱码， 先用 Write 工具写好入口 json 再调用脚本。
2. 转换轨迹数据：

   python scripts/episode_to_json.py --episode <episode.hdf5> --out <输出目录>/data/<任务标识>_ep0.json
   

3. 抽取三路相机视频（需要 ffmpeg 在 PATH 上）：

   python scripts/episode_to_videos.py --episode <episode.hdf5> --outdir <输出目录>/video --task <任务标识>
   

   产出 <任务标识>_head.mp4、<任务标识>_left.mp4、<任务标识>_right.mp4。
4. 同一站点追加更多 episode：换不同的 --task 标识重复第 2、3 步， 再执行一次 build_site.py --no-copy --out <输出目录> --task <新标识> --entry-file <入口.json> 合并任务清单（不会删除已有数据）。
5. 本地预览：cd <输出目录> && python -m http.server 8123 → http://localhost:8123/?task=<任务标识>
6. 部署（可选）：用 ms-studio-deploy skill（static 类型）把输出目录发布到魔搭创空间。

注意事项

• 任务标识（task key）只能用英文小写、数字、下划线/连字符，且同一站点内唯一；
• 场景道具（碗、篮子等）只有官方六个任务自带；自定义任务默认只有机械臂和桌子， 除非另外加道具或编排文件（data/choreography_<任务标识>.json）；
• 夹爪约定：1 = 完全张开，0 = 闭合（映射为 joint7 = 值 × 0.05，joint8 镜像）；
• 视频固定 25 fps，与轨迹 JSON 逐帧对齐（两边 frames 数必须一致）；
• json 读写文件务必显式 encoding="utf-8"（Windows 默认 GBK 会损坏中文）。