Files
vibemake/docs/admin-walking-upload-generic-spec.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

25 KiB
Raw Permalink Blame History

行走演示上传与展示规范:最低必传项 + 可选功能

修订日期: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 个策略全部必传”换成“识别后决定”;默认界面就显示固定的基础类别与明确的选填卡片。后台解析文件的用途是验证用户的配置与引用是否成立。

上传交互约定:

  1. 每项有“未提供/已选择/已上传/检查通过/需要处理”的明确状态,并显示缺少的具体文件和归属功能。服务未接入时只显示“已选择,尚未上传”,不显示检查通过。
  2. 配置由模型/算法人员提供,普通上传者按栏位选文件。提供说明和真实示例,不让普通上传者手写关节张量、策略状态机或文件哈希。
  3. 分项上传必须保留相对目录与引用;同名文件不能静默覆盖。改变文件名后同步更新引用并重新校验。
  4. ZIP 是批量导入容器,最终解压成相同的资源目录。导入已声明的功能绑定并展示给用户确认;无绑定的额外文件保留为“未用于展示”,不凭文件名激活功能。
  5. 多传文件允许存为草稿素材。只有被选中功能引用的资源才进入发布清单并由前台加载,不因多传素材就增加前台负担。
  6. 可选功能取消勾选后保留其草稿文件,停止计入本次发布要求。发布编译器必须同步去除技能、输入绑定和资源引用,并重新校验完整配置,不能只删一个 ONNX。
  7. 新版协议不要让上传者再上传一份 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 都能运行。

项目发布内容 前台展示
没有行走配置 隐藏行走演示按钮
只有基础行走 模型、开始/暂停、重置与实际支持的方向控制;没有足球及其他动作
行走 + 头部摆动 增加头部摆动控制
行走 + 左脚踢球 增加一个足球、左脚踢球和重置球;没有右脚按钮
行走 + 左右脚踢球 一个足球、两个踢球按钮;不重复创建球
行走 + 翻滚,无踢球 增加翻滚;不显示足球
行走 + 多项通过的功能 按功能分组展示全部已支持操作;手机使用“更多动作”面板

加载与交互约定:

  1. 首次只加载基础资源,动作策略按需加载并缓存;已发布的可选动作可先显示按钮,点击后提示加载,加载完成前不执行。不要在启动阶段 Promise.all 强制加载所有可选策略。
  2. 控制参数、可移动方向和限速来自已验证配置;不硬套小鸭子的轴数、键位、关节数量或动作菜单。参数为零或不支持的方向不显示可用控制。
  3. 开场不自动走、不自动踢、不自动摆头。切后台、关闭弹窗、失焦、触摸取消时清空输入;恢复时不沿用此前按住的方向,也不自动重播动作。
  4. 一项可选动作下载失败,应提示该动作不可用,基础行走继续可用;相关道具只在仍有可用依赖功能时保留。修改物理世界若需要重建,先暂停并重置。基础资源失败才展示整体失败。
  5. 动作执行失败不能带着残留控制量继续跑。运行器必须具备经验证的结束/取消和恢复基础状态逻辑;无法安全恢复时暂停并提供重置,不宣称所有异常都能无缝降级。
  6. 对未支持的能力 ID 显示后台适配提示,公开前台不展示不可用按钮;不能因一个未知选填字段导致已支持基础演示崩溃,也不能忽略它对基础控制的实际依赖。
  7. 高精度 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-核对资料/。

配套资料:

10. 交给后台与前台对话的验收清单

  • 打开上传页,不上传任何文件也能看到明确的基础必传项与可选功能。
  • 只上传基础配套资源就能进入基础行走检查,不要求任何踢球/翻滚/起身策略。
  • 内置头部控制只要求参数和关节配置,不强制新增 ONNX。
  • 只配置左脚踢球:前台出现一个足球和左脚按钮,没有右脚按钮;仅翻滚时没有足球。
  • 左右脚同时启用:只有一个足球;足球物理设置不一致时后台阻止该组合发布。
  • 未启用动作的文件缺失不报错;多传未绑定文件不自动增加按钮,也不被前台无用加载。
  • 一个选填动作失败,用户能明确选择仅发布已通过的功能;最终配置与资源引用完整。
  • ���有策略文件而无对应控制配置,不能标成可用动作;不支持的控制器明确待适配。
  • 可选动作加载失败不导致基础演示初始化失败;动作执行中出错能取消/暂停并重置。
  • 打开不自动行走,未配置演示时隐藏入口,切项目不串模型、能力或资源。
  • 桌面与手机按实际功能布局,低性能设备不因一次加载所有策略而卡住。
  • 上传成功、静态检查、运行验证和发布分别显示;没有真实检查服务时不伪造通过。

交接范围:后台实现最低准备清单、选填功能配置、资源检查与发布;社区实现同一能力契约的播放适配。保留现有整机、零件、装配上传流程及源模型材质,不用重新围绕小鸭子设计全站表单。