Files
vibemake-admin/docs/model-experiences-api.md

54 KiB
Raw Permalink Blame History

2026-10-28 联调更新:以 admin-api(7).md 第 8.3 节为准。 当前 dev 返回 modelGlbUrl 等新字段时,默认使用 ProjectResourcesPanel 与 /resources/{resourceType}/signature、PUT /resources/{resourceType}、DELETE /resources/{resourceType}。确认即更新社区绑定,无需草稿、构建或重新发布。下面旧版 experience-draft / walking-editor 属于此前拟议方案,仅保留兼容代码,不是本次后端实现。

2026-10-29 零件单项管理

  • 当前零件列表支持按文件名/目录搜索(忽略大小写),显示匹配数,逐行删除。

  • “上传单个零件”选择 GLB 后自动添加,可指定相对目录,默认根目录;完全相同路径需要确认替换。同名但不同目录按不同零件处理。

  • 后端目前只有整批签名/绑定、整类清除接口。单项增删通过读取原清单、四路下载保留文件、合并后四路上传新批次、完整绑定实现;删除最后一个零件直接清除零件绑定。不会调用不存在的单文件接口,不会把新增一个文件误提交成整组清单。旧 OSS 对象仍保留。

  • 代价:零件数量较多时,单项变更也会传输保留的零件,页面显示进度;若后端增加原子增删/保留对象引用接口,可替换该兼容流程以减少流量和内存使用。

  • 下载失败不提交新绑定;失败允许手动重试并复用已成功的文件。确认结果未知时必须先刷新核对,不自动重复提交。开始操作及确认前核对绑定是否变化;后端尚无版本号/CAS,这不是跨客户端原子并发锁。

  • 删除零件不自动改写已有步骤 JSON,界面提示管理员同步调整引用该零件的步骤。

  • 验证:新增 8 项零件管理测试及原 7 项自动上传测试通过,dev 构建通过。真实 dev 联调项目 b7drj14qq1nf 添加测试零件(275 → 276)后删除(276 → 275),刷新确认生效;保留的 275 个零件逐一下载比对 SHA256,与 Microban 原文件全部一致。未操作用户截图中的 gcw47xwyyhr8 项目资源。

当前四类资源接口

  • model-glb:单个 GLB;model-parts:文件夹内 GLB,保留子目录;assembly-json:单个 JSON,后端不解析业务内容;walking-resources:全部目录文件,无 robot.json 要求。
  • 签名提交 files[{relativePath,sizeBytes}];OSS 按原 formFields + File 直传,最多四路,不携带管理 Token;全部成功后 PUT {batchCode,files}。返回平铺 ProjectView,合入详情的 project。
  • 允许零字节,不设前端大小/数量配额。只校验扩展名和文档路径规则;可视化编辑另需能解析真实 GLB。
  • 同批成功文件手动重试不重传;网络不确定/过期使用新批,确认结果不明先刷新核对。替换整类资源需要完整清单;DELETE 幂等清除绑定但不删除对象。
  • 详情页选好文件即自动签名、直传并确认绑定;失败保留选择,仅显示手动重试,不自动循环重试。新建页先选文件,项目创建且 READY 后按类别依次自动上传。装配编辑器保存时生成 JSON 并自动上传;零件仍通过 model-parts 独立绑定。
  • 2026-10-28 dev 真实联调:本地入口改为 http://localhost:8091,项目 b7drj14qq1nf(未发布)。使用 Microban-后台上传资料-20261028,整机 GLB 1 个、零件 GLB 275 个、步骤 JSON 1 个、运动目录文件 32 个均已自动上传并确认绑定,刷新后保留。逐个从 OSS 下载比对 SHA256:309/309 与本地原文件一致。保留 parts/、assets/、policies/ 等相对路径。此前 localhost:5188 的 OSS CORS 阻塞在 8091 下未复现。
  • 自动化覆盖四类资源自动上传、零字节与目录、失败后仅重试未成功文件、新建项目多类串行上传、仓库 READY 后开始且不重复,共 7 项通过。可视化编辑生成 JSON 后自动上传也已在 dev 实测成功。
  • 本次不宣称行走策略已执行、前台仿真成功或 JSON 播放契约已验证,接口仅核验对象存在及大小。

模型与演示:后台已实现的第一阶段接口约定

日期:2026-10-28。用于后端实现和前后台联调;以下新增接口尚未上线,前端已按本约定接入,不能将 UI 或模拟测试通过视为真实上传成功。

协议来源:vibemake-site/docs/admin-model-assembly-walking-spec.md。根据本次需求,前端不限制文件大小,不限制机器人型号和 runtimeProfile;文件限额、ZIP 解压保护、完整性及运行器兼容性均由后端校验并返回具体结果。

1. 本期范围

项目详情新增“模型与演示”:整机 GLB、零件 GLB 文件夹、装配步骤 JSON、行走 ZIP 上传;资源库;JSON 文件映射;候选导入确认;草稿启停/清空;版本构建;打开平台预览;完整快照发布。

装配的主入口是“制作装配流程”:支持本地/已上传 GLB 的三维点选与列表多选、分组、轴向进入距离预览、拖动排序、批量进入设置、撤销/重做、复制步骤设置和完整流程播放。“高级导入(JSON)”仅导入步骤配置;零件从上方“零件模型”选择。保存时程序生成 v1 装配清单,用户不用输入编号、四元数或哈希。不做通用自动几何对齐或策略训练;坐标不一致的零件可用移动/旋转控件手动对齐。原始 GLB 直传 OSS,保留材质、颜色、贴图与文件字节。

本地文件也可先制作流程(无前端大小限制)。SHA256 由 Web Crypto 对原文件计算;未上传的临时资源编号只保留在页面内存中,不向保存接口提交。上传确认后,按类型、完整相对路径、字节数、SHA256 唯一匹配服务器 assetId,存在歧义时不自动替换。新建项目到详情页的一次 SPA 跳转同时保留文件和流程;浏览器刷新前需要上传并保存,或先导出系统生成的 JSON。

界面按“整机模型、零件模型、拼装步骤、行走演示”四个独立区域组织,不让管理员在资源类型下拉框反复切换。新建页可同时选择整机和零件,创建后保留这些 File 并直接进入模型页继续上传;实际上传仍使用当前项目的签名接口,不将文件序列化进创建项目 JSON。文件选择仅在本次页面操作中保留,刷新页面需重新选择。

整机上传确认后自动选用到本地展示设置;完整包上传后自动发起读取;独立 JSON 仅逐路径核对“零件模型”已上传的 part-glb,不将整机 GLB 当作零件候选;缺少/有歧义时才提示管理员核对。导入确认仅更新对应的装配或行走区域,保留已选择的整机与另一种演示。按钮“检查并预览”会先保存本地修改,再生成检查版本;最终仍需单独确认发布。

