用途
该技能专门用于将已有的 IWSDK 0.4.x 应用迁移到 IWSDK 0.5.0。它强调这是迁移而非重写:保留可用的运行时逻辑,只把静态组合内容迁移到原生场景格式,并在实时运行时中验证行为一致性。技能以 IWSDK 0.4.2 作为公开对比基线。
版本适用范围有明确边界:如果项目已在 0.5.x,则只诊断所报告的问题,不重放迁移;如果低于 0.4.x,需先完成中间版本的迁移;如果高于 0.5.x,应使用对应版本边界的技能。
主要能力
技能按阶段组织迁移流程:
- 阶段 1:迁移前盘点:根据锁文件确定包管理器,收集所有 @iwsdk/* 依赖及版本、涉及 glxf、metaspatial、compileUIKit、vite-plugin-uikitml、vite-plugin-gltf-optimizer、mkcert 等的导入与配置调用,以及 World.create、World.loadLevel、PanelUI、ScreenSpace、Visibility、render.defaultLighting、features.spatialUI 的使用情况;把静态对象分类为资产、场景节点、玩家空间子对象或动态对象,形成对齐检查清单。
- 阶段 2:对齐包版本:把所有已使用的 IWSDK 包更新到 0.5.0,不混用 0.4.x 与 0.5.x;移除 @iwsdk/glxf、@iwsdk/vite-plugin-gltf-optimizer、@iwsdk/vite-plugin-metaspatial、@iwsdk/vite-plugin-uikitml、vite-plugin-mkcert 等已退役包;不因 @iwsdk/scene-composition 是新包就添加,除非应用代码直接导入其 API。
- 阶段 3:简化 Vite 配置:移除 mkcert、Meta Spatial、UIKitML 编译和 glTF 优化器的插件与导入;创建 iwsdk.config.json 作为项目的唯一权威配置,选择场景以及无扩展名的 assets.module 和 components.module 路径,并存储可序列化的 world/emulator 选项;HTTPS 默认开启,使用缓存的不受信任证书。
- 阶段 4:创建共享清单:用 defineAssets 定义资产目录(支持 glTF、UIKitML 及无父级的程序化 Object3D 原型),用 defineComponents 声明应用组件,并通过虚拟模块 virtual:iwsdk-project 向 World.create() 提供相同导出。
- 阶段 5:替换 GLXF 或代码编写的静态布局:创建 public/scenes/main.iwsdk.scene.json,用稳定的节点 id、资产引用、变换和组件值表达静态内容;用 player-space 父节点表达附着于玩家、相机、头部、目标射线或握持空间的内容;用 DomeGradient/DomeTexture 表达可见背景,用 IBLGradient/IBLTexture 表达基于图像的照明;移除 render.defaultLighting;0.5 没有 .glxf 的运行时回退路径,需以旧场景和截图作为视觉参照重建静态层级,无法对齐则停止并报告迁移未完成。
- 阶段 6:迁移 UIKitML:把源 .uikitml 文件放入 public/ui/,删除生成中间 JSON;面板 URL 从 .json 改为 .uikitml;移除 PanelUI 的 maxWidth/maxHeight;spatialUI 配置从 kits 改为 kit 加可选 componentSets;通过稳定场景与元素 id 定位面板元素。
- 阶段 7:处理行为级兼容性:检查 createTransformEntity() 现在自带 Visibility、优先使用 RayInteractable 而非已弃用的 Interactable、移除 xr.features.lightEstimation、沉浸式 AR 始终隐藏编写的穹顶/背景视觉、AssetManager.getGLTF() 默认返回新克隆、ScreenSpace 显式尺寸等。
- 阶段 8:递增范围验证:运行格式化、类型检查、测试和生产构建;启动 0.5 开发服务器并等待浏览器连接与命令就绪;验证并打开每个原生场景;在编辑器视图对比层级、变换、可见性、灯光、面板和相机视图;在运行时视图测试交互并检查控制台;进出 XR 验证屏幕空间面板恢复;调整桌面窗口验证 UIKit 布局;如有物理头显,接受自签名证书警告后进入 XR。
使用方式
用户上下文通过 $ARGUMENTS 传入。技能要求先检查 package.json 和锁文件中的已安装版本,编辑前查看 git 状态并保留所有现有工作,在转换 GLXF、场景文件或 UI 源码前创建可恢复检查点;删除包前先盘点所有导入、配置钩子、脚本和生成输出是否已被替换。
适用场景
适用于需要跨 0.5 边界升级、替换 Meta Spatial Editor 或 GLXF、移除退役包的 IWSDK WebXR 应用。
限制
技能明确要求:不得仅因应用编译通过就声称 GLXF 或 Meta Spatial 场景已完成迁移;动态行为应保留在 TypeScript/JavaScript 中,原生场景只负责静态组合、组件值、变换、灯光、面板和玩家空间附着;不得把资产与组件清单同时导入 index.ts 或在 iwsdkDev() 中配置;不得在迁移中重新生成 IWSDK 库参考语料。完成报告需包含检测到的源与目标版本、包增删、遗留件处理、迁移文件、行为变更、实际运行的自动与实机测试,以及仍待验证的视觉或物理头显检查。