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.
25 KiB
行走演示上传与展示规范:最低必传项 + 可选功能
修订日期:2026-10-28
后台交接项目:/Users/jerry/linkhand/vibemake-admin
社区前台:/Users/jerry/vibemake-site
参考运行器:/Users/jerry/Downloads/vibemakersandbox/app/
本版为后续实施约定。后台固定展示最低必传项,上传者自行选择额外功能;前台根据实际配置且验证通过的功能显示操作与道具。不能按机器人名字、文件名猜功能,也不能要求每个机器人都上传小鸭子的全部策略。
本文取代上一版“先识别机器人,再显示要求”的页面设计。以下规则、发布协议和前端适配属于待实施内容;不是现有社区已经支持全部功能的声明。整机 GLB、零件 GLB、装配步骤保持原有流程。
1. 先把必传和选填定清楚
“行走演示”整个模块选填。项目没有配置行走演示时,社区不显示行走按钮;不影响整机和 AI 装配展示。
一旦启用行走演示,本期采用 MJCF 物理仿真 + ONNX 行走策略。最低要求如下,不按机器人型号改变类别:
| 上传项 | 是否必须 | 上传者需要准备什么 | 页面说明 |
|---|---|---|---|
| 机器人控制配置 | 必传 | robot.json,包含模型路径、关节对应关系、观测、动作、控制参数及初始姿态 |
由该机器人的模型/算法工程导出或提供;后台表单可辅助填写,不能靠上传 GLB 自动生成有效策略 |
| 物理模型 | 必传 | 配套的 MJCF XML,如 model.xml |
定义机器人关节、碰撞、质量、执行器等;普通 GLB、URDF 改后缀不能替代 |
| 模型引用文件 | 有引用就必须传齐 | 上述模型使用的网格、贴图、include 文件等,可多选/上传文件夹 | 数量不固定;模型没有外部依赖时,无需另传文件,不要求凑够多少个 STL |
| 基础行走策略 | 必传,至少一个配套策略 | 一个能在该控制配置下运行的 ONNX,如 policies/walk.onnx |
本期最低模式是一个 primary ONNX;更多动作的策略按下表选填,不要求固定 7 个 |
| 发布清单 | 系统生成,不让用户上传 | manifest.json,资源路径、字节数、SHA256、已发布功能等 |
上传检查后自动生成,用户不用手写文件索引 |
文件名除约定入口外可自定义,以配置中的引用为准。资源的来源和授权说明随原资源保留,不用为了平台格式重复制作已有说明。
以下均不是通用必传项: 整机 GLB、kinematics.json、单独的 controller.json、足球模型、球场、踢球/翻滚/起身策略、训练代码、训练日志。GLB/映射只在选择需要它们的显示方案时成为该方案的必备资源;基础 mjcf_visual 直接使用物理模型的可视几何。
只有 GLB 可以做外观或装配展示,不能直接生成强化学习行走。Python、.pt、.pth 也不能直接替代本期浏览器支持的 ONNX。最低文件清单固定,不等于任意模型和任意策略可以混搭。
2. 可选功能:选哪项,才补哪项
后台把以下项目做成可勾选的功能卡片。每项默认关闭;不勾选时不要求资源,不产生缺文件错误。
| 功能 ID | 上传者看到的功能 | 选中后必须具备 | 可以不传的内容 | 前台增加什么 |
|---|---|---|---|---|
head |
头部摆动 | 头部关节组、支持的控制器和参数;使用 ONNX 时提供引用的策略 | 使用平台已支持的参数控制器时,无需额外 ONNX | 头部摆动开关 |
sit_stand |
坐下/站起 | 配套动作控制配置和其引用的策略;声明支持的动作及切换条件 | 不要求同时具备跌倒起身 | 已验证的坐下/站起操作 |
roll |
翻滚 | 配套控制配置、引用的策略和动作结束/恢复行走规则 | 踢球、足球和起身策略 | 翻滚按钮 |
kick_left |
左脚踢球 | 左脚踢球控制配置、引用的策略、兼容的足球物理预设 | 右脚踢球策略、单独的足球 GLB | 足球 + 左脚踢球按钮 |
kick_right |
右脚踢球 | 右脚踢球控制配置、引用的策略、兼容的足球物理预设 | 左脚踢球策略、单独的足球 GLB | 足球 + 右脚踢球按钮 |
recovery |
跌倒起身 | 起身控制配置、引用的策略、适用姿态与触发规则 | 没有此功能时,基础演示使用手动重置 | 起身按钮;只有明确配置才自动触发 |
ground_pick |
俯身拾取 | 拾取控制配置、引用的策略及所需道具配置 | 不要求其他机器人具备拾取功能 | 拾取操作及该功能所需道具 |
rollers |
滚轮行驶 | 配套滚轮物理模型/模型变体、依赖、控制配置与行驶策略 | 不要求顺带上传蹲伏策略 | 切换滚轮模式及其控制 |
roller_crouch |
滚轮蹲伏 | 已启用 rollers,加蹲伏控制配置及引用的策略 |
与其无关的双足动作策略 | 滚轮模式下的蹲伏按钮 |
visual_model |
高精度显示模型 | 额外 GLB 及当前渲染器要求的关节/节点映射,必须与物理模型匹配 | 不需要高精度显示时整项不传 | 使用该模型显示,保留原材质和颜色 |
动作策略可以复用同一个已验证的文件,不规定“一项动作一定另传一个文件”。平台内置控制器确实支持该动作时,也可以只配置参数。不能通过省略策略或填一个功能名称,就声称运行器具备对应动作。
动作控制配置不只是按钮名,至少要明确:执行哪个控制器/技能、控制哪些关节、观测与动作约定、触发条件、执行结束条件以及如何返回基础行走。沿用 robot.json 和运行器已有配置结构;后台负责把功能绑定到实际技能,不能从 ONNX 文件名推测这些含义。
当前下载的 generic 运行器只有一个 ONNX primary 和独立关节的 oscillator overlay。它尚未支持通用踢球/翻滚/起身状态切换。功能卡片是统一的产品约定,未部署对应处理器的项目显示“需要播放器适配”,可以留草稿,但不能标记可发布。 不得为通过检查要求上传其他机器人的策略。
足球显示规则
- 左、右脚任意一项踢球功能配置完整、通过检查并发布,场景显示 一个 足球;只显示实际支持的踢球按钮。
- 两项都没有,默认不创建足球,不显示踢球、重置球、球视角等相关操作。
- 足球由平台提供基础外观和物理预设。上传者不用为了踢球再制作一个 GLB;所选物理预设的半径、质量、接触参数、出生位置等必须与训练场景兼容,并通过试运行。
- 左右脚同时启用时必须使用兼容的球设置;有冲突时在后台报错,不能静默覆盖其中一套。
- 自定义足球 GLB 属于外观选填项,只改变外观,不能据此推断物理参数或让机器人自动学会踢球。单独多传一个球文件,不等于启用踢球功能。
- 平台球场、地面、灯光、普通相机与重置按钮由播放器提供。特殊环境若是策略运行的必要条件,应作为所选功能的依赖明确配置。
3. 后台页面:打开就能看懂,无需先上传再猜要求
建议主入口采用 分项上传,ZIP 放在“已有资源包”的快捷导入入口。两种方式最后都进入同一草稿和校验流程。
行走演示 选填
基础行走只需准备下面四项。其他动作按需添加,不用全部上传。
基础行走 · 必须准备
① 机器人控制配置 必传 [选择 robot.json] [查看说明]
② 物理模型 XML 必传 [选择文件]
③ 模型引用文件 有引用必传 [选择多个文件] [选择文件夹]
④ 行走策略 ONNX 必传 [选择文件]
额外功能 · 选填
□ 头部摆动 □ 坐下/站起 □ 翻滚 □ 跌倒起身
□ 左脚踢球 □ 右脚踢球 □ 俯身拾取
□ 滚轮行驶 □ 滚轮蹲伏 □ 高精度显示模型
[已有资源包?导入 ZIP] [下载文件要求]
[检查资源并预览] [保存草稿]
勾选“左脚踢球”后才展开:
左脚踢球
动作控制配置/技能绑定 必填 [选择或导入配套配置]
踢球策略 按配置必传 [选择 ONNX / 复用已上传文件]
足球物理预设 必选 [平台预设 ▾] [查看参数]
自定义足球外观 选填 [选择 GLB]
前台将增加:足球、左脚踢球。
不把“7 个策略全部必传”换成“识别后决定”;默认界面就显示固定的基础类别与明确的选填卡片。后台解析文件的用途是验证用户的配置与引用是否成立。
上传交互约定:
- 每项有“未提供/已选择/已上传/检查通过/需要处理”的明确状态,并显示缺少的具体文件和归属功能。服务未接入时只显示“已选择,尚未上传”,不显示检查通过。
- 配置由模型/算法人员提供,普通上传者按栏位选文件。提供说明和真实示例,不让普通上传者手写关节张量、策略状态机或文件哈希。
- 分项上传必须保留相对目录与引用;同名文件不能静默覆盖。改变文件名后同步更新引用并重新校验。
- ZIP 是批量导入容器,最终解压成相同的资源目录。导入已声明的功能绑定并展示给用户确认;无绑定的额外文件保留为“未用于展示”,不凭文件名激活功能。
- 多传文件允许存为草稿素材。只有被选中功能引用的资源才进入发布清单并由前台加载,不因多传素材就增加前台负担。
- 可选功能取消勾选后保留其草稿文件,停止计入本次发布要求。发布编译器必须同步去除技能、输入绑定和资源引用,并重新校验完整配置,不能只删一个 ONNX。
- 新版协议不要让上传者再上传一份
manifest.json;系统自动生成。导入已有包的 manifest 只能作为导入资料,文件大小、哈希和检查结果必须重新计算。
4. 发布协议:一个项目地址,按功能描述展示
社区详情接口继续使用 walkingManifestUrl;没有演示返回 null。后台接收 ZIP 后解压、检查、预览、发布,返回 manifest 地址,不返回 ZIP 地址或开发机路径。
建议在此前拟议的 transport v2 中明确 capabilities。它放在发布层,避免往现有严格校验的 robot.json 随意塞 UI 字段。
{
"schemaVersion": 2,
"kind": "walking",
"runtimeProfile": "robot-package-v1",
"entry": "robot.json",
"autoWalk": false,
"capabilities": [
{ "id": "walk", "skillIds": ["walk"] },
{ "id": "head", "skillIds": ["head"] }
],
"props": [],
"files": []
}
这是 协议形状示例,尚未实现,不能直接当可运行包上传。files 发布时必须填入真实资源索引,不得为空。以上能力示例对应 Microban 配置中的 walk 和 head;没有踢球,自然没有足球。
字段约定:
| 字段 | 规则 |
|---|---|
entry |
指向本版本的机器人配置,基础行走及选中的技能配置必须闭合 |
runtimeProfile |
平台已部署的可信运行协议,不能是上传的 JS/HTML 执行入口;这里的 robot-package-v1 是拟议标识 |
capabilities |
必须包含且仅包含一个 walk 条目;其余为已选择、验证通过且准备发布的功能;ID 唯一 |
capabilities[].skillIds |
指向 robot.json.skills 的真实技能 ID,可多对一或一对多;功能 ID 与技能 ID 不必同名;visual_model 使用渲染绑定而非技能绑定 |
| 功能依赖 | 来自平台固定目录,如 roller_crouch 依赖 rollers;发布时强制闭合;机器人名称不参与决定必传项 |
props |
功能依赖的场景对象配置。踢球使用唯一的 football:包含经验证的物理预设及其固定版本;自定义外观另有资源引用。没有需要它的功能则不生成该对象 |
files |
本版本入口和已发布功能的完整依赖索引:path、bytes、sha256;共享文件只计一次;平台内置资源用固定版本预设,不让用户重复上传 |
autoWalk |
固定 false;打开/重置时不自动发出行走或可选动作命令 |
发布层功能不另复制 ONNX 路径,控制配置仍由技能持有,避免两处定义不一致。后台可存各功能的草稿启用状态与校验报告;发布清单中只输出实际可用的功能,不发布一堆 enabled:false 占位按钮。
若启用左脚踢球,发布层增加 kick_left → 对应技能 ID 的绑定及一个 football 对象;技能的策略、触发/退出规则和足球物理配置必须通过同一运行器验证。不能只增加能力字段就跳过控制器适配。
已验证的功能清单是能力上限。前端还要检查自身运行器支持与设备加载结果,不能仅凭 manifest 的声明把任意上传内容当作可执行能力。
5. 后台最低要求的验证与发布规则
“最低要求”指只强制基础行走,不代表只验扩展名或文件头。
基础检查
- 配置结构和跨字段关系有效;基础模型、依赖和行走策略齐全。检查真实文件内容、SHA256、合法路径、ZIP 展开体积/条目数;Git LFS 指针和 HTML 错误页不能当模型数据。
- MJCF 能编译,关节/sensor/body/执行器和 VFS 引用匹配。配置和 ONNX 的关节顺序、输入输出名、类型、维度、归一化与动作缩放匹配;试推理结果有限。
- 维度按这个机器人的配置计算,不固定 61/14 或 63/18。引用文件完整,不等于能正确控制。
- 用对应运行器进行初始化、走/停、所声明的方向控制、重置和资源释放预览。打开时不自动行走;若零速度策略不能稳定站立,必须明确暂停展示,不能标为已验证站立。
可选检查
- 未选择的功能不检查其策略是否存在,也不阻止基础发布。
- 每个选中功能分别检查控制器支持、资源闭包、关节所有权、依赖、状态切换和试运行。某项需要的共用模型/策略也是基础依赖时,失败必须算基础失败。
- 某个可选功能缺文件或暂不支持:保存为草稿,明确“这项暂不可发布”。允许用户点击 “仅发布已通过的功能”,展示最终功能列表后发布;不能静默删功能冒充整包通过。
- 发布时重新构建并校验裁剪后的配置、输入绑定和资源索引,不能保留对失败功能的悬空引用。某个旧运行器仍强依赖可选策略时,必须先改运行器;不能仅修改校验器放行。
- 发布生成不可变版本及实际能力快照;失败不能覆盖正在使用的有效版本。检查报告须绑定资源版本/哈希,上传新文件后旧报告作废。
报告建议按 scope: "base" | "feature" 和 capabilityId 分组,逐项包含 code、path、status、message。例如:
基础行走 通过 可以发布
头部摆动 通过 使用内置控制器,无需额外策略
左脚踢球 未通过 缺少 policies/kick-left.onnx
右脚踢球 未启用 无需上传
[补充左脚踢球资源] [仅发布基础行走和头部摆动] [保存草稿]
后台接受文件、完成静态检查、通过运行预览、发布到社区是不同状态,不能全部叫“上传成功即可演示”。
6. 前台最高适配:按能力组合,而不是按机器人写分支
前台应实现功能注册表和对应处理器,按“已发布功能 ∩ 当前运行器支持”生成操作,并根据资源加载状态决定能否执行。尚未下载的可选策略显示可点击加载的操作;加载失败才停用该功能,不能因为使用懒加载而把全部可选按钮藏起来。新增机器人在支持的控制契约内不需要改一套页面。未支持的新控制方式仍需开发运行器,不能承诺任意 ONNX 都能运行。
| 项目发布内容 | 前台展示 |
|---|---|
| 没有行走配置 | 隐藏行走演示按钮 |
| 只有基础行走 | 模型、开始/暂停、重置与实际支持的方向控制;没有足球及其他动作 |
| 行走 + 头部摆动 | 增加头部摆动控制 |
| 行走 + 左脚踢球 | 增加一个足球、左脚踢球和重置球;没有右脚按钮 |
| 行走 + 左右脚踢球 | 一个足球、两个踢球按钮;不重复创建球 |
| 行走 + 翻滚,无踢球 | 增加翻滚;不显示足球 |
| 行走 + 多项通过的功能 | 按功能分组展示全部已支持操作;手机使用“更多动作”面板 |
加载与交互约定:
- 首次只加载基础资源,动作策略按需加载并缓存;已发布的可选动作可先显示按钮,点击后提示加载,加载完成前不执行。不要在启动阶段
Promise.all强制加载所有可选策略。 - 控制参数、可移动方向和限速来自已验证配置;不硬套小鸭子的轴数、键位、关节数量或动作菜单。参数为零或不支持的方向不显示可用控制。
- 开场不自动走、不自动踢、不自动摆头。切后台、关闭弹窗、失焦、触摸取消时清空输入;恢复时不沿用此前按住的方向,也不自动重播动作。
- 一项可选动作下载失败,应提示该动作不可用,基础行走继续可用;相关道具只在仍有可用依赖功能时保留。修改物理世界若需要重建,先暂停并重置。基础资源失败才展示整体失败。
- 动作执行失败不能带着残留控制量继续跑。运行器必须具备经验证的结束/取消和恢复基础状态逻辑;无法安全恢复时暂停并提供重置,不宣称所有异常都能无缝降级。
- 对未支持的能力 ID 显示后台适配提示,公开前台不展示不可用按钮;不能因一个未知选填字段导致已支持基础演示崩溃,也不能忽略它对基础控制的实际依赖。
- 高精度 GLB 保持源文件的材质、贴图、颜色;性能降级优先降低像素比、阴影、抗锯齿和显示帧率。不要擅自改材料或用外观模型替换关节不兼容的运动模型。
手机与普通 Windows 性能
- 控件根据可用功能布局;触控目标建议至少 44px,方向控制不遮挡主体,多余动作折叠为面板。没有额外功能时不占用这部分空间。
- 限制渲染像素比与分辨率,优先降低渲染成本;仿真步长和策略调用频率属于控制契约,不能为了流畅随意改动。
- 关闭/离屏暂停;按需下载可选策略,切换项目或关闭时释放 WebGL、ONNX session、事件监听和未完成请求,避免重复创建仿真循环。
- 达不到控制实时性时暂停并提示性能不足;若另行提供录像可切换查看,但不能把视频当实时策略演示。不得在低性能设备上默默减速控制仍标“正常”。
- 验收至少包含实际手机和普通 Windows 电脑;新版通用运行器不自动继承旧社区已做的移动端优化。
7. ZIP 只是批量导入方式
一个基础包的准备示意:
robot.json 必传:控制配置,含基础行走技能
model.xml 必传:物理模型,名字可自定义
assets/ 有引用才必传:模型所需网格、贴图、include 等
policies/
walk.onnx 必传:一个配套的基础行走策略
SOURCE.md / LICENSES/ 保留所用资源的来源说明
需要踢球等功能,再加入对应策略与配置;不需要的文件不用凑。发布清单由后台生成,不在上传者的最低准备清单里。
ZIP 内路径与配置一致,保持文件夹结构。没有配置与功能绑定的 ZIP 可以作为素材导入草稿,但不能直接发布。社区拿到的是解压后的 manifest 和受控资源 URL,ZIP 本身不是可以“自动走起来”的程序。
沿用已知运行器,上传包不能携带执行用的 JS、HTML 或任意自定义代码。文件大小、条目数与路径等限制由服务端统一执行,前台重复做必要边界校验。
8. 当前实现差距:必须同步修改,不能只换文案
| 位置 | 现状 | 需要做的调整 |
|---|---|---|
后台 WalkingUploadGuide.tsx、WalkingChecklist.tsx |
旧版小鸭子固定要求 | 固定基础清单 + 可选功能卡片 + 按功能的检查报告 |
后台 walkingUpload.ts 与上传配置 |
固定 7 个策略等 | 采用本规范的功能目录、依赖和资源绑定;补齐分项上传、打包和发布流程 |
社区 js/experience-packages.js、js/walking.js |
只接 Microduck v1 及专用页面 | 保留旧版本兼容,新增 v2 清单与能力驱动入口;不能把 v2 直接交给 v1 校验器 |
下载版 generic 运行器 |
ONNX primary + oscillator overlay | 接入动态包;为额外动作增加支持声明、状态切换、资源隔离和界面处理器 |
| 下载版 Microduck 适配器 | 启动强制 7 个策略,另有滚轮与固定路径依赖 | 将可选策略加载与相关初始化拆开,基本行走只依赖必需资源;之后才支持只上传基础小鸭子包 |
| 模型包加载 | 下载版要求资源同源并使用静态列表 | 接入项目级 manifest,采用同源资源代理或明确实现允许的资源源策略;仅配置 CORS 不够 |
| 发布路径 | Microduck 有 ../../ 和固定站点资源 |
打包完整依赖,调整路径;归一化后必须位于版本包根目录,不能全局放开路径穿越 |
旧 Microduck v1 包仍按旧运行器要求读取,不能把其 7 个启动策略简单删除。新上传规则与新播放路径一起落地后,才实现“只传基础行走”。旧版只是兼容分支,不是所有新机器人的必传标准。
本地临时预览还会给 Microban 项目补上小鸭子演示。正式验收“未配置则隐藏”“只显示本项目能力”时要关闭该回退,避免把示例当作后台已发布数据。
9. 结合最新工程验证的两个例子
- Microban:
robot.json、model.xml、配置引用的 25 个 STL、1 个walk.onnx;头部摆动用内置 oscillator,无额外 ONNX。不要求 GLB、kinematics、单独 controller、踢球、翻滚、起身。25 是这个模型的引用数,不是通用要求。 - Microduck: 当前代码声明 9 个策略、旧启动加载其中 7 个,属于现有实现的耦合。目标是基础行走、踢球、翻滚等按上述功能目录拆开;不能让其他机器人补齐这些动作,也不能声称现有鸭子代码已经支持删掉它们。
当前下载的 Microban 副本有 26 个 Git LFS 指针:25 个 STL 和 1 个 ONNX 尚非真实二进制。本次可确认配置结构与依赖关系,不能据此标为已跑通的基础示例;需补齐真实文件后试运行。
2026-10-28 上传资料整理补充:已从来源记录指定的 Rhoban/microban 提交补齐这 26 个真实文件,并逐项核对原记录的大小和 SHA256,保留下载目录原样。整理后的资源在 /Users/jerry/Downloads/Microban-后台上传资料-20261028/;运动 ZIP 包含基础行走和内置转头。已通过 MJCF 编译、25 个网格引用检查和 ONNX [1,63] → [1,18] 实际推理检查;后台到社区的行走联调仍待接入,具体记录在该目录的 06-核对资料/。
配套资料:
- 后台要求与功能目录 JSON:本文的机器可读交接配置,不是已上线接口或运行包。
- Microban 配置原样副本:控制配置实例。
- Microban 本地文件核对报告:真实文件与 LFS 指针核对。
- 旧版 Microduck 说明:仅供兼容,不作为新上传页默认规则。
10. 交给后台与前台对话的验收清单
- 打开上传页,不上传任何文件也能看到明确的基础必传项与可选功能。
- 只上传基础配套资源就能进入基础行走检查,不要求任何踢球/翻滚/起身策略。
- 内置头部控制只要求参数和关节配置,不强制新增 ONNX。
- 只配置左脚踢球:前台出现一个足球和左脚按钮,没有右脚按钮;仅翻滚时没有足球。
- 左右脚同时启用:只有一个足球;足球物理设置不一致时后台阻止该组合发布。
- 未启用动作的文件缺失不报错;多传未绑定文件不自动增加按钮,也不被前台无用加载。
- 一个选填动作失败,用户能明确选择仅发布已通过的功能;最终配置与资源引用完整。
- 只有策略文件而无对应控制配置,不能标成可用动作;不支持的控制器明确待适配。
- 可选动作加载失败不导致基础演示初始化失败;动作执行中出错能取消/暂停并重置。
- 打开不自动行走,未配置演示时隐藏入口,切项目不串模型、能力或资源。
- 桌面与手机按实际功能布局,低性能设备不因一次加载所有策略而卡住。
- 上传成功、静态检查、运行验证和发布分别显示;没有真实检查服务时不伪造通过。
交接范围:后台实现最低准备清单、选填功能配置、资源检查与发布;社区实现同一能力契约的播放适配。保留现有整机、零件、装配上传流程及源模型材质,不用重新围绕小鸭子设计全站表单。