所有新增路径均带 /admin-api 前缀,沿用当前 Bearer Token 和 {code,message,data,requestId} 响应。下面列出的结构是 data 内容。精确 TypeScript 定义:src/api/experience-types.ts;请求实现:src/api/experiences.ts。

2. 资源类型与上传

当前上传入口仅使用 whole-glb、part-glb、assembly-manifest、walking-zip。零件只通过文件夹选择,批量签名和原文件直传仍使用 part-glb;保留文件夹内相对路径,过滤非 GLB 与 macOS 的 ._ 伴随文件。前端不设置大小/数量限额。parts-zip/assembly-zip 类型仅为历史兼容保留,不再提供新的上传或读取入口;旧资源不物理删除。

POST /projects/{projectCode}/model-assets/signature

{
  "type": "part-glb",
  "files": [{"relativePath":"left/arm.glb","sizeBytes":18876964}]
}
{
  "batchCode":"batch-001",
  "uploadUrl":"https://oss.example.com",
  "expiresAt":"2026-10-28T08:00:00",
  "files":[{
    "relativePath":"left/arm.glb",
    "objectKey":"project/immutable-key/left/arm.glb",
    "formFields":{"key":"project/immutable-key/left/arm.glb","policy":"SIGNED_POLICY","signature":"SIGNED_VALUE"}
  }]
}

formFields 是服务端签名结果,上例仅说明结构。客户端原样构建 OSS FormData;不携带后台 Authorization,不重写 Content-Type。最多 4 路并发;全部在途文件结束后才允许重试。明确失败时只补传同批次未成功的文件;签名过期或传输结果未知时使用新批次,避免覆盖旧对象。已经传输完成但 complete 返回丢失时,仅再次确认同一 batchCode。

POST /projects/{projectCode}/model-assets/complete

请求仅为 {"batchCode":"batch-001"},不接受任意客户端 objectKey。返回第 4 节的 ExperienceOperation,可同步返回资源,也可返回 jobId。

服务端核对项目归属、实际字节与 SHA256;ZIP 解压、GLB 元数据分析等可异步执行。相同 batchCode 重复确认必须幂等,返回同一资源/任务,不能重复创建资源。不要在签名接口自动绑定项目或发布。

GET /projects/{projectCode}/model-assets?cursor=...&type=part-glb

cursor/type 可选。使用游标分页,不是已有用户/项目列表的 page 分页:

{
  "items":[{
    "assetId":"asset-arm-left",
    "type":"part-glb",
    "relativePath":"left/arm.glb",
    "bytes":18876964,
    "sha256":"5976d400a8f87877fee0be58731e13b8c1db84271b24d35ed889f255e56f894a",
    "status":"READY",
    "downloadUrl":null,
    "metadata":{"meshCount":12,"triangleCount":15000}
  }],
  "nextCursor":null
}

状态为 PROCESSING/READY/FAILED。已上传 GLB 的 downloadUrl 需返回可供后台跨域读取的 HTTP(S) 原文件地址(可短期签名并支持刷新获取),才能在可视化编辑器中载入;不能是任意脚本 URL。为 null 时明确显示无法预览,允许重新选择本地原文件。单独 JSON 的资源还需返回 metadata.manifestFiles: [{path,bytes,sha256}],供管理员逐路径映射已有 GLB。行走元数据可返回 robotId/runtimeProfile,后台只展示识别结果,不硬编码值。

3. 草稿

GET /projects/{projectCode}/experience-draft

新项目也应返回 HTTP 200、revision=0 和三个 null 绑定;不要用 404 表示空草稿。后台遇到 404/405/501 会展示“接口待接入”,并禁止伪保存。

{
  "projectCode":"project-a",
  "revision":0,
  "wholeModel":null,
  "assembly":null,
  "walking":null,
  "report":null,
  "latestBuild":null,
  "published":null
}

PUT /projects/{projectCode}/experience-draft

完整替换:三个字段必须出现,null 表示清空;不是“省略即清空”。

{
  "expectedRevision":12,
  "wholeModel":{"assetId":"asset-robot","displayQuaternion":[0,0,0,1]},
  "assembly":{
    "enabled":true,"title":"机器人装配","unit":"meter",
    "referenceAssetId":"asset-robot","displayQuaternion":[0,0,0,1],
    "parts":[{
      "id":"base","name":"底座","assetId":"asset-base","parentId":null,
      "position":[0,0,0],"quaternion":[0,0,0,1],"scale":[1,1,1],"installOffset":[0,0.08,0]
    }],
    "steps":[{"id":"step-1","label":"安装底座","parts":["base"]}],
    "editorGroups":[{"id":"group-base","name":"底座组件","parts":["base"]}]
  },
  "walking":null
}

行走非空时:{enabled,packageAssetId,robotId,runtimeProfile}。各项目使用自己的标识和资源,不套用 Microduck 样例。保存成功递增 revision,并返回完整 ExperienceDraftView。冲突返回 HTTP 409/REVISION_CONFLICT,不得自动覆盖。

assembly.editorGroups 是可选的编辑器分组,保存后原样返回,用于再次编辑;不放入公开 manifest,也不改变播放语义。其他装配字段沿用 v1,不需要新增“上传步骤 JSON”才能保存可视化流程。构建时由 parts.assetId 获取不可变原文件的真实 bytes/SHA256,生成公开 JSON 与文件映射。相同资源的多个实例只声明一次文件;同路径的不同资源应生成无冲突的包内路径。实例位置/四元数/缩放使用父节点局部坐标,保留 GLB 内部节点变换;进入动画从 position + installOffset 到 position,不改最终方向或材质。

步骤需覆盖所有实例、每个实例安装一次,父零件必须在同一步或更早的步骤中。编辑器在排序、替换步骤零件后会校验;后端仍需独立校验。复制步骤只复制名称和进入设置,提示另选一组零件,防止产生重复安装。单个 GLB 内部的多个网格保留为同一个文件实例;若希望独立选择,应上传分件 GLB。

enabled=false 保留草稿内容;重新生成并发布版本后对应社区字段为 null。清空绑定不物理删除历史发布正在引用的对象。

4. 统一异步结果

complete/import/build 三类 POST 均返回 ExperienceOperation。所有可空字段请显式返回 null,数组返回 []:

{
  "jobId":"job-001",
  "assets":[],
  "draftCandidate":null,
  "build":null,
  "report":null
}

同步完成时 jobId=null,其余字段放对应结果。异步任务:

GET /projects/{projectCode}/experience-jobs/{jobId}

{
  "jobId":"job-001",
  "status":"RUNNING",
  "phase":"VALIDATING",
  "message":"正在校验包内引用",
  "report":null,
  "result":null
}

