Files
vibemake/docs/admin-walking-upload-ui-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

19 KiB
Raw Permalink Blame History

后台行走演示上传:界面说明与实施交接

旧版兼容资料:新上传页面一律按 最低必传项 + 可选功能规范 实施。固定展示基础准备清单,额外动作由上传者选择;没有踢球功能就不要求踢球策略,也不展示足球。本文固定 7 个策略等要求只适用于尚未拆分依赖的旧 Microduck 播放器,不作为新页面规则。

日期:2026-10-28
适用:现有 Microduck 鸭子行走演示,microduck-alpha-v1
实施项目:/Users/jerry/linkhand/vibemake-admin

1. 本次需要实现什么

上传者打开“行走演示”区域后,必须能直接回答:

  1. 这里支持哪一种机器人?
  2. 我需要准备哪些文件,每个文件有什么用?
  3. 哪些必须由我提供,哪些模板自带,哪些系统生成?
  4. 上传后缺了什么,能不能运行,下一步怎么做?

本期建议保留现有 ZIP 上传流程,增加常驻的文件说明、完整必需文件列表、示例下载与逐项检查结果。 不要只增加一句“包含模型、物理配置、控制参数和策略”。逐项文件上传可作为同一清单上的第二种入口,但需要真正完成打包链路后再开放。

这是交接说明,本文件不代表后台功能已经实施。后台当前 ZIP 本地检查主要是扩展名和 ZIP 文件头,不能把这个结果称为“文件齐全”或“演示可运行”。

2. 卡片怎么改,哪些文案直接用

卡片默认展示

行走演示                                      选填
当前支持:Microduck 鸭子机器人

上传与 Microduck 匹配的行走资源包。模型、物理配置和动作策略
需要配套,只有一个 GLB 文件不能生成行走演示。

[选择行走资源 ZIP]  [下载可运行示例 ZIP]  [查看文件结构]

上传前请准备
机器人模型    必备    microduck.glb
物理配置      必备    robot_allcollisions.xml
运动映射      必备    kinematics.json
动作策略      必备    7 个 ONNX 文件    [查看 7 个文件]
网格依赖      按引用  模型和物理配置引用的网格文件
控制配置      必备    controller.json,使用对应模板或由算法人员提供
文件清单      必备    manifest.json,由配套打包工具生成
配套素材      模板自带  沿用示例中的 assets 与来源说明

不确定怎么准备?先下载完整示例,或把这份文件要求交给模型/算法人员。
不要用其他机器人的整机 GLB 替换示例里的运动模型。

“必备”指最终资源包必须具备,不等于要求上传者逐个手写文件。系统生成和模板提供的内容要清楚标识来源。

行走功能整体为选填;用户开始配置并希望发布时,当前模板要求的文件才成为必备项。未配置时不阻止项目正常发布,前台隐藏行走入口。

查看文件结构

使用抽屉/大弹窗,展示第 3 节清单、目录、文件来源和缺项处理;支持复制文件清单。必要说明不要只藏在鼠标悬停提示内,手机上也要能点击查看。

“查看 7 个文件”展开第 3.2 节的七行,必须显示中文用途 + 完整文件名 + 必备状态,不把文件名截得无法辨认;长路径允许换行与复制。

上传后的区域

显示资源包名、大小、识别出的机器人、检查阶段、逐项文件状态和下一步按钮。状态示意:

microduck-walking.zip       识别机器人:Microduck

模型文件        已找到,待校验
物理配置        校验通过
运动映射        校验通过
动作策略        6 / 7,缺少“左脚踢球”策略
控制配置        与当前运行器匹配
资源完整性      未通过
试运行          尚未开始

缺少 policies/ball_kick_left.onnx
当前播放器启动时需要这个文件。请补齐后重新上传。

[重新选择 ZIP]  [查看完整检查报告]

上面是文案示例,不允许在未检测时预填这些结果。没有后端服务时显示“已选择文件,等待上传服务接入,尚未检查资源内容”,保留说明与示例下载,禁用依赖服务的按钮。

3. 当前鸭子到底需要哪些文件

以下路径是解压后资源包内的路径。当前前端依赖这些固定路径和大小写,不能随意重命名。ZIP 的根目录放 manifest.json;如果支持外包一层文件夹,导入器须明确识别并规范化,保持所有内部引用一致。

3.1 模型与控制:逐项列清

