threejs-compatibility-fallbacks

Three.js 兼容性回退

将回退视为经过明确授权的产品分支。规范的 WebGPU/TSL 工作以及原生 WebGPU 质量调优仍由其所属技能负责。

1. 激活分支

在选择实现方案前，记录以下所有内容：

• 用户明确请求在 WebGPU 不可用时进行回退；
• 已明确识别并完成初始化的非 WebGPU 后端，或在指定目标上可复现的、与功能支持相关的初始化失败；记录实际发生的状态，不要仅凭缺少 isWebGPUBackend 属性推断后端；
• 规范实现的负责人及确切功能；
• 已接受的视觉、物理、时间、交互、性能和维护方面的损失范围；
• 兼容性分支的维护负责人。

仅在 await renderer.init() 成功后检查后端身份。在 r185 中，renderer.backend.isWebGLBackend === true 可明确识别已初始化的 WebGL 后端；标志缺失或未知并不能作为证明。初始化被拒绝时，记录确切错误，并将已初始化后端身份保留为未知。将应用或配置异常交由调试处理，不要伪装成硬件不可用。WebGPU 初始化成功时，返回规范实现的负责人处理。若用户未明确请求回退，则报告规范实现的阻碍。使用已安装 API 提供的已初始化或部分初始化清理路径，清理探测所用的资源和监听器；若要使用不同的渲染器栈，则使用单独的新画布。

当五项激活事实均已记录且规范实现保持不变时，此步骤完成。

2. 对规范行为进行分类

列出规范功能在几何、辐射度、颜色、时间、交互、状态所有权和生命周期方面的不变量。将每一项归类为：

• preserved：保留相同的量，且证明方式仍然适用；
• weakened：保留该量，说明变化后的误差、支持范围、更新节奏、陈旧程度或适用范围，并冻结新的门槛；
• removed：标记该能力为不支持，并移除依赖它的声明。

在跨系统边界上，保留意味着单位、坐标系/原点、时间区间与采样相位、所有者、生产者/消费者版本、支持范围/滤波、有效性/陈旧程度/误差、速率与积分语义、单向或双向反应范围、稳定身份、不可变的上一帧/当前帧呈现状态、重置行为及 GPU 完成依赖均保持不变。语义不同的近似方案应归类为弱化或移除。稳态帧中的 GPU 到 CPU 回读必须排除在关键帧路径之外。

当每项规范声明都恰有一种处置方式，且每个弱化或移除的条目都注明其对用户可见的影响时，此步骤完成。

3. 选择最诚实的首选表示方式

针对每项功能，按以下顺序选择：

1. 当可移除交互时，使用预计算或静态的规范输出；
2. 使用有界的 CPU/离线生成，并声明上传节奏、延迟、内存分配和丢失的动态效果；
3. 移除功能，并同步调整 UI/文档及相关声明；
4. 在明确接受维护责任后，使用隔离的旧版分支。

选择不支持能力的处理方式时，请阅读降级决策矩阵。只有在实现或验证旧版/API 分支时，才阅读 r185 API 映射；并针对已安装的版本重新验证每个符号。

当所选表示方式是最早满足所有 preserved 不变量及所有弱化不变量冻结门槛的选项，且所有剩余损失均已明确说明时，此步骤完成。

4. 隔离所有权

为兼容分支单独设置导入项、构建／部署入口、测试、制品、能力门控和维护负责人。在分支内保留一个场景信号图，以及一个色调映射／输出变换负责人。记录颜色纹理与数据纹理的领域、资源的创建／重置／调整大小／释放，以及规范资产与兼容资产之间的边界。

当节点渲染器分支需要 GPU 时间戳时，必须在初始化前通过 trackTimestamp: true 构造渲染器。经典 WebGLRenderer 没有此选项或 resolveTimestampsAsync() API；它需要使用自身支持且经过验证的计时器查询检测方案，否则应判定为证据不足。旧版分支只有在激活后才能使用 WebGPURenderer( { forceWebGL: true } )；它仍是兼容产品，而非规范渲染器。选择一套连贯的技术栈：带 WebGL 后端的 WebGPURenderer 保留节点材质／TSL 和 RenderPipeline 模型；WebGLRenderer 使用经典的 ShaderMaterial 和 EffectComposer API。forceWebGL 不会把前者变成后者。不要在这两套技术栈之间共享不兼容的材质、通道、渲染目标或特定于渲染器的资源。保留应用状态，并通过明确的分支适配器恢复其控件，而不是保留旧 GPU 对象。

禁用或删除兼容入口后，规范构建和运行时图保持不变，且每项分支资源都有唯一负责人和释放路径，即表示此步骤已完成。

5. 验证变更后的声明

如果已安装 $threejs-visual-validation，则针对每项保留或弱化的声明调用它。由其负责人进行验证时，以规范证据为准，只采集能够支撑声明的视图、跟踪记录和诊断信息，并测试适用的重置、调整大小／DPR、转换、拆卸以及释放／重新创建路径。声明预热完成后，持久性资源必须趋于稳定。

如果没有该负责人，请报告这一情况，并对受影响的声明返回 INSUFFICIENT_EVIDENCE；不要在此技能中构建替代验证。缺少时间戳同样意味着无法进行所需的 GPU 归因，应返回 INSUFFICIENT_EVIDENCE；呈现时间或 CPU 耗时仅能作为端到端证据。

每项保留的声明都有判定结果，所有已删除的声明均不再出现在产品表述中，输出转换只有一个负责人，并且生命周期／资源声明要么在验证中趋于稳定或验证失败，要么以 INSUFFICIENT_EVIDENCE 标记并注明缺失证据，即表示此步骤已完成。

输出

每项功能返回一行：

功能	目标	保留	弱化	移除	表述	验证

另请记录激活事实、隔离的入口和维护负责人、输出负责人、生命周期结果、不受支持的声明、任何缺失的验证负责人，以及每项 INSUFFICIENT_EVIDENCE 判定所需的确切证据。