状态:QUEUED/RUNNING/SUCCEEDED/FAILED。成功时 result 必须为 {assets,draftCandidate,build,report};不是整个响应信封。失败保留 report 中的定位信息。前端串行约 3 秒查询,不捏造百分比;查询失败显示恢复查询,离开项目时停止,不自动重发 POST。

Report:{status: "PENDING" | "PASSED" | "FAILED", errors: Issue[], warnings: Issue[]};Issue:{code,message,path?,partId?,stepId?}。类型、错误码可自由扩展;前端显示未知错误码的原文。

5. 导入

POST /projects/{projectCode}/experience-imports

{
  "sourceAssetId":"asset-assembly-json",
  "kind":"assembly",
  "expectedRevision":12,
  "assetBindings":[{"path":"left/arm.glb","assetId":"asset-arm-left"}]
}

kind=parts/assembly/walking。完整 ZIP 自带映射,不需要 assetBindings;独立装配 JSON 必须逐路径绑定本项目已上传资源。后端核对 bytes/sha256,不能仅按 basename 匹配。

返回统一异步结果。parts 导入只返回 assets,不凭空创建位姿;assembly/walking 返回基于 expectedRevision 的完整 draftCandidate 和校验报告,不直接覆盖服务端草稿。只有 report.status=PASSED 时后台才允许应用候选;应用后仍需用户保存草稿。

后端应分别报告文件完整性、运行器兼容性、仿真验收结果。后台允许任何型号/运行器的包上传,不据 microduck-alpha-v1 建白名单;不兼容或未验收的包如何进入候选/发布,由后端报告决定,不能把“上传成功”当作“仿真已验收”。

6. 构建与预览

POST /projects/{projectCode}/experience-builds

请求:{"draftRevision":13},返回统一异步结果,结果内 build 为:

{
  "buildId":"build-013","draftRevision":13,"status":"READY",
  "publishable":true,"publicationMessage":null,
  "report":{"status":"PASSED","errors":[],"warnings":[]},
  "outputs":{
    "glbMainUrl":null,"glbConfig":null,
    "assemblyManifestUrl":"https://assets.example.com/project-a/assembly/a1/manifest.json",
    "walkingManifestUrl":null
  },
  "previewUrls":{"wholeModel":null,"assembly":"https://community.example.com/preview/controlled-ticket","walking":null}
}

status=READY/FAILED。publishable=false 时 publicationMessage 应说明尚未完成的校验/验收。空配置也允许构建,用于发布清空后的快照。

previewUrls 是前台同协议播放器的受控预览页面地址,不是 ZIP 或 GLB 下载地址。 后台不自行执行 ZIP 中的 HTML/JS/WASM,不假造预览。后端需与前台确定正式预览路由和整包鉴权方式;原前台 /examples/experience-preview.html 只在本地存在,不可当线上地址返回。manifest 的单独查询签名不能自动解决所有相对资源的私有访问。

outputs 中 manifest 字段必须是可加载的解压后 JSON 地址,引用文件与清单同版本;生成 build 不等于公开发布。后台下载/预览链接应受控或带有效期,社区接口只返回已发布快照的公开地址。

7. 原子发布

扩展已有 PUT /projects/{projectCode}/publication:

{
  "commitSha":"当前 main SHA",
  "experienceBuildId":"build-013",
  "expectedDraftRevision":13
}

服务端重新确认项目、main SHA、草稿 revision、构建归属、文件完整性及验收结果,原子写入代码与资源快照。失败保留旧发布版本。允许 commitSha 不变、只更新资源快照。

兼容旧请求只传 commitSha:保留当前已发布的资源,不能清空,也不能自动选择最新上传文件。后台原有顶部发布按钮走此兼容语义;“模型与演示”的“发布此资源版本”才携带资源构建参数。

GET 草稿的 published 返回:{releaseId,commitSha,draftRevision,experienceBuildId,publishedAt,glbMainUrl,glbConfig,assemblyManifestUrl,walkingManifestUrl} 或 null。相关 URL/config 同时加入后台 ProjectView 和社区项目详情。

社区规则:已发布的 assemblyManifestUrl/walkingManifestUrl 非空才展示对应入口,null 隐藏;关闭开关或清空绑定必须发布后才影响社区。各项目独立,不能按名称匹配或自动补其他项目的演示。

8. 交接前仍需对齐

  1. 上述新增接口的完整返回结构及 HTTP 202 异步语义,由后端按此契约实现或反馈差异。
  2. 前台新增 glbMainUrl/glbConfig 主展示读取;装配/行走目前已读取两个 manifest 字段。
  3. 前台行走加载器当前固定 microduck-alpha-v1。后台已取消型号限制;其他机器人真实播放仍需前台/算法提供匹配运行器并注册,上传文件不能自动生成运行器。
  4. 受控平台预览路由、预览票据与全部依赖文件的访问方式。
  5. 后端各文件类型的大小/数量限制及错误码,返回时前端展示后端 message/requestId,不内置前端大小上限。
  6. 正式联调关闭前台本地样例补全,验证“未上传/关闭/清空 → 发布 → null → 隐藏入口”,并验收实际设备上的装配及行走行为。

9. 旧版 Microduck v1 兼容报告(仅此格式;通用规则见第 10 节)

后台仍采用完整 walking-zip 上传/导入/构建链路,不开放未接通的逐项上传或自动补策略。src/config/walking-upload-requirements.json 仅为旧版 Microduck v1 模板,只有明确识别旧格式或用户主动查看专用示例时使用,不作为默认上传清单。该 JSON 是 UI 展示配置,不是社区 manifest,不是 API。

已将实际完整样例随项目静态发布:public/examples/microduck-alpha-v1/7114a32b7a3e/microduck-walking.zip,12,786,579 字节,SHA256 7114a32b7a3e7b6264312e83dc88aa9d38760230c866eacdeadf9fba3e59bcd4。已核对完整包及清单声明的 164 个资源的真实字节数/哈希;此核对不等同于后台实际浏览器仿真验收。ZIP 含 166 个文件(另有目录条目),这些数字不作为其他包验收条件。下载链接是同源静态路径,Vite 构建会复制进 dist,无需本机绝对路径或新的下载 API;部署时必须包含该目录。文件要求亦可下载为面向准备人员的文本。

旧版 ExperienceReport 的总状态不能推断各个文件、阶段已经通过。为 complete/import/job/build/draft 中的 ExperienceReport 增加可选 walking:

{
  "status": "FAILED",
  "errors": [{"code":"MISSING_POLICY","message":"缺少左脚踢球策略","path":"policies/ball_kick_left.onnx"}],
  "warnings": [],
  "walking": {
    "sourceAssetId": "walking-zip-001",
    "robotId": "microduck-alpha",
    "runtimeProfile": "microduck-alpha-v1",
    "items": [
      {"key":"robot/mjlab/microduck.glb","path":"robot/mjlab/microduck.glb","state":"found_pending_validation"},
      {"key":"policies/ball_kick_left.onnx","path":"policies/ball_kick_left.onnx","state":"missing","suggestion":"请补齐同一演示工程的左脚踢球 ONNX 后重新上传。"},
      {"key":"meshes","state":"not_checked"},
      {"key":"assets","state":"not_checked"},
      {"key":"provenance","state":"not_checked"}
    ],
    "stages": [
      {"id":"identify","state":"passed"},
      {"id":"integrity","state":"mismatch","message":"资源包缺少必需策略"},
      {"id":"compatibility","state":"not_checked"},
      {"id":"runtime","state":"not_checked"},
      {"id":"review","state":"not_checked"}
    ]
  }
}
  • sourceAssetId 必须是本次检查的不可变行走 ZIP 资源;不能使用项目编码代替版本。后台仅对匹配资源显示逐项状态;重新选择的 File 不复用同名旧 ZIP 的结果。发布预览仍绑定同一草稿 revision/buildId。
  • 单文件 key 使用完整包内路径;若提供 path,同样必须是完整路径。依赖组 key 使用 meshes/assets/provenance,滚轮扩展可用 rollers 或具体路径;扩展结果放完整报告,不列为七策略基础必备。
  • items[].state 和 stages[].state:not_checked/found_pending_validation/missing/checking/passed/mismatch/runtime_failed。阶段 id:identify/integrity/compatibility/runtime/review。每项可带 message/suggestion。未返回的项显示“未检查”;未执行的试运行和预览显示“未执行”,不会用总的 PASSED 补绿。
  • report.walking 同样可随失败响应的 data 返回(与 errors/warnings 并列),或随异步任务的 report 返回,以便失败时保留中文错误、完整路径和 requestId。缺项报告不会应用候选草稿;失败不清除所选 ZIP,也不改旧发布资源。
  • meshes 按实际引用检查,不规定 STL 数量。assets/ 和来源说明保留模板内容;不要把模板素材通过检查等同于所有用户新策略可运行。全部七个基础策略启动必需,另外两个滚轮策略只作扩展。
  • 兼容性检查需检查完整 controller 控制语义与映射,不能只比较 ONNX 张量维度;实际试运行需使用同版本浏览器运行器。没有执行不得返回 passed。
  • 没有后端服务或只做了 ZIP 扩展名/文件头检查时,后台显示尚未检查内容,下载与说明仍可使用。后台不实施仿真、不伪造逐项结果。接口是否可发布最终仍由当前版本的 build.publishable/publication 接口判断。
  • Microduck 说明只代表当前提供的模板;沿用用户要求,后台不按机器人 ID 硬编码禁止其他项目上传,也不设文件大小上限。其他机器人是否能播放由对应运行器与服务端兼容性结果决定。

10. 通用机器人运动演示:按包报告展示(取代固定默认清单)

默认页面与准备说明现在是通用的;没有识别包时,不预填“左脚踢球”等策略。src/config/walking-upload-profiles.json 是模板/格式说明索引,不是播放器协议或已部署能力注册表。只有旧格式 legacy-walking-v1(兼容未返回 format、但明确 runtimeProfile=microduck-alpha-v1 的老报告)使用第 9 节清单。机器人名称不作为判断条件,显式 Robot Package 格式优先于旧 profile,不能把新版 Microduck 的九策略声明降成旧七策略。

后端应沿用播放器原生 robot.json schema 与跨字段规则解析,按 model、assets.path/VFS、skills.controller.policy、render.source 和平台维护的 adapter 依赖规则生成 requirements。ONNX 路径去重并保留引用技能;oscillator 无额外策略文件。不要按 id=microban 等名称分支套文件数、模型名或策略路径;不要向后台再引入一套不同控制配置。

现有 ExperienceReport.walking 扩展如下(字段定义见 experience-types.ts):

{
  "sourceAssetId":"immutable-robot-package-asset",
  "robotId":"robot-from-config",
  "runtimeProfile":"generic",
  "format":"robot-package",
  "entry":"robot.json",
  "adapter":"generic",
  "requirements":[
    {"key":"entry","label":"机器人配置","path":"robot.json","category":"config","required":true},
    {"key":"model","label":"物理模型","path":"model.xml","category":"model","required":true},
    {"key":"walk-policy","label":"行走策略","path":"policies/walk.onnx","category":"policy","required":true,"skills":["行走"]}
  ],
  "capabilities":[
    {"id":"walk","label":"行走","controller":"onnx","policyPath":"policies/walk.onnx","supported":true},
    {"id":"head","label":"转头","controller":"oscillator","supported":true}
  ],
  "items":[{"key":"policies/walk.onnx","path":"policies/walk.onnx","state":"found_pending_validation"}],
  "stages":[{"id":"identify","state":"passed"},{"id":"runtime","state":"not_checked"}],
  "communityRuntime":{"status":"pending","message":"社区的通用包入口尚未部署"}
}

示例省略模型的实际网格闭包;真实报告必须返回该包实际依赖,而非固定填 25 个。requirements.category 为 config/model/dependency/policy/render/provenance/adapter,另可带 help/preparedBy;required 仅表示该包需要。capabilities 只列配置实际声明的动作,supported 表示内置运行器能力支持,不代表试运行通过,更不代表社区已经部署。未知适配器或能力明确返回不支持并说明,不执行包内自带 JS。

format 可为 legacy-walking-v1 / robot-package / walking-transport-v2 / unknown。后两种新格式的报告必须明确社区接入情况。communityRuntime.status 为 supported/pending/unsupported:pending 或未返回支持确认时,后台对 Robot Package 不开放资源预览与发布,即使上传成功或总报告 PASSED,也不能据此宣称旧社区可播放。草稿上传与保存仍允许;实际发布接口必须再次校验。

通用阶段为 identify/integrity/contract/runtime_support/runtime/review;旧 compatibility 保留兼容。未返回结果仍显示未检查,runtime/review 未执行。源资源仍以不可变 sourceAssetId 绑定,关联 ModelAsset 的字节/哈希与构建 revision;同名新 File 不复用旧结果。没有后端解析服务时仅展示通用说明和 ZIP 文件头检查结果,不伪造 robot.json 已解析。

明确的带路径错误优先于“文件存在”状态。LFS_POINTER 等错误显示“资源未下载完整”,不能以文件存在或扩展名正确显示通过;缺策略时指出实际引用动作与路径。检测内容、引用闭包、schema、跨字段、控制契约、ONNX 实际推理及仿真仍由后端/运行器完成。