中文名称 包内路径 是否必备 用途与准备方式
运动模型 robot/mjlab/microduck.glb 是 鸭子运动显示用的网格;与物理配置和运动映射中的网格名称配套。使用原工程导出,不能用任意整机 GLB 顶替
物理配置 robot/mjlab/robot_allcollisions.xml 是 MJCF 文件,包含关节、碰撞、执行器等。由机器人/算法工程导出;不能拿 URDF 改扩展名替代
运动映射 robot/mjlab/kinematics.json 是 将关节与显示模型关联,来自同一物理模型的导出工具;不要求普通用户手写
控制配置 controller.json 是 明确关节顺序、观测输入、动作输出与控制频率。使用经过验证的对应模板,或由算法人员提供
文件清单 manifest.json 是 声明运行器、文件路径、真实大小与 SHA256。由配套打包工具/后台生成

两种上传方式的区别: 导入“完整 ZIP”时,这两个 JSON 需已经在包里;如果实现了“逐项添加并生成资源包”,系统可以生成 manifest,并针对这个固定模板填入已验证的 controller。不能在尚无打包功能的页面提示“无需提供 manifest”而仍只接受完整 ZIP。

控制配置可从平台固定模板提供,但不能根据 ONNX 的维度猜出关节顺序或控制语义。填入模板不等于证明用户的新策略与模板兼容,仍需后续检查。

3.2 七个动作策略:当前版本全部必备

中文名称 必备文件路径 上传区解释
行走策略 policies/BEST_alpha_walking.onnx 控制鸭子的行走动作
起坐策略 policies/BEST_alpha_sitstand.onnx 控制起坐动作
翻滚策略 policies/roulade.onnx 控制翻滚动作
左脚踢球策略 policies/ball_kick_left.onnx 控制左脚踢球动作
右脚踢球策略 policies/ball_kick_right.onnx 控制右脚踢球动作
俯身拾取策略 policies/alpha_ground_pick.onnx 控制俯身拾取动作
起身恢复策略 policies/BEST_alpha_stand.onnx 用于起身恢复

给上传者的固定说明:

当前播放器会在启动时加载这 7 个策略,即使只展示走路,也需要完整提供。它们必须与同一机器人的物理模型和控制配置匹配。请上传训练导出的 ONNX 文件;Python 代码、训练日志、.pt 或 .pth 文件不能直接替代。

这不是后台任意要求:js/experience-packages.js 检查七条路径,sandbox/src/game/game.js 启动时实际加载七个策略并检查推理结果。不能把六个策略标成选填,除非以后同时修改运行器支持的动作集合与协议。

3.3 网格依赖:由引用决定,不能让用户猜数量

robot/mjlab/meshes/ 保存相关 STL 网格。当前运行器优先按名称从 microduck.glb 取得网格,缺少时再读取对应 STL。

因此必需的是每一处几何引用都能正确解析,并不是必须存在固定数量的 STL 文件。对上传者采用简单说明:

请保留原演示工程的 meshes 文件夹,或直接使用完整示例包。系统会检查物理配置与运动映射引用的网格是否齐全,不需要你手工数文件。

当前示例有 43 个 STL 文件,基础 MJCF 中有 38 个 mesh 声明;数字只是现有样例信息,不能作为通用验收条件。校验器需检查名称、引用和数据兼容性,不能只判断“上传了 38 个文件”。

注意该 MJCF 的 meshdir="assets" 指的是运行器虚拟文件系统中的位置;当前运行器将 GLB/STL 几何载入该位置。它不是让上传者把机器人网格放进顶层音效 assets/ 文件夹。后端校验需要遵循这个运行器的实际映射规则。

3.4 模板配套内容:不要让普通用户逐个制作

内容 当前示例情况 后台说明与处理
assets/ 音效、图片、贴纸、场景素材等共 103 个文件 标记“模板配套素材”。本期保留完整示例内容;未经逐项依赖审计,不提供“一键删除素材”功能
LICENSE、NOTICE、UPSTREAM.md 现有包保留了上游许可与来源说明 标记“随模板保留”;上传第三方来源资源时保留对应说明
README.txt 包内使用说明 保留模板说明,系统可在打包时生成更新后的使用说明

可以以后把平台通用素材移到网站公共资源,但那需要同步修改前端路径和打包规则。本期不能把它们从 ZIP 删除后期待现有代码自动去其他地方找。

3.5 示例里另外两个 ONNX,不要混入基础必传列表

当前完整样例还含:

  • policies/BEST_roller.onnx
  • policies/BEST_roller_crouch.onnx
  • robot/mjlab/robot_allcollisions_rollers.xml
  • robot/mjlab/kinematics_rollers.json
  • 滚轮相关网格。

