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.
19 KiB
后台行走演示上传:界面说明与实施交接
旧版兼容资料:新上传页面一律按 最低必传项 + 可选功能规范 实施。固定展示基础准备清单,额外动作由上传者选择;没有踢球功能就不要求踢球策略,也不展示足球。本文固定 7 个策略等要求只适用于尚未拆分依赖的旧 Microduck 播放器,不作为新页面规则。
日期:2026-10-28
适用:现有 Microduck 鸭子行走演示,microduck-alpha-v1
实施项目:/Users/jerry/linkhand/vibemake-admin
1. 本次需要实现什么
上传者打开“行走演示”区域后,必须能直接回答:
- 这里支持哪一种机器人?
- 我需要准备哪些文件,每个文件有什么用?
- 哪些必须由我提供,哪些模板自带,哪些系统生成?
- 上传后缺了什么,能不能运行,下一步怎么做?
本期建议保留现有 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.onnxpolicies/BEST_roller_crouch.onnxrobot/mjlab/robot_allcollisions_rollers.xmlrobot/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 个文件上传框。使用以下分组,文件清单与打包过程由系统完成:
- 运动模型: 选择
microduck.glb。 - 物理与运动映射: 分别选择 XML、kinematics JSON;可同时选择配套 meshes 文件夹。
- 动作策略: 7 个有中文名称的上传位,支持一次多选自动匹配文件名;每行可替换。无法识别或同名冲突时要求明确指定,不按文件大小猜动作。
- 控制配置: “使用 Microduck 标准控制配置”与“导入配置”两种方式。标准配置只适用于已适配的 Microduck;导入后仍做严格匹配。
- 配套资源: 显示选择的版本化模板及素材摘要,来源说明随模板保留;用户新增依赖需明确收集。
- 生成并检查: 后台按约定路径组织文件、生成 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 链路;保留已有整机、零件与装配上传功能,不将模板兼容标记等同于仿真验收。完成后展示桌面和手机效果,并说明真实接通了哪些检查、哪些仍等待后端。