旧版示例 ZIP 仍保留在显式选择的“旧版 Microduck v1 专用兼容示例”内。Microban 仅提供原样 robot.json 配置参考,现有下载副本包含 26 个 Git LFS 指针,不能制作“可运行示例”。切换参考模板不会修改当前包的 requirements 或上传文件。

Robot Package 发布外壳 transport v2 仍为拟议协议,本次未实现前后台传输与播放接入,未修改社区播放器或覆盖 sandbox。后续需共同确认外壳、依赖闭包、同源受控入口与路径规范化;不能全局放宽路径穿越检查,不能把下载工程本地运行等同于 OSS 动态资源可播放。

11. 装配操作入口简化

零件模型只保留“选择零件文件夹”与“上传零件文件夹”,无单文件多选和 ZIP。目录中的子文件夹路径保持不变,只检查/上传 GLB;其他文件明确提示已忽略。没有 GLB 的文件夹显示错误,不允许制作空流程。制作装配流程直接使用本项目上方已选/已上传的零件,编辑器不另设上传入口;整机只用于参考,不进入新增零件候选。旧流程已引用的数据保留,避免界面简化破坏已有流程。

高级导入仅 JSON。清单文件引用逐项按完整路径、字节数与 SHA256 核对本项目 part-glb;映射对话框也仅提供零件模型,不提供整机。批量上传顺序保持整机→零件→步骤 JSON,生成版本前仍检查真实资源关联与草稿修订。API 无需新增目录或 ZIP 解压协议,继续签名批量 GLB 原文件。

12. 行走表单 v3:本次后台与后端联调约定(待后端实现)

本节为新版默认入口,覆盖前面“仅 ZIP”的交互说明;旧 ZIP 接口继续用于显式兼容区。来源为 admin-walking-upload-generic-spec.md 与 src/config/walking-upload-profiles.json v3。本仓库完成后台表单、上传适配与前端流程;下面的接口是待双方确认并实施的约定,不表示服务器已部署,也不表示社区播放器已完成能力拆分。

表单与资源

基础四项为机器人控制配置、MJCF、模型实际引用文件、配套 primary ONNX。无外部引用的 MJCF 不要求上传空目录。客户端读取 schema=1 的 robot.json 来辅助绑定实际 skill id 和路径;完整 schema、引用闭包、关节/观测/动作维度、推理及仿真检查由后端执行。前端没有文件大小上限,后端的限制需通过结构化错误返回。

十项可选功能默认关闭:head、sit_stand、roll、kick_left、kick_right、recovery、ground_pick、rollers、roller_crouch、visual_model。按选中功能要求资源;oscillator 不强制 ONNX,多个技能允许共用一个策略。roller_crouch 依赖 rollers。恢复自动触发须另行明确开启。额外素材保存在资源库,不能仅因存在文件就新增功能或加载到前台。

足球和拾取物的预设由后端提供 id、不可变 version、label、kind、parameters,禁止客户端猜测物理参数。左右踢球共用一个足球;未选踢球且未明确拾取足球时不显示足球。上传足球 GLB 仅替换外观,不能替代物理预设。社区最终只展示所发布能力,按能力懒加载依赖。

路由与请求

管理 API 根路径仍是 /admin-api,统一响应封套沿用现有接口。下表路径均相对 /projects/{projectCode}/walking-editor。完整、逐字段类型以 src/api/walking-editor-types.ts 为准,调用实现在 src/api/walking-editor.ts。

方法与路径 请求 返回 data
GET 空路径 无 WalkingEditorView
PUT 空路径 expectedRevision、expectedExperienceDraftRevision、draft WalkingEditorView
POST /resource-signatures files: [{clientId, relativePath, originalPath, sizeBytes, kind}] batchCode、uploadUrl、expiresAt、files: [{clientId, relativePath, formFields}]
POST /resource-completions {batchCode} {resources: WalkingResource[]}
POST /checks expectedRevision、expectedExperienceDraftRevision WalkingEditorOperation
POST /builds expectedRevision、expectedExperienceDraftRevision、checkId、capabilityIds WalkingEditorOperation
POST /imports expectedRevision、sourceResourceId WalkingEditorOperation,含 importCandidate
GET /jobs/{jobId} 无 WalkingEditorJob

签名中的 clientId 原样回传,关联本地文件;不能按叶文件名匹配。文件直传到 uploadUrl,使用各自 formFields + 原 File,最多四路并发,不重新编码或改变材质。complete 由服务器核验真实对象,返回 clientId、resourceId、relativePath、originalPath、bytes、sha256、kind、status(READY/PROCESSING/FAILED)。hash 必须为服务器核验的 64 位 SHA256。相同 batchCode 的 complete 必须幂等,不能重复新增资源。签名过期/结果未知的新批次使用新对象,不覆盖旧对象;确认接口不得信任客户端哈希或文件索引。

草稿、并发与异步

WalkingEditorView 必须包含 apiVersion=1、revision、experienceDraftRevision、sourceVersion、draft、resources、skills、presets、featureSupport、check、latestBuild、experienceDraft。未检查/未构建使用 null,不能伪填 PASSED。404/405/501 在后台显示“接口待接入”,用户仍能选择文件但不能上传/保存。

草稿结构包括 enabled、entryResource、modelResource、dependencyResources、walkPolicyResource、walkSkillId、features、football、pickupTarget、resourceIds。所有 Resource 字段提交真实 resourceId;resourceIds 可包含未绑定素材。features 每项包含 enabled、skillIds、configResource、policyResources、modelResource、dependencyResources、mappingResource、autoTrigger。足球绑定为 {presetId, version, visualResource},拾取物额外有 kind。允许保存不完整草稿,缺文件不等于能构建或发布。资源引用必须属于当前项目,未启用功能不阻断基础校验。

PUT 同时校验独立行走 revision 和全项目 experienceDraftRevision,原子更新两者。返回新的完整 experienceDraft 快照;其中 walkingEditorRevision 指向已保存的行走表单版本。普通整机/装配草稿写入必须保留此令牌,不能因为旧 walking 字段为 null 就清除新表单。构建以该令牌组合整机、装配和行走,绑定全项目修订号。禁用新行走模块应通过新版 draft.enabled=false 保存;不得让旧版入口意外覆盖新版本。PUT 返回与接受值语义一致的 draft,若需要规范化或补充功能绑定,返回显式导入候选供确认,不能静默修改用户选择。

冲突返回 409,后台保留本地文件与表单,刷新核对后才可再次提交。网络/5xx 的写入结果不明时先查状态,不自动重发。长任务返回 jobId,后台串行查询(两秒间隔),离开页停止;查询失败可继续查询相同任务,不再次创建操作。Job 状态为 QUEUED/RUNNING/SUCCEEDED/FAILED;完成返回 view,失败保留旧发布版本并带具体报告。sourceVersion 覆盖配置和资源内容,任一变化使旧 check/build 失效。