这些属于额外滚轮玩法,基础鸭子启动的七个策略不包括它们。UI 放到“其他已识别资源/滚轮扩展”,不要显示成“缺少它们就不能基础行走”。完整示例导入后保留这些文件,不能因为不是基础必备就擅自删掉。

4. 用户可以看到的目录范例

microduck-walking.zip
├── manifest.json                     文件清单,工具生成
├── controller.json                   控制配置,对应机器人模板
├── robot/mjlab/
│   ├── microduck.glb                  运动模型
│   ├── robot_allcollisions.xml        物理配置
│   ├── kinematics.json                运动映射
│   └── meshes/                        配套网格,按引用检查
├── policies/
│   ├── BEST_alpha_walking.onnx        行走
│   ├── BEST_alpha_sitstand.onnx       起坐
│   ├── roulade.onnx                   翻滚
│   ├── ball_kick_left.onnx            左脚踢球
│   ├── ball_kick_right.onnx           右脚踢球
│   ├── alpha_ground_pick.onnx         俯身拾取
│   └── BEST_alpha_stand.onnx          起身恢复
├── assets/                           模板配套素材
├── LICENSE / NOTICE / UPSTREAM.md     来源说明
└── README.txt                        使用说明

这是基础结构,完整样例还带第 3.5 节扩展文件。清单中的资源路径必须真实存在,文件字节数与哈希必须对应实际内容。

5. 若选择逐项上传,表单怎么设计

不要平铺 166 个文件上传框。使用以下分组,文件清单与打包过程由系统完成:

  1. 运动模型: 选择 microduck.glb。
  2. 物理与运动映射: 分别选择 XML、kinematics JSON;可同时选择配套 meshes 文件夹。
  3. 动作策略: 7 个有中文名称的上传位,支持一次多选自动匹配文件名;每行可替换。无法识别或同名冲突时要求明确指定,不按文件大小猜动作。
  4. 控制配置: “使用 Microduck 标准控制配置”与“导入配置”两种方式。标准配置只适用于已适配的 Microduck;导入后仍做严格匹配。
  5. 配套资源: 显示选择的版本化模板及素材摘要,来源说明随模板保留;用户新增依赖需明确收集。
  6. 生成并检查: 后台按约定路径组织文件、生成 manifest、检查、保存一个不可变资源版本。

逐项入口可以把任意源文件名映射到明确的策略槽位,但最终包内路径必须使用第 3 节名称;文件字节保持不变,并记录源文件与目标路径的映射。模型与 XML/JSON 引用不能通过简单改名强行适配。

现有后台上传类型只有 walking-zip,尚无完整逐项行走上传协议。 若实现该方式,需要补充批量上传/打包接口,或先在客户端按固定模板生成 ZIP 再走现有上传链路;大包打包需考虑内存与界面响应。按钮未接通前不要展示为可用,也不要静默拿示例策略补全用户缺项。

无论采用哪种入口,最终仍返回 walkingManifestUrl,社区播放器协议保持一致。不要为每个策略增加一个社区项目字段。

6. 检查状态与错误提示必须真实

按阶段展示,不能只给一个总的绿色“通过”:

阶段 判定内容 通过后的文案
文件识别 能读 ZIP 目录与清单,找到关键路径 “文件已识别,等待完整校验”
完整性 全部资源存在、实际大小与哈希一致、引用有效、限额合规 “资源完整性通过”
兼容性 profile、controller、关节与几何映射、策略张量与推理结果匹配 “与当前运行器兼容”
试运行 用实际发布版本加载、站立、走停、重置,检查异常 “试运行通过,待预览确认”
发布验收 操作者预览并确认,服务端验证当前版本可发布 “可以发布”

实际运行要使用同一版本的浏览器运行器;服务端工具能解析 ONNX,不代表浏览器支持其所有运算。试运行没有执行就显示“未执行”,自动检查也不保证所有场景下都稳定。

错误提示直接说明用户该做什么:

情况 页面文案
没有清单 “未找到 manifest.json。请选择配套工具生成的完整行走包,或下载示例查看结构。”
缺某个策略 “缺少左脚踢球策略 policies/ball_kick_left.onnx。当前播放器启动需要全部 7 个策略,请补齐后重新上传。”
网格缺失 “物理配置引用了 meshes/xxx.stl,但模型与网格文件夹中都未找到可用几何。请补充原工程的网格文件。”
控制约定不符 “关节顺序/控制参数与 Microduck 运行器不一致。请使用同一演示工程导出的配套文件。”
其他机器人 “当前只支持 Microduck 演示。该机器人尚未适配,暂时不能启用行走入口。”
只检查了 ZIP 头 “文件格式检查通过,尚未检查包内内容。”
上传服务未接入 “可以先查看文件要求和下载示例。上传服务尚未接入,暂不能检查或发布演示。”

