1c837766cd
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.
148 lines
9.0 KiB
Plaintext
148 lines
9.0 KiB
Plaintext
Vibemake 装配 / 行走资源包接入说明
|
||
协议版本:1;2026-10-28
|
||
|
||
一、两个字段
|
||
|
||
项目详情响应中的项目对象增加两个可空字符串:
|
||
{
|
||
"assemblyManifestUrl": "https://资源域名/experiences/项目ID/assembly/v1/manifest.json",
|
||
"walkingManifestUrl": "https://资源域名/experiences/项目ID/walking/v1/manifest.json"
|
||
}
|
||
|
||
没有相应功能返回 null。前端分别显示 / 隐藏两个按钮,不再根据项目编号或名称判断。
|
||
临时本地预览例外:后端未接入期间,本机 / 局域网的 Microban(ppsx17fhhtzq)详情页
|
||
会补上空的两个字段,打开 275 分件装配和现有 Microduck 行走样例;后端有效地址优先。
|
||
此配置仅在 js/project-experiences.js,正式域名和其他项目不使用,可在联调完成后删除。
|
||
字段是 ZIP 解压后的 manifest.json 地址,不是 ZIP 下载地址、GLB 地址或 HTML 页面地址。
|
||
保存接口也需要接受这两个字段;详情接口必须返回,列表接口可选。
|
||
主展示区的 urdfMainUrl 保持独立。前端不会在字段为空时回退到固定的演示资源。
|
||
|
||
二、后台上传与发布
|
||
|
||
项目编辑页设置“AI 装配资源包”“行走演示资源包”两个 ZIP 上传位,均允许清空。
|
||
1. 上传到临时区。拒绝绝对路径、..、软链接、重复路径和解压炸弹,在解压过程中限额。
|
||
2. 解压到独立版本目录,保留路径、文件名和大小写。本次两个 ZIP 根目录就是 manifest.json。
|
||
3. 检查 schemaVersion、kind、files 中每个文件的存在性、实际 bytes、SHA256 和内部引用。
|
||
4. 验证模型 / 配置。行走策略还需算法团队在隔离环境确认动力学和推理结果。
|
||
5. 完整发布到对象存储 / CDN 后,再将 manifest 地址写到项目字段。失败时保留旧版本。
|
||
|
||
本版输入上限:清单 2 MB、资源 1000 个、清单所列资源解压总计 200 MB。
|
||
后端解压限额也要计入 README、许可证等文件,不能先全部解压再检查。
|
||
装配包单个 GLB 不超过 50 MB、实例不超过 1000;这不是手机流畅度保证。
|
||
|
||
推荐目录:/vibemake_dev/experiences/<projectId>/<kind>/<version>/。
|
||
正式目录可用 /vibemake/experiences/...。这两种 linkerbot OSS 路径已接入本地 / 局域网代理。
|
||
其他资源域名可直接读取,但需要配置 CORS。代理不会转发任意域名。
|
||
资源必须支持 GET、正确 Content-Type(JSON / XML / GLB / ONNX / STL / 音频等)和 HTTPS。
|
||
公开资源使用匿名读取,当前请求不携带 Cookie;只给 manifest 签名不会授权同目录其他文件。
|
||
私有资源的逐文件签名、令牌刷新等需要扩展协议,本版不支持。
|
||
每次更新发布新版本目录,避免缓存混用;不要只发布清单、遗漏网格、贴图或策略。
|
||
ZIP 不允许指定浏览器脚本或 iframe 入口,上传目录按数据资源管理,不作为可执行网页发布。
|
||
|
||
三、AI 装配包
|
||
|
||
microban-assembly.zip:
|
||
manifest.json
|
||
models/robot.glb
|
||
README.txt
|
||
|
||
模型是用户提供的“机器人.glb”,文件和材质参数未修改。
|
||
GLB SHA256:5976d400a8f87877fee0be58731e13b8c1db84271b24d35ed889f255e56f894a
|
||
网页使用自身的光照、环境反射和色调映射,最终明暗与 Blender 环境可能不同。
|
||
当前包是完整模型,steps 为空,仅展示总装,不凭空生成安装工序。
|
||
|
||
未来多零件仍然只用 assemblyManifestUrl,不需要再增加字段。
|
||
包内放多个 GLB,manifest 指定实例、层级、最终位置和步骤。例如:
|
||
{
|
||
"schemaVersion": 1,
|
||
"kind": "assembly",
|
||
"title": "示例机器人",
|
||
"unit": "meter",
|
||
"displayQuaternion": [0,0,0,1],
|
||
"files": [
|
||
{"path":"parts/body.glb","bytes":实际字节数,"sha256":"实际64位小写哈希"},
|
||
{"path":"parts/arm.glb","bytes":实际字节数,"sha256":"实际64位小写哈希"}
|
||
],
|
||
"parts": [
|
||
{"id":"body","file":"parts/body.glb","position":[0,0,0]},
|
||
{"id":"left","file":"parts/arm.glb","parentId":"body",
|
||
"position":[0.12,0.2,0],"quaternion":[0,0,0,1],"scale":[1,1,1],"installOffset":[0.08,0,0]},
|
||
{"id":"right","file":"parts/arm.glb","parentId":"body",
|
||
"position":[-0.12,0.2,0],"quaternion":[0,1,0,0],"installOffset":[-0.08,0,0]}
|
||
],
|
||
"steps": [
|
||
{"id":"s1","label":"安装主体","parts":["body"]},
|
||
{"id":"s2","label":"安装左臂","parts":["left"]},
|
||
{"id":"s3","label":"安装右臂","parts":["right"]}
|
||
]
|
||
}
|
||
上述 bytes、sha256 为文字占位,实际清单必须填真实数值和哈希。
|
||
|
||
制作约定:
|
||
- 使用静态、自包含、未压缩 GLB 2.0,贴图与缓冲区嵌入 GLB。
|
||
暂不支持骨骼动画、Draco / Meshopt 压缩、KTX2 贴图,需要时再接解码器。
|
||
- 统一单位米、GLB Y-up 坐标;源模型方向不同时可用 displayQuaternion 整体修正。
|
||
- parentId 省略 / null 表示总装根节点;position、quaternion、scale 相对父节点。
|
||
- quaternion 顺序 x,y,z,w,必须归一化;缺省 [0,0,0,1];scale 缺省 [1,1,1]。
|
||
- 保留正确局部原点。每个 GLB 如果已在总装坐标中,使用零位移根节点即可。
|
||
不要把各个 GLB 单独居中 / 缩放后丢失定位信息。前端只对整体统一取景。
|
||
- id 唯一,仅英文字母、数字、横线、下划线。同一 GLB 可复用为多个螺丝等实例。
|
||
- steps 可为空:显示整体。提供步骤则覆盖全部零件,每个各装一次,父零件先装或同一步装。
|
||
- installOffset 是安装开始位置相对最终位置的偏移,默认 [0,0.08,0]。
|
||
前端已实现逐步装配 / 查看整体、前后步骤切换,以及新增零件平移到最终位置。
|
||
本版不处理拧螺丝旋转、复杂轨迹、碰撞检测或 CAD 装配约束。
|
||
- 大型总装须控制面数和纹理尺寸;后续可增加分级模型与分步加载。
|
||
|
||
多个 GLB 不能自动说明如何安装。作者 / CAD 导出工具需要提供位姿、层级和步骤。
|
||
未来 AI 可以生成同一份 manifest,经作者校对后上传,不影响详情接口。
|
||
|
||
四、行走包
|
||
|
||
microduck-walking.zip:
|
||
manifest.json 类型、运行器版本、控制配置入口、文件清单
|
||
controller.json 关节顺序、默认姿态、维度、控制频率等
|
||
robot/mjlab/ 物理模型 XML、网格、运动学 JSON、GLB 等
|
||
policies/ 已训练、已导出的 ONNX 策略
|
||
assets/ 场景、音效等既有资源
|
||
LICENSE / NOTICE / UPSTREAM.md / README.txt
|
||
|
||
这是 Microduck 的资源,不是 Microban 的行走策略。
|
||
可临时挂在测试项目联调,但正式发布应绑定真正对应的机器人项目。
|
||
GLB 只解决显示;物理模型、关节映射、观测与动作语义必须和策略匹配。
|
||
|
||
运行流程:离线训练 -> 导出 ONNX、匹配的物理模型与配置 -> 打包上传 ->
|
||
前端固定运行器读取资源 -> MuJoCo WASM 仿真 + ONNX Runtime 推理 -> Three.js 显示。
|
||
不要上传 Python 训练环境、.pt/.pth 检查点、node_modules、浏览器脚本或 WASM 引擎。
|
||
训练不在浏览器进行。
|
||
|
||
目前只支持 runtimeProfile: microduck-alpha-v1、robotId: microduck-alpha、autoWalk: false。
|
||
文件路径按运行器约定保留,不可随意改名。14 维动作、61 维观测、13 维指令;
|
||
物理步长 0.005 秒、每 4 步推理一次(50 Hz)。controller.json 不匹配会拒绝启动。
|
||
ONNX 启动检查单输入 / 单输出、输出形状、有限数值及不同输入下的响应。
|
||
这些检查不能证明策略稳定,仍需算法团队验证真实的模型参数和控制效果。
|
||
其他机器人、其他观测预处理 / 动作后处理需要新增平台运行器适配,
|
||
不能只改 runtimeProfile、维度数字或 GLB 就兼容。协议可扩展,现有算法并非通用。
|
||
|
||
五、前端部署边界与验证
|
||
|
||
已接入两个字段、清单校验、动态资源目录、装配步骤和加载错误重试。
|
||
公共协议:js/experience-packages.js;行走适配:sandbox/src/game/package-config.js。
|
||
资源 SHA256 的真实核验由上传后端完成,浏览器不逐文件重算哈希。
|
||
浏览器校验结构和大小信息,装配 GLB 还检查实际字节数与自包含要求。
|
||
|
||
首次安装:npm --prefix sandbox ci
|
||
构建运行器:npm run build:walking
|
||
完整部署:npm run build,将 /play/microduck/ 与其他站点文件一起部署。
|
||
两个 ZIP 不包含运行器;上传包不能替代部署本次前端代码。
|
||
|
||
重新生成交付包:npm run package:experiences
|
||
生成多零件测试积木:node scripts/experience-fixtures.mjs
|
||
协议回归:npm run test:experiences
|
||
渲染 / 控制回归:npm --prefix sandbox test
|
||
本地服务:npm run dev
|
||
联调页:http://localhost:8091/examples/experience-preview.html
|
||
联调页使用真实加载组件,可填写后端地址,不修改远端项目;不包含在正式构建中。
|
||
|
||
两个 ZIP 已做解压与跨源加载验证。手机尺寸下检查界面,不等同于低配手机 / Windows 实机性能验收。
|
||
真实 OSS、上传接口和后端字段需要后端上线后联调;本地通过不代表生产接入已完成。
|