ZIP 导入先上传 archive,再解析;返回 view.resources 和 importCandidate。候选确认只应用本地表单,后续仍需保存、校验;不直接覆盖已发布数据。未绑定额外文件保留草稿。无效路径、符号链接、重复路径、解压限制、LFS 指针等由服务端检验,不能信任 ZIP 内自带 manifest 的哈希或能力声明。

分功能检查与部分发布

check 包括 checkId、draftRevision、sourceVersion、base、features[]、communityRuntime。base/feature 各有 capabilityId、status、message、issues[];issue 带 scope(base/feature)、capabilityId、code、path、message。status 为 PENDING/PASSED/FAILED/UNSUPPORTED/NOT_RUN。PASSED 需代表实际契约和运行检查完成,不能仅检查文件名。未部署运行器为 pending/unsupported,禁止生成可发布演示。

基础失败阻断整次发布,选填功能失败只影响该功能。后台明确列出失败项,并让用户确认已通过子集 capabilityIds;必须包含 walk,包含全部功能依赖,且均属于本次同一 sourceVersion 的有效检查。服务端再次验证子集,按它重新编译 robot.skills、输入绑定、道具和依赖闭包。失败或未选的功能与额外素材保留草稿,不进入发布依赖,不自动删除。

build 返回 WalkingEditorBuild(draftRevision、sourceVersion、checkId、capabilityIds、experienceBuild)。experienceBuild 沿用全项目模型构建结构及最终 SHA/revision 发布接口。只有同版本检查通过、运行器 supported、构建 publishable 且 report PASSED 才能预览/发布。后端必须重新核验这些条件,不能信任 UI 的按钮禁用。发布为不可变快照,用户修改草稿不会改变当前线上演示。

联调顺序:GET 初始化与预设 → 签名/直传/确认 → PUT 乐观锁 → 分功能检查 → 子集构建/预览 → 原子发布 → 社区按能力展示。前端自动化使用模拟接口验证流程;真实文件推理、预设物理效果、社区资源按需加载及生产接口需要后续联合验收。

工程文件夹入口与页面命名补充

后台入口统一命名为“装配与仿真”。行走表单支持直接选择工程根文件夹,不要求压缩为 ZIP;目录文件复用上述批量签名/直传/确认接口,无需新增解压接口。去掉所选外层目录名,保留包内子路径;原路径保留在 originalPath。识别根 robot.json,绑定明确的 model 路径;只有唯一 primary ONNX 时自动绑定基础策略,多个 primary 时由用户选择。已有基础绑定保留,额外动作默认关闭。所有目录资源均可上传,服务端应从这些资源按 MJCF/配置的真实引用解析基础依赖闭包,未绑定且未被引用的素材不进入发布版本。目录不含 robot.json 时提示补充,不能冒充已完成配置。ZIP 继续作为可选导入。

2026-11-02:点击编排与组件总装

后台装配编辑器默认显示空场景。直接装配时,点击右侧零件即追加一个步骤;再次点击已编排零件只定位预览,不重复安装。仅已编排零件写入公开流程,未使用的 GLB 仍留在项目零件库。当前实现保留已有装配 JSON 中的工具、安装动画等扩展字段及其文件校验记录。

新建流程会用零件 GLB 内部节点名匹配整机 GLB 的唯一同名节点,并核对局部包围范围(整机与分件可经过不同顶点去重,不要求顶点数量相同)。最终外层变换为 整机节点世界矩阵 × 零件节点世界矩阵的逆矩阵。节点重名、几何不匹配或多节点变换不一致时不猜测位置;界面提示该零件待匹配。已有流程的最终位姿保持不变。

组件模式由管理员主动选择,普通模式不自动生成组件。上传接口仍是 assembly-json,公开 JSON 保持 schemaVersion: 1、kind: assembly 和原有 files / parts / steps;新增可选字段:

{
  "componentPlan": {
    "version": 1,
    "components": [
      { "id": "head", "name": "头部", "parts": ["head-shell", "head-cover"] },
      { "id": "body", "name": "躯干", "parts": ["body-shell"] }
    ],
    "connections": [
      { "id": "head-body", "name": "头部连接躯干", "members": ["head", "body"], "installOffset": [0, 0.08, 0] }
    ]
  }
}
  • steps 仍只记录每个零件一次,保留原始点击顺序;components 的排列决定组件制作顺序。组件内部按 steps 中的相对顺序播放。
  • 播放头部的步骤时只显示头部累计装好的零件;进入躯干阶段后收起头部,只显示躯干进度。坐标始终沿用整机位置,收起不改变数据或删除模型。
  • connections 依次连接已完成组件,也可引用更早连接的 id,形成多层总装。每完成一个组件,就立即插入所有依赖已就绪的连接,再开始下一组件。例如:头部零件 → 躯干零件 → 头部与躯干拼接 → 左腿零件 → 加装左腿。第一个成员为基体,其余成员沿同一个世界坐标偏移刚性进入,保留内部相对位姿,不再逐件重装或播放螺丝动画。
  • 每个零件只能归属一个组件,每个组件或连接结果只能被后续连接消费一次;禁止自引用、循环、引用未来节点和重复消费。保存时要求当前工作区先命名为组件,并把所有组件连成一个总装根节点。
  • 后台预览支持空场景、前后一步、进度拖动、播放到当前步骤、重播当前步骤和查看整体。未显示的零件不提前解析渲染;浏览器预览可缩小解码贴图,上传原字节和校验值保持不变。
  • “预览到此步”固定目标,从第一阶段依次播放直到该阶段;“重播本步”只播放当前阶段。前进由真实模型动画完成事件触发,不用独立定时器跳步,支持暂停和继续。
  • 组件工作区的“拼接已有组件”支持将当前未命名零件直接保存为组件并新增连接;已被消费的组件不重复列出,后续选择它已完成的总装。步骤列表包含零件安装和组件拼接,可点击定位任意阶段。

前台交接状态: 本仓库已实现组件编排、JSON 生成、回读和后台预览。当前 vibemake-site/js/experience-packages.js 的旧播放器只累加 steps.parts,还没有读取 componentPlan,因此不能据此宣称社区前台已实现组件收起和连接。前台接入时可对照本仓库 src/utils/assemblyWorkflow.ts 中 assemblyStages() 的阶段规则:每阶段包含明确的 parts(可见集合)、entering(本步进入集合)、offset(组件连接的世界偏移)。前台需在校验原有零件步骤后编译组件阶段,按每阶段的可见集合替换显示状态,而不是继续累加全部历史零件。