逐项状态至少区分:未检查、已找到待校验、缺失、检查中、通过、不匹配、运行失败。步骤失败后保留已选文件和可读错误,不覆盖旧的已发布资源。

当前运行器约定:robotId=microduck-alpha、runtimeProfile=microduck-alpha-v1、autoWalk=false、61 维观测、14 维动作、13 维命令、物理步长 0.005 秒、每 4 步推理一次。完整 controller 见样例;不能只比较维度就认定策略匹配。

7. 本期实现范围与验收

优先完成“保留 ZIP + 清楚说明 + 示例下载 + 真实逐项检查结果”;它能继续使用已有上传/导入/构建接口。单独列清文件要求,不等于必须立刻实现逐项上传。

  • 上传前即可看到支持型号、必备类别、七个策略清单与文件来源。
  • “下载可运行示例 ZIP”返回实际完整包,不是占位链接或空目录模板。
  • 展示网格按引用校验,不把 43 个 STL 或 166 个文件写成所有资源包的硬性条件。
  • 7 个基础策略全部标必备,2 个滚轮策略单独分类。
  • 明确 manifest 自动生成的前提:当前完整 ZIP 导入仍需包内已有清单。
  • 没有真的解析 ZIP/执行校验时,不显示文件齐全或可运行。
  • 从真实报告映射文件状态,错误含中文用途、路径和修复建议;保持 requestId 便于排查。
  • 检查与预览使用同一个候选资源版本,失败不替换旧发布。
  • 预览打开默认站立;走停、重置与球交互可用;普通电脑和手机均验收。
  • Microban 等其他机器人不能仅换 GLB 后标记为已兼容。
  • 手机表格或列表可读,文件路径可复制,不依赖 hover;服务未接入也可查看说明。

8. 给实施对话的真实文件与代码位置

当前可用样例:

  • 完整 ZIP:/Users/jerry/vibemake-site/deliverables/experience-packages/microduck-walking.zip
  • 解压目录:/Users/jerry/vibemake-site/deliverables/experience-packages/microduck-walking/
  • 当前打包脚本:/Users/jerry/vibemake-site/scripts/package-experiences.mjs
  • 可直接参考的页面文件要求配置:microduck-upload-requirements.json
  • 完整清单:walking.manifest.json
  • 精确控制模板:controller.json

现有 ZIP 为 12,786,579 字节,含 166 个文件;manifest 列出 164 项,未把 manifest 自身和 README.txt 列入哈希清单。示例中有 9 个 ONNX,其中 7 个基础、2 个滚轮扩展。这些数字用于核对本样例,不作为其他合法包的固定数量要求。

正式后台的下载入口要将该 ZIP 部署到版本化静态地址或后端下载接口,不能在网页链接里写本机绝对路径。新增的文件要求 JSON 是后台展示配置,不是社区播放器的新清单协议,也不是已经存在的后端 API。

后台重点文件:

  • src/components/project/experiences/ModelAssetUpload.tsx:当前四块上传卡片,重点改 walking 区域。
  • src/components/project/experiences/ExperiencePanel.tsx:上传、导入、任务状态、预览与发布流程。
  • src/components/project/experiences/ExperienceReport.tsx:已有报告展示,可扩展逐项结果。
  • src/components/project/experiences/ExperienceDraftForm.tsx:机器人/运行器信息展示。
  • src/utils/modelAssets.ts:目前 ZIP 主要校验扩展名和文件头,不能充当完整内容校验。
  • src/api/experience-types.ts:现有统一报告只有 status/errors/warnings;若要结构化逐项结果,增补类型并与后端约定,不能凭空推断每项通过。

社区核对基线:

  • js/experience-packages.js:清单与必备路径。
  • sandbox/src/game/constants.js:策略路径、关节顺序、控制常量。
  • sandbox/src/game/game.js:七策略启动加载、物理模型与虚拟网格目录。
  • sandbox/src/game/duck.js:GLB 命名几何与 STL 回退规则。
  • sandbox/src/game/package-config.js:controller 精确匹配。
  • js/walking.js:读取 manifest,使用网站内置 /play/microduck/ 运行器。

给实施者的任务:按本文完成后台上传者可理解的说明与状态展示,优先复用现有 ZIP 链路;保留已有整机、零件与装配上传功能,不将模板兼容标记等同于仿真验收。完成后展示桌面和手机效果,并说明真实接通了哪些检查、哪些仍等待后端。