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.
10 KiB
社区模型资源接口联调(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 真机性能保证。