2026-11-02:工具拧入、工作端校准与直接定义组件

  • 顶部撤销、重做使用带文字的按钮。普通装配选好零件后可直接点击“定义为组件”,在对话框勾选成员、填写名称;确认后进入组件列表并保留已有步骤顺序。
  • 模型下方直接显示当前步骤的六个进入方向、毫米距离和“使用工具拧入”。组件连接阶段也可在这里设置整体进入方向和距离;工具只用于单个零件的安装步骤。
  • 工具下拉框来自当前项目已上传的 GLB 清单。已经作为装配零件选中的文件须先从流程移除才能用作工具;工具进入独立工具库,不自动生成“安装工具”的步骤。工具文件仍通过 model-parts 上传,无新增后端接口。
  • 新工具首次使用先校准工作端:在工具模型的工作端端面中心点击,获取包含内部节点变换的 GLB 场景根坐标与端面法向;可在校准窗口微调毫米坐标、选择六向或反转。工作轴表示从工具尖端朝螺孔内的方向。已有工具复用原校准,未声明工作轴的旧工具可从工作端附近端面测量。
  • 螺丝头采用几何主轴、端面法向与两端宽度识别。只在能区分宽头和窄杆时自动配置;不能区分时明确提示,可指定局部拧入轴,或在零件模型上点选螺丝头。不可静默把未知零件当成螺丝或把工具默认成 +Z。
  • socketPosition、axis 使用螺丝 GLB 场景根坐标,tipPosition、tipAxis 使用工具 GLB 场景根坐标;installOffset 仍使用螺丝父坐标。计算进入偏移时包含螺丝自身旋转和等比缩放。工具对齐、插入、旋转与退出沿用前台 js/assembly-motion.js 的四阶段规则。
  • 保存时自动写入根节点 tools: [{id, file, tipPosition, tipAxis}] 和零件上的 installation: {type: "screw", toolId, axis, socketPosition, toolQuaternion, direction, turns, travel, approachDuration, engageDuration, tightenDuration, retractDuration, toolClearance}。工具路径、字节数和 SHA-256 自动列入 files。工具 GLB 与原零件 GLB 保持原字节;关闭某颗零件的工具效果会移除该零件的 installation,已校准工具保留以便复用。
  • 旋转圈数为 1–20 整数,拧入行程为 0.01–100 毫米;动画各阶段范围与现有前台校验一致。螺丝及其父节点须等比缩放。旋转以插入点为轴心,工具临时挂在螺丝下,拧入完成后精确恢复原最终位置和方向。
  • 改动工具、圈数、行程、转角或螺丝头校准后需“应用工具并预览”;未完成的工具配置会阻止保存,避免保存旧参数。播放步骤按实际工具动画时长等待;支持暂停,切换步骤和查看整体时清理临时工具。

验证:使用当前小鸭子 165 颗杯头螺丝的原始 GLB 核对识别方向与插入点,全部通过,最大插入点差异约 0.000419 毫米。另有六个方向、父级旋转与缩放下的工作端/插入点重合测试,以及工具保存、回读、关闭效果测试。此处描述的是视觉对齐与动画格式,并未增加工具碰撞检测。

2026-11-02:独立组装与继续拼装

每个零件安装步骤可设置“本步展示”。独立组装只显示当前组件的进度;从续装切回独立组装时,以本步零件开始新场景。继续拼装明确选择一个更早的步骤为基准:保留基准阶段的全部已安装零件,仅把本步 parts 作为新增安装集合。后续选择新零件时沿用当前续装进度,也可切回独立组装。组件拼接阶段本身保留基体,不显示这个切换。

字段仍由后台生成,通过现有 assembly-json 接口上传原 JSON;不增加文件上传接口:

{
  "steps": [
    { "id": "install-leg", "label": "安装腿", "parts": ["leg"],
      "scene": { "mode": "continue", "base": { "kind": "connection", "id": "body-head" } } }
  ],
  "sceneSequence": [
    { "kind": "step", "id": "body-step-1", "componentId": "body" },
    { "kind": "step", "id": "body-step-2", "componentId": "body" },
    { "kind": "step", "id": "body-step-3", "componentId": "body" },
    { "kind": "step", "id": "head-step", "componentId": "head" },
    { "kind": "connection", "id": "body-head" },
    { "kind": "step", "id": "install-leg" }
  ]
}

上例为字段片段,省略其余原有零件、步骤与组件定义。scene.mode 为 independent 或 continue;后者必须有 base。引用使用稳定编号,不使用页面上的第几步:kind=step 引用 steps.id,kind=connection 引用 componentPlan.connections.id;可选的 componentId 区分一个多零件步骤拆到多个组件时的阶段。组件重命名不改引用;分组变化时只在目标阶段唯一的情况下重新匹配。

  • sceneSequence 固定包含零件和组件拼接的播放顺序。旧 JSON 没有这些字段时沿用旧的组件规则;启用新标记后保存完整顺序,保证“躯干三步 → 独立的头 → 头躯干拼接 → 在总装上装腿”不会被按类型重新排序。
  • 续装阶段的可见集合为 基准.parts ∪ 本步.entering,进入集合只有本步零件。后续未单独指定方式的同一工作区步骤沿用续装上下文;保存时补成明确 scene。总装后再接独立制作的组件时,基体包含已经续装的零件,避免腿等附件消失。
  • 尚未分组但已经续装到总装的零件可以直接保存,无需再命名为组件或添加一次重复拼接。独立零件仍要求完成组件定义;依赖必须指向更早阶段,禁止缺失、自引用、向未来引用和循环。删除基准及会间接移除基准的操作会被拦截,先修改依赖步骤再删除。
  • 新标记、基准和顺序随保存、回读、撤销与重做保留。模型最终位姿、材质、原文件和校验值不变。步骤列表用“独立组装”或“继续拼装 · 接第 N 步”显示规则。

前台需同步读取 scene 与 sceneSequence,或对照 assemblyWorkflow.ts 编译完整阶段;只累加旧 steps.parts 的播放器无法还原独立场景与续装分支。本次实现范围是后台编辑、预览、JSON 和回读。

2026-11-02:整机参考与当前装配双视窗

编辑器左侧固定为整机参考,使用同一零件库的最终安装位姿;右侧固定为当前步骤的装配进度,最右边保留零件、步骤和组件列表。底部播放控制与安装设置保持在一屏内。工具文件不作为整机零件显示,未能定位的零件沿用原有警告。

左侧支持点击模型零件隐藏,以及通过“显隐”搜索、查看已隐藏项、逐个恢复、全部显示或全部隐藏。“恢复整机参考”恢复左侧完整显示并重置参考视角;两边可分别旋转、缩放和重置视角。显隐为临时参考状态,不修改步骤、位姿、资源、JSON 或编辑历史,右侧安装、撤销和播放不清空左侧显隐选择。为双视窗控制浏览器预览占用,参考视图降低渲染像素与解码贴图预算,原文件、原材质参数与上传字节保持不变。

