Files
vibemake/docs/frontend-resource-integration.md
Jerry 1c837766cd feat: integrate robot assembly and simulation with resilient loading
Add backend-driven assembly and simulation experiences, MAKE branding, mobile rendering budgets and desktop-only CAD/PCB routes. Improve logo loading progress, document image recovery and URDF request handling; include dev packaging and regression coverage.
2026-10-30 18:38:39 +08:00

96 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 社区模型资源接口联调(2026-10-28)
## 最新兼容范围(2026-10-29,RP1 动作接入)
以下覆盖后文的早期版本说明。运行器依据用户最新提供的 `Downloads/vibemakersandbox/app/src/platform` 更新,保留社区的资源绑定、同源代理、按需加载、推理 Worker、控制调度和渲染预算。
- **RP1**:接入 episodic ONNX 动作、每个动作自己的观测历史/参考姿态、动作参考 `JSON + float32-le .f32`、逐关节 PD 参数及力矩速度限制。动作先等待站稳,再切换策略;结束或方向输入打断后过渡回基础行走。参考数据作为策略观测输入,不直接回放关节位置。
- **Microban**:支持 `render.body_visuals` 声明的自包含 GLB,并跟随 MuJoCo 身体位姿,保留 GLB 原材质。没有声明 body visuals 的旧包继续使用 MJCF 网格。
- **Microduck**:支持 `schema: 1 / adapter: microduck` 的新 `robot.json`,同时保留 `microduck-alpha-v1` 旧 manifest。新包须满足已接入鸭子适配器的关节顺序、观测和控制时钟契约;按声明的技能加载策略、展示动作按钮,未声明踢球时不展示球。
- API 文件清单仍是资源唯一来源;支持嵌套包路径和各文件独立 URL。增加 `.f32` 数据代理类型,不允许脚本。配置、策略、参考数据和网格均来自该项目的后台绑定,没有项目编码到样例的回退。
- 通用运行器的可选技能缺资源、不支持或初始化失败时,显示“部分动作暂不可用”并隐藏相应入口,基础行走仍可用;基础模型、主策略或必要模型依赖错误仍会阻止启动。
- 打开/重置保持静止;第一次按方向或可用动作即可开始。沿用小鸭子的深色暖色网格风格。手机控制按钮随空间排布;模型显示帧间插值不改变物理步长。
本次真实接口回归:`7pw11wsghcp3`(RP1)、`ppsx17fhhtzq`(Microban)、`gcw47xwyyhr8`(Microduck)。已在浏览器验证 RP1 跳舞/挥手及返回行走、小鸭子方向控制和坐下、Microban 方向控制与头部摆动;390×844 视口验证 RP1 动作按钮与模型可见。该尺寸检查不等于手机真机性能测试。
后端已绑定的当前资源包无需重新上传;刷新前台使用新运行器即可。任意新的控制器类型或不匹配的训练契约仍需明确适配,不能把“上传成功”等同于“可仿真”。
## 当前联调项目
- 名称:资源上传接口联调-20261028
- 项目编码:`b7drj14qq1nf`
- 社区地址:`http://localhost:8090/project/?id=b7drj14qq1nf`
- 管理后台使用 8091,前台默认端口已改为 8090;启动 `npm run dev`。
- 接口文档:用户提供的 `vibemake-api.md`。
- 社区接口仅返回可访问的已发布项目。该项目发布前为 404,发布后正常返回。
## 已对接的字段
| 详情字段 | 前台用途 | 缺少时 |
| --- | --- | --- |
| `urdfMainUrl` / `urdfBaseUrl` | 详情页主展示优先使用绑定的 URDF 和配套网格,支持关节交互;按 URDF 坐标系显示,不使用装配 JSON 的朝向 | 未绑定时使用整机 GLB |
| `modelGlbUrl` | 未绑定 URDF 时展示整机 GLB,GLTFLoader 保留原有颜色、材质、纹理 | 两者都无则不显示模型舞台 |
| `assemblyJsonUrl` | 装配步骤入口,沿用 v1 assembly 清单与步骤格式 | 隐藏 AI 装配入口(保留旧 `assemblyManifestUrl` 兼容) |
| `modelPartsFiles[]` | `relativePath` 匹配步骤清单中的零件路径,使用本条 `url` 加载,核对 `sizeBytes` | 步骤存在但所引用零件缺失时明确报错 |
| `modelPartsBaseUrl` | 后端提供的目录信息 | 实际加载优先按文件清单的 URL,不猜测上传批次 |
| `walkingResourcesBaseUrl`、`walkingResourcesFiles[]` | 运动目录及其完整文件清单,定位唯一 `robot.json` | 隐藏运动入口(保留旧 `walkingManifestUrl` 兼容) |
整机、零件、步骤 JSON 和运动资源可能位于不同 OSS 上传批次。不能用步骤 JSON 的 URL 所在目录拼接零件地址。后端已经返回的编码 URL 也不能整体重复编码。
本地 / 局域网资源经同源 `/__model_assets/` 代理,支持 `project-resources`;生产域名直连 OSS 时仍须配置相应 CORS。代理只允许指定 OSS 数据目录及资源类型,不代理上传的脚本。
## 装配
当前真实接口返回 275 个零件。JSON 决定零件对应关系、最终位姿、步骤顺序、进入方向与过渡时长,前台支持整体、逐步、自动播放 / 暂停和进度定位。每个零件保持 GLB 自身材质;整机与分件原本配色不同的地方不会被统一改色。
校验包括:步骤结构、路径、父子关系、位姿、文件大小;支持 Web Crypto 的环境还会核对清单中的 SHA-256。后台文件绑定不等于装配语义已经正确。
## 运动
本项目上传的是 Microban Robot Package,共 32 个文件;其中配置、MJCF、引用的 25 个 STL 和 1 个基础 ONNX 是运行依赖,许可证与来源记录无需在初始化时下载。配套配置定义了行走及头部摆动,没有踢球,因此没有足球和踢球入口。
当前新运行器支持:
- `schema: 1`、`adapter: generic`。
- MJCF 模型和配置中声明的全部资源,按原相对路径放入 MuJoCo 虚拟文件系统。
- 一个主 ONNX 控制器;观测拼接、关节顺序、动作缩放、参考姿态、PD / native 执行按配置执行。
- 可选 oscillator 关节动作;根据技能声明生成按钮。
- 3 维方向指令,按模型声明的速度范围及键位显示方向按钮。
基础校验后还会编译 MJCF、检查关节与观测 / 动作维度,并进行一次策略推理。缺少文件、LFS 指针文件、网页错误响应、不支持的控制器均给出错误,不会替换成其他机器人的样例。
**兼容范围**:当前接入并验证的是这个通用 Robot Package 与原有 `microduck-alpha-v1` 清单包。新的技能类型、其他 adapter 或任意 Python / ONNX 组合需要相应运行器,不能因上传成功就宣称可播放。新通用运行器根据 MJCF / STL 绘制物理模型,不把整机 GLB 自动绑定成可运动模型;整机和装配入口仍使用原 GLB 材质。
## 默认行为与性能
- 打开与重置均暂停,不自动行走;开始后按住方向键运动,释放即清除指令。
- 关闭弹窗销毁 iframe 及运行资源;失焦 / 隐藏页面暂停物理计算。弹窗打开时底层整机暂停绘制。
- 共用渲染预算,限制帧率 / DPR / 总像素,慢帧时自动降档。静止场景按需绘制。
- 模型依赖限制并发加载;仅在打开入口时加载大体积仿真引擎和策略。
- 通用运行器使用单线程 WASM 和串行控制调度;推理慢时不积压补帧,不保证所有低端硬件实时运行。
## 本次验证
- 真实已发布社区详情、整机 GLB、275 个零件与步骤 JSON 成功读取。
- 浏览器实际操作:装配播放推进至第 44 步,暂停、整体切换正常。
- 浏览器实际操作:仿真初始暂停;按住前进约 3 秒后行走约 0.55 m,释放后速度回到 0;头部动作可开启,重置关闭动作并归零。
- 390 px 手机视口下操作装配、运动方向键和重置;另检查 320 px 小屏布局。视口模拟不等于真机性能测试。
- `npm run test:experiences`:20 项通过。
- `npm --prefix sandbox test`:31 项通过,含新增触摸 / 键盘共存、失焦清空、暂停时不积存指令,以及引入运行器的策略 / 调度回归。
- `npm run build`:通过;生成 `dist/` 与 `dist.zip`。
这些结果只覆盖当前项目与声明的兼容格式。没有修改后端上传、发布状态或原始模型文件。
## 2026-10-29:统一为原小鸭子展示风格
- 两个运行器共用 `sandbox/src/embed/style.css` 与 `presentation.js` 的灯光、深色背景、暖色网格和边界墙。通用运行器不再单独显示蓝灰场景、速度/距离和另一套控制栏。
- 方向键、自动行走、继续/暂停、重置保持同一位置和外观;按各机器人声明保留额外动作。Microban 增加同样的自动行走入口,速度上限仍来自其 `robot.json`。自动行走是前台路线控制,底层步态仍使用上传 ONNX。
- 模型材质、动力学、策略没有因统一界面而改变。Microban 保留头部动作,无足球;小鸭子保留原球与原动作体系。关闭、失焦、隐藏页面均停止运动;重新打开和重置都暂停。
- 小鸭子也支持新的 `walkingResourcesFiles` 字段。每个清单文件匹配 API 返回 URL、校验大小,缺文件直接报错,不再假定所有文件与 manifest 位于同一目录。
- 本次资料在 `/Users/jerry/Downloads/机器人后台上传测试-20261029/`,分为两个独立目录,每个目录都有 `00-上传说明.txt` 和 `99-核对记录.json`。
- Microban:用户原整机 GLB、275 个原零件及 275 步展示 JSON、32 个原运动文件;已逐文件核对哈希。小鸭子:166 个运动文件,其中 manifest 声明的 164 个文件已核对哈希;另导出一个 70 网格实例、8 种原 classic 材质的整机 GLB。小鸭子原 GLB 是无内嵌材质的网格库,整机导出依据原运动学和参考姿态;没有杜撰装配工序。
- 当前后台按文件夹上传,按每份说明分别选择文件/文件夹,无须重新打 ZIP。小鸭子零件和装配步骤本次留空;Microban 可覆盖四个上传区域。
- `examples/upload-retest.html` 是不进入生产构建的本地验收页,文件来自本次整理的副本,不代表已经重新上传后台。
- 自动校验:资源 21 项、仿真 32 项通过,生产构建通过。原 Microban 项目仍读取已发布的真实 API;新的两个文件夹等待用户重新上传。
- 浏览器已核对两套桌面场景、自动行走、手动接管、暂停和重置;390 / 320 px 窄屏检查通过。小鸭子重置时让镜头与球的短暂动画完成后再停止绘制,并扩大竖屏取景范围以保留足球。视口模拟不等于手机/Windows 真机性能保证。