2026-11-03:独立组件库与总装步骤分开

编辑器增加显式的“步骤编排 / 组件制作”操作切换。旧版“直接装配 / 组件装配”的既有时间线、连接与 JSON 保留兼容;新组件库独立于旧 componentPlan。创建组件、创建子组件、修改内部步骤不会自动加入或重排项目总装。总装通过“加入总装步骤”显式引用顶层组件;组件通过“加入当前组件”显式引用直接子组件。空组件允许先保存,作为待制作的部位。名称在同一级唯一,可以分别命名躯干、躯干1、躯干2。

内部 Assembly 新增 componentLibrary: { version: 1, components: [{ id, name, parentId, parts, steps }] }:

  • id 稳定,重命名不改编号;parentId 为 null 或同库上级 ID,只表达目录归属,不自动生成步骤。
  • parts 只记录这个组件直接拥有的零件实例;不同组件不能拥有同一个实例。上级引用子组件不重复取得零件所有权。
  • steps 是组件自己的有序安装步骤。可使用现有方向、工具、独立/续装场景;引用直接子组件时,步骤额外携带 componentId、完整叶子 parts 快照和 installOffset。子组件内部步骤不展开到上级或总装时间线。
  • 根 steps 仍仅为总装顺序。引用组件时必须选择顶层组件,叶子零件不允许重复进入总装。组件引用整体平移,不再次播放内部螺丝工具效果;安装方向/距离只修改该引用的偏移,不修改内部零件参数。
  • 组件引用只同步叶子清单,不插入或移动外部步骤。保存校验层级/引用循环、零件重复归属、未知组件、错误上级、重复使用、失效引用与内部步骤数据。删除有子组件或被步骤引用的组件会被拦截。撤销/重做同时覆盖库和总装。

当前单人上传继续使用 /resources/assembly-json/signature 与 PUT /resources/assembly-json,原文件、哈希与工具文件不变。公开 JSON 根 parts/steps 只包含总装使用的实例/步骤;componentLibrary 扩展保存上述目录、内部步骤,并有 parts 数组保存尚未进入总装的实例定义(同公开 part 结构,使用 file 而非内部 assetId)。回读合并根 parts 与库 parts 并验证文件哈希。因此只有组件库时根 parts/steps 可以为空,仍可以重新打开继续制作;既有总装的步骤、顺序不会因创建组件而改变。前台应以非空且有效的总装步骤决定播放入口,不能仅凭有 assembly URL 就展示可播放;组件库本身不应作为公开播放序列,后续播放器需支持引用级 installOffset。

协同接口尚未实现,不能把本次 UI 视为已支持安全的多人同时保存。 当前后端只原样存 JSON 并替换项目级绑定,没有组件 revision、共享零件实例清单版本、占用事务或条件更新。前端当前归属检查仅针对加载的快照;整个库仍随项目 JSON 一并保存,不是组件级云端增量更新。

后端联调下一步应提供:共享零件实例固定 ID 与 catalogRevision;组件独立的 revision/版本快照;保存请求包含 expectedRevision、catalogRevision、requestId 和组件步骤;在同一个事务内校验版本、权限、零件唯一归属、引用依赖并提交,冲突返回明确的组件/零件和最新版本。总装应独立保存并引用固定组件版本,组件保存不直接替换已发布总装。现有 JSON 上传/导入、零件增删、清除也必须遵循同样的版本规则;前端提交前先 GET 不能替代后端原子校验。接入之前不开放“多人协同已启用”的提示,也不自动合并或覆盖冲突内容。

2026-11-03:统一选择与分段标记(当前交互,以本节为准)

删除“直接装配 / 组件装配”以及“完成并命名 / 拼接已有组件 / 连接所选组件”的重复入口。现在只有“创建组件 → 步骤编排”:组件制作独立于总装,保留父子组件;编排侧栏仅有“组件与零件”和“步骤”两页,组件树与零件列表同屏,支持统一搜索。勾选组件即追加一个组件步骤并自动勾选所有叶子零件;取消组件选择撤销对应步骤,成员也取消选中。已有散件/组件的任何叶子交集都会阻止再次选中,部分重叠以半选状态提示。零件随组件选中时不能单独移除;应先取消组件,或回到原组件修改内容。

总装可选择任意层级的组件,也可单独选择组件中的某个零件;只要同一总装实例不重复即可。目录归属和实际选中是两种关系:同一零件仍只能由一个组件直接拥有;总装引用或选择成员不再次取得其所有权。制作某个组件时只允许选择其直接子组件与未被其他组件占用的零件。上述总装规则替代上一节“只可引用顶层组件”和“总装不能选择已归属组件的散件”。

拼装采用稀疏分段:

  • 第一步开始展示;未标记的后续步骤默认 上一阶段.parts ∪ 本步.parts,进入集合只有本步选择的零件/组件。不要求每步填写展示方式。
  • “新拼装”在当前步骤写 scene: {mode:"independent"},从本步进入集合重新开始;后面未标记步骤继续在此基础累加,直到下一显式标记。
  • “继续拼装”可选择更早步骤,写 scene: {mode:"continue",base:{kind:"step",id}};从该进度加装本步内容,后续步骤自动继承。取消标记即恢复接上一步。
  • 用户主动标记的步骤额外有 sceneMarker:true,保存后保持;默认继承步骤没有 scene、没有 sceneMarker,保存时不再逐步物化。旧版自动生成的相邻 continue 可在首次编辑时清理,新版用户标记不清理。
  • 引用/删除保护只针对显式续装基准。删除普通中间步骤会自动重新接上有效的上一阶段;移动带标记的步骤保留标记,失效/向未来引用阻止保存。回看旧步骤后再选择零件,仍追加到末尾并继承末尾进度。

旧 componentPlan 的分组与嵌套连接在本地编辑时整理为组件库层级,原分组内部步骤保留,连接作为上级组件中的子组件选择。主流程引用完成的组件,不再把内部准备和总装都作为重复叶子安装。原文件、零件编号、最终位姿、工具配置保留,旧服务器 JSON 在保存前不改动;存在无法唯一转换的引用时应保留原文件并提示问题。新 JSON 仍由现有原样存储接口保存,协同版本/占用事务仍待后端实现。

播放器需按本节默认累加、稀疏 scene 标记和组件引用整体 offset 编译阶段;不要把所有未标记步骤当成“独立新场景”,也不要将组件内部步骤追加到总装。可对照 assemblyStages()。已覆盖混合选择去重、分段继承和接回旧进度、稀疏保存回读、预览暂停恢复、旧组件整理、父子组件存储和工具配置的自动化检查。