HarmonyOS 7 新特性3：TiledGSNode——轻带看让 71MB 庭院按视口按需加载：真机实测与零请求降级

HarmonyOS 7 新特性3：TiledGSNode------轻带看让 71MB 庭院按视口按需加载：真机实测与零请求降级

文章目录

[HarmonyOS 7 新特性3：TiledGSNode------轻带看让 71MB 庭院按视口按需加载：真机实测与零请求降级](#HarmonyOS 7 新特性3：TiledGSNode——轻带看让 71MB 庭院按视口按需加载：真机实测与零请求降级)
- - - 1、引言
    - 2、效果展示与项目结构
    - - [2.1 产品动线：三个 Tab 各承担一段交付责任](#2.1 产品动线：三个 Tab 各承担一段交付责任)
      - [2.2 监控浮层与观测日志上屏：把仪表做进产品](#2.2 监控浮层与观测日志上屏：把仪表做进产品)
    - [3、Kit 能力与核心 API 深度解析](#3、Kit 能力与核心 API 深度解析)
    - - [3.1 TiledGSNode 在 Spatial Recon Kit 里的位置](#3.1 TiledGSNode 在 Spatial Recon Kit 里的位置)
      - [3.2 接口面拆解（SDK d.ts 逐条实证，@since 26.0.0）](#3.2 接口面拆解（SDK d.ts 逐条实证，@since 26.0.0）)
      - [3.3 官方设计的供给闭环 vs 真机实测](#3.3 官方设计的供给闭环 vs 真机实测)
      - [3.4 探测降级：把「不可用」变成一条显式路径](#3.4 探测降级：把「不可用」变成一条显式路径)
      - [3.5 大资产加载方案选型对比](#3.5 大资产加载方案选型对比)
      - [3.6 清单 schema：官方未公开部分的探针实录](#3.6 清单 schema：官方未公开部分的探针实录)
    - 4、逻辑流梳理
    - 5、项目实战
    - - [5.1 分块 bootstrap：清单落沙箱 + 相机按包围盒推导](#5.1 分块 bootstrap：清单落沙箱 + 相机按包围盒推导)
      - [5.2 瓦片供给状态机：回调入口去重、并发与黑名单](#5.2 瓦片供给状态机：回调入口去重、并发与黑名单)
      - [5.3 探测降级：4 秒窗口 + 世代校验](#5.3 探测降级：4 秒窗口 + 世代校验)
      - [5.4 Component3D 场景重绑：ForEach 键强制重建](#5.4 Component3D 场景重绑：ForEach 键强制重建)
      - [5.5 世代令牌与统一清理：异步链路的所有权纪律](#5.5 世代令牌与统一清理：异步链路的所有权纪律)
      - [5.6 会话记账与数据页订阅：跨组件的事件总线](#5.6 会话记账与数据页订阅：跨组件的事件总线)
      - [5.7 双设备实测数据](#5.7 双设备实测数据)
    - 6、避坑指南
    - - [6.1 Component3D 只在首次实例化绑定 Scene](#6.1 Component3D 只在首次实例化绑定 Scene)
      - [6.2 @State 字段同名重复声明冻结按钮](#6.2 @State 字段同名重复声明冻结按钮)
      - [6.3 Tab 切换记账竞态：数据页首屏漏掉刚关账的会话](#6.3 Tab 切换记账竞态：数据页首屏漏掉刚关账的会话)
      - [6.4 @Builder 按值传参不建立响应式依赖](#6.4 @Builder 按值传参不建立响应式依赖)
      - [6.5 取证工具链：前台 3D 渲染时不要跑 dumpLayout](#6.5 取证工具链：前台 3D 渲染时不要跑 dumpLayout)
    - 7、总结

1、引言

去年帮朋友交付一批门店扫描资产，无人机环拍加手机补拍，重建出来的 3DGS 场景单个就是几百 MB。交付那天他问我：能不能做个东西，让客户在自己手机上点开就能逛？我试着把庭院资产（裁剪后 71.2MB、30 万高斯）整卡塞进一个渲染视口，Mate 60 Pro 上加载等了十几秒，内存峰值直接顶到几百 MB，换个更大的场景就 OOM。客户视角更直接：他看不到「加载」这个过程的价值，他只看到转圈。

问题不在渲染器，在「整卡」这个前提。客户逛空间的时候，任意时刻真正看得见的只有视口里那一小块------背后那面墙、头顶那片瓦片，此刻根本不需要在内存里。HarmonyOS 7.0 (API 26) 在 Spatial Recon Kit 里新增的 TiledGSNode（分块 3D 高斯泼溅节点） 就是冲这个前提来的：大场景按空间切成瓦片、按 LOD 组织成一份清单 JSON，渲染器根据驱动相机只请求当前视口需要的那几块，应用侧负责把瓦片字节供给到位。官方发布说明的原文是「新增分块 3DGS 渲染对象，支持设置驱动分块选择的相机、设置瓦片请求回调函数、通知渲染器指定的瓦片现在可以加载等」。

这篇我把官方设计的供给闭环在应用侧 完整实现并逐跳真机实证，但也必须先说清楚边界：跨两台设备复现的一个现象是，loadTiledGSNode 能 resolve、回调能注册，但渲染器在当前两个固件 build 上从不发起瓦片请求------按视口加载在当前固件上还没有真正跑起来，用户实际看到的画面由整卡兜底承担 。围绕这个现象，「轻带看」把探测降级做成一条显式设计的路径------分块 resolve 后观察 4 秒，窗口内未观察到请求就声明原因、切整卡兜底，保证用户永远看得到画面。降级不是 try/catch 的兜底，是一条被声明、被记账、被截图取证的产品路径。

支撑这篇文的不是单个 demo 页面，而是三个真实业务切片，它们决定了工程里每一个「看起来多余」的设计：

切片一：客户远程带看。客户在手机上点开空间、拖拽换视角，问「左边那个角落再看看」。这个动作对应渲染器侧的「驱动相机移动 → 重新计算视口瓦片集合 → 回调要字节」，是 TiledGSNode 存在的理由，也是监控浮层里「请求/就绪」计数要上屏的原因------带看体验立不立得住，要看这两个数动不动。
切片二：资产交付双路径 。同一个庭院，扫描重建后产出两条资产：分块清单（22 瓦片 Streamed SOG）与整卡对照档（LOD3 PLY）。空间库里的每个空间描述符同时携带 manifest 与 wholeAsset 两个字段，模式切换就是在这两条路径之间选------这不是为了演示双模式而双模式，是交付现场的真实形态：分块链路不可用时，整卡档就是客户手里那份「至少能打开」的资产。
切片三：会话记账对账。每次带看的模式、加载耗时、时长、瓦片快照写进单例记账，数据页汇总卡与列表必须逐条对得上 hilog。这个切片逼出了两个 ArkUI 状态坑的修复（6.3、6.4）------记账数据对了但首屏显示不对，在交付语境里等同于数据错了。

2、效果展示与项目结构

空间库列表：真实空间「花园庭院」携带两条资产路径（分块 22 瓦片清单 + 整卡 LOD3 对照），样板间、工作室两个 Mock 占位撑产品感，置灰标「重建中/排队中」。

带看页：顶栏模式徽章 + 双模式按钮，降级声明横幅（黄色条）写明降级原因，视口左上监控浮层实时显示相位、瓦片计数、加载耗时、相机方位，视口下方观测日志上屏------截图即行为证据，不用连电脑也能复盘链路。

数据页：本次会话真实记账（模式/加载耗时/时长/瓦片快照）与汇总卡（会话数、分块/降级占比、平均加载耗时），全部由 SessionStats 单例推导；历史记录为 Mock，统计后端接入后替换。

工程结构（实战工程，省略 Mock 与资源目录）：

text 复制代码

entry/src/main/ets/
├── commons/scene/
│   ├── GSSceneLoader.ets        # 插件/场景/相机 bootstrap + 整卡链路 + 包围盒推导相机
│   ├── TiledGSLoader.ets        # 分块 bootstrap + TileSupply 瓦片供给状态机
│   ├── OrbitCameraController.ets# 轨道相机（手势增量 → 方位/俯仰/距离）
│   └── ViewBounds.ets           # 包围盒描述（中心 + 对角线）
├── features/
│   ├── model/
│   │   ├── TourSpace.ets        # 空间描述符：manifest + wholeAsset 双资产路径
│   │   ├── SessionStats.ets     # 单例会话记账 + AppStorage 事件广播
│   │   └── TourMock.ets         # 占位空间与历史演示数据（与真实链路物理隔离）
│   ├── spaces/SpaceLibraryPage.ets
│   ├── tour/TourViewportPage.ets# 本篇主体：双模式 + 探测降级 + 监控浮层
│   ├── data/DataPage.ets        # 快照模式渲染 + @StorageProp 订阅
│   └── mine/MinePage.ets
└── pages/Index.ets              # 四 Tab 外壳 + ForEach 会话键

2.1 产品动线：三个 Tab 各承担一段交付责任

轻带看的动线是「大空间进 → 视口里按需流式浏览 → 离开时留下一笔可对账的记录」，三个真实 Tab 各承担一段：空间库负责资产目录与可用性声明（哪些空间能进、携带哪两条资产路径）；带看页负责加载链路与视角交互，是本篇全部 API 实证的发生地；数据页负责把每次带看的模式、耗时、时长、瓦片快照记成可对账的会话。我的 Tab 是 Mock 静态页，不承载功能也不假装承载。

这条动线里有一个刻意的设计：空间库进入带看时不走「默认模式」，而是走 auto------分块优先加探测降级。理由来自切片二：交付现场没有人会替客户选模式，应用必须自己判断当前固件上哪条路径能出画，并把判断结果声明在横幅里。手动双模式按钮保留给排查与对照，默认路径永远是被探测验证过的那条。

2.2 监控浮层与观测日志上屏：把仪表做进产品

带看页视口左上的浮层实时显示相位、瓦片计数（请求/就绪/失败/去重）、加载耗时与相机方位；视口下方的观测日志区保留最近 12 条链路事件，双写 hilog 与屏幕。这个设计在排查期救过我三次：零请求现象的第一手证据就是浮层截图，不需要连电脑导出日志；降级横幅与浮层同屏出现，客户视角的「为什么是整卡」与应用视角的「因为零请求」在同一帧里对齐。

日志列表的 ForEach 键用全局单调递增 seq 而非数组下标------列表只保留最近 12 条，slice 截断后若用下标作键，每条日志的 index 都会位移，触发全部 Text 节点重建；seq 键让截断只影响被移除的节点。这是审查修订落点，也是 6 节之外一个便宜但真实的性能细节。

3、Kit 能力与核心 API 深度解析

3.1 TiledGSNode 在 Spatial Recon Kit 里的位置

Spatial Recon Kit 的渲染底座是 ArkGraphics3D 的 Scene + Component3D，3DGS 能力由 spatialRender.GSPlugin 提供：loadGSNode 整卡加载一个 .ply/.sog 资产，loadTiledGSNode 加载一份清单------清单描述全量瓦片集合与每个瓦片可用的 LOD 层级，渲染器拿到清单后并不立即取数据，而是等驱动相机动起来、算出当前视口需要哪些瓦片，再通过回调向应用要字节。官方术语页已有词条「Tiled 3D Gaussian Splatting；分块 3D 高斯泼溅」。

这个模型和整卡加载的差异是根本性的：整卡是「应用把数据推给渲染器」，分块是「渲染器按视口向应用拉数据」。拉模型下内存占用由视口决定而不是由场景总量决定------这是官方设计语义，也是大空间能在手机上逛的理论前提；它在当前固件上是否成立，取决于瓦片请求能否真正被触发（3.3 会如实交代：没有）。

3.2 接口面拆解（SDK d.ts 逐条实证，@since 26.0.0）

以下接口面逐条摘自本机 SDK 的 @hms.graphics.spatialRender.d.ts（路径 DevEco-Studio.app/Contents/sdk/default/openharmony/ets/api/graphics3d/，API 26 Release，Huawei 2025 版权头，全套符号 @since 26.0.0），非二手转述：

API	签名	语义与约束
`GSPlugin.loadTiledGSNode`	`(scene, params: TiledGSImportSettings, parent?: Node): Promise<TiledGSNode>`	清单描述全量瓦片集与每瓦片 LOD 层级；resolve 只代表清单被接受
`TiledGSImportSettings`	`{ uri: string }`	清单 JSON 文件路径，空串加载失败
`TiledGSNode.setCamera`	`(camera: Camera): void`	覆盖「驱动分块选择的相机」，默认用场景激活相机；SDK 注释明确驱动相机可以与渲染相机不同
`TiledGSNode.setTileRequestCallback`	`(callback: GSTileRequestCallback	null): void`
`GSTileRequestCallback`	`(tiles: GSTile[]) => void`	一次可能请求多个瓦片
`GSTile`	`{ uri: string }`	一个 GSTile 对应清单中的一个 .sog 文件
`TiledGSNode.notifyTileReady`	`(tile: GSTile): void`	告知渲染器该瓦片字节已就位；渲染器已不需要时为 no-op

版本单独说一句：TiledGSNode 全家是 26.0.0 真新增，底座 GSPlugin 与滤镜能力是 6.0.1 (API 21) 就有的，两者在正文里分开写，不混成一个版本号。

3.3 官方设计的供给闭环 vs 真机实测

官方设计的闭环是四跳：loadTiledGSNode(清单) resolve → setTileRequestCallback 注册 → 渲染器按视口回调 GSTile[] → 应用把瓦片字节放到 tile.uri 指向的位置、调 notifyTileReady(tile)。我在真机上把前两跳 都走通了：清单从 rawfile 落沙箱（loadTiledGSNode 走 file://，官方示例即沙箱路径）、22/22 瓦片预热进沙箱、回调注册成功、loadTiledGSNode RESOLVE 耗时首载 44--63ms（Mate 60 Pro）/ 7--41ms（MatePad Edge）。第三跳------渲染器按视口回调 GSTile[]------在当前固件上从未发生 ；第四跳（供给字节 + notifyTileReady）我在应用侧已完整实现，只是从未被触发过。

第三跳从未发生：渲染器一次瓦片请求都没发，监控浮层「请求 0 · 就绪 0」恒定，画面空白。为排除应用侧因素做了四组判别实验：

拖动视角：方位角 45°→40° 实测变化，请求仍 0------排除「初始相机不在空间树内」；
预置全部瓦片：加载前把清单声明的 22/22 个 .sog 全拷进沙箱清单同目录，仍 0 请求------排除「供给时序/文件缺失」；
清单 schema 五变体 ：PlayCanvas Streamed SOG v1 原 schema、单 LOD 完整树、单叶子单瓦片退化结构、绝对 file:// 路径、最小清单，逐轮真机点击------全部静默；
D 级日志 ：hilog -b D + 16M 缓冲，加载窗口内渲染器侧无任何瓦片/清单/解析输出，连解析失败告警都没有。

再加一组判别力最强的对照：同设备同进程内，整卡 loadGSNode 正常出画（garden 可见、RESOLVE 33ms），分块 resolve 但贡献 0 高斯------插件加载、Vulkan 管线、GS 着色器、相机配置全部正常，断点精确锁定在 TiledGSNode 的瓦片选择子路径。该现象在 Mate 60 Pro（7.0.0.107 R4P3）与 MatePad Edge（7.0.0.107 R6P5，2in1/PC 形态）上逐轮复现。

结论按证据强度写，并把观察与归因分开：观察到的事实 是------TiledGSNode 接口链路在当前两固件可通（resolve + 回调注册），瓦片选择子路径未激活，请求恒 0；整卡同管线可正常出画，排除了渲染管线与相机配置因素。归因（推断，待官方确认）是------「渲染器 TiledGS 选择器在当前固件未启用或存在缺陷」在整卡对照成立后可能性居首，「清单 schema 与渲染器期望不符且解析静默失败」退居第二（官方未公开 schema，五变体全静默仍支持它，但无法单独确证）。需要诚实说明的推断边界：D 级日志「连告警都没有」能说明当前观测方式下没看到日志，不能严格证明解析代码路径根本没进入------静默失败、日志级别不覆盖、异步解析未完成都在剩余可能性里，只有拿到官方 schema、官方样例清单或解析状态接口才能收敛。这个结论直接决定了本篇的产品形态------分块链路保留完整实现（固件修复后即可用），用户体验由探测降级兜底。

3.4 探测降级：把「不可用」变成一条显式路径

面对「接口通、链路不通」，最容易写错的是 try/catch 兜底：resolve 成功了，catch 永远等不到，用户对着空白视口发呆。轻带看的做法是探测：分块 resolve 并注册回调后起一个 4 秒窗口，窗口内未观察到瓦片请求 即判定「瓦片供给链路在当前固件不可用」，显式声明原因（横幅写明「探测：分块链路已通但 4000ms 窗口内未观察到渲染器瓦片请求（当前固件现象）」），切整卡 LOD3 对照出画。这个判定有两个已知边界要写在明处：其一，4 秒阈值是基于当前固件恒零请求的实测设定，固件修复后若渲染器从 resolve 到首次回调的延迟可能超过 4 秒，需在真机上实测延迟分布重新校准；其二，窗口内收到请求也只等于「链路激活」，不等于供给成功与出画------判定升级为 ready 计数与实际出画，同样留待回调真正被触发后做（冷路径上无法真机验证的改造，改了也是纸上修复）。降级会话在数据页单独记一类（degraded），与手动整卡（whole）、分块（tiled）三口径分开记账，不混写。

降级前还有一道守卫：该空间若无整卡资产可兜底，就不发横幅、不进空白态，直接走显式失败文案------「降级」这个词只有在真能降的时候才允许出现。

降级会话的记账口径也值得单独说：数据页把会话分三类------tiled（分块带看）、whole（手动整卡对照）、degraded（探测或失败降级整卡）。这里必须澄清 tiled 的确切语义，否则它和「瓦片请求恒 0」看起来像自相矛盾：tiled 会话的记账口径是「loadTiledGSNode RESOLVE 成功并进入分块带看态」，不代表分块渲染成功 ------当前固件上这笔会话的画面是空白的（或随后被探测降级接管），它记录的是「我发起了一次分块尝试、接口层接受了清单」这个事实。auto 探测轮因此必然产出成对的两笔：一笔 tiled（RESOLVE 成功即开账，探测降级时关账）加一笔 degraded（整卡接管后开账、出画、关账）。汇总卡「分块/降级」一栏显示的是前两类与第三类的计数比，平均加载耗时三类同口径参与。这个口径是交付语境逼出来的：如果降级会话混进整卡计数，「分块链路不可用」这件事在数据页就消失了，而它恰恰是最需要被看见的信息。复验轮的真机数据是 5 会话、2/3、平均 57ms，与 hilog 逐条对账一致------2 笔 tiled（两度 auto 进入，RESOLVE 42/51ms，画面空白后关账）、3 笔 degraded（整卡出画 56/56/80ms），没有一笔手动整卡对照，正好对应那轮操作序列。

3.5 大资产加载方案选型对比

「71MB 庭院上手机」有四条候选路径，选型结论直接决定工程结构：

方案	首帧就绪	内存特征	实现复杂度	结论
整卡 PLY（loadGSNode）	实测 10--80ms（LOD3 档）/ 全量档十几秒	与场景总量线性相关，大场景 OOM	低（一次调用）	对照组与降级兜底，不作主路径
整卡 Streamed SOG 压缩档	介于两者之间	仍为整卡驻留，压缩只省传输不省驻留	低	省流量不省内存，不解决 OOM
TiledGSNode 分块（本篇主路径）	清单 resolve 实测 44--63ms；瓦片随视口渐进为设计语义（当前固件未实证）	设计上由视口决定、与场景总量解耦（当前固件未实证）	中（清单+回调+供给状态机）	主路径；当前固件瓦片选择未激活，保留实现待修复，用户体验暂由整卡兜底
应用层自管分块（自切 PLY + 多 Scene 切换）	取决于自切粒度	可控但需自维护 LOD 树与淘汰策略	高（等于自研选择器）	不做：与官方能力重复建设，固件修复后即成负债

选第四方案的人不少，理由是「不等官方」。我的判断相反：瓦片选择是渲染器内部的视锥/LOD 计算，应用层自管只能做到「按区域换场景」，做不到「同屏混合 LOD」，体验上限低且维护成本高；官方接口已通、只差选择器激活，保留官方链路 + 探测降级是期望值最高的组合。这个判断的代价也写在明处：当前固件上主路径不出画，用户体验完全由整卡兜底承担------所以「主路径」这个词在本篇里指的是投入方向，不是已交付的用户体验。

3.6 清单 schema：官方未公开部分的探针实录

TiledGSImportSettings.uri 指向的清单 JSON，官方只给了一个约束：描述全量瓦片集与每瓦片可用 LOD 层级。schema 长什么样，文档里没有。我的素材管线用 PlayCanvas splat-transform 生成 Streamed SOG，其清单形态是「完整二叉空间树 + 每节点多 LOD + 相对路径 filenames」，与官方描述的语义完全同型，于是把它当第一候选直接上真机------静默。

随后做了五变体探针矩阵，零资产变化、只改清单结构，逐轮真机点击加载。其中最激进的是 v_min------单叶子、单 LOD、绝对路径的最小清单，全文只有 380 字节，直接贴在下面（它就是真机上跑过的那份，脱敏仅去掉了沙箱前缀中的用户段）：

json 复制代码

{"version":1,"asset":{"generator":"splat-transform v3.4.2","chunkGaussians":65536,
 "chunkExtent":8,"chunkMinGaussians":4096},"count":70540,"counts":[70540],
 "lodLevels":1,"lodErrors":false,
 "filenames":["file:///data/storage/el2/base/haps/entry/files/tiled/0_0.sog"],
 "tree":{"bound":{"min":[-20.39873,-2.732265,-16.68474],"max":[19.70347,16.03609,6.321159]},
  "lods":{"0":{"file":0,"offset":0,"count":70540}}}}

变体	结构	结果
A 原 schema	完整二叉树 + 4 LOD + 相对 filenames	resolve，零请求
v_lod1	单 LOD、完整树	resolve，零请求
v_flat	单叶子、单 LOD、单瓦片（退化结构）	resolve，零请求
v_abs	完整树 + 绝对 `file://` filenames	resolve，零请求
v_min	单叶子 + 绝对路径（最小清单，见上方 JSON）	resolve，零请求

五变体全静默、D 级日志零输出。这组证据能确凿支撑的结论 是排除法的一部分：供给时序、文件缺失、相机位置、单一 schema 形态、单一设备/固件 build 这些应用侧与个体侧的解释都被排除了，断点在渲染器的瓦片选择子路径。但要把观察和归因分开记：观察是「加载窗口内渲染器侧对清单零反应、连告警都没有」；归因上「选择器未启用/存在缺陷」居首、「schema 不符且解析静默失败」居次（3.3 的排序依据同此）。必须承认归因的边界：「零日志」不能严格证明「解析路径未进入」------如果渲染器的清单解析根本不打 D 级日志，静默失败与未进入在现有观测手段下不可区分。要收敛这两个假设，需要的是官方输入：公开的 schema、官方样例清单、或解析状态/错误契约------这超出了本篇应用侧探针能到达的边界，留给官方渠道（论坛/工单）与新固件复验去回答。

对读者的实操建议：在官方公开 schema 或新固件激活选择器之前，不要在生产链路里押注任何第三方清单格式；把清单生成做成可替换的管线环节（本篇的变体生成器即为此留的口子），固件修复后第一轮探针就能给出答案。清单与瓦片的目录组织也建议从一开始就按「沙箱落地」设计：loadTiledGSNode 的 uri 走 file:// 沙箱路径（官方示例即此形态），rawfile 只作货仓不作运行期路径，避免包体路径与沙箱路径两套口径在供给状态机里打架。

4、逻辑流梳理

官方设计的供给闭环（本篇实现完整覆盖应用侧每一跳）：
渲染器(瓦片选择器) GSPlugin 轻带看·带看页渲染器(瓦片选择器) GSPlugin 轻带看·带看页 #mermaid-svg-Tu6j84hAGrgLVKaE{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Tu6j84hAGrgLVKaE .error-icon{fill:#552222;}#mermaid-svg-Tu6j84hAGrgLVKaE .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Tu6j84hAGrgLVKaE .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Tu6j84hAGrgLVKaE .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Tu6j84hAGrgLVKaE .marker.cross{stroke:#333333;}#mermaid-svg-Tu6j84hAGrgLVKaE svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Tu6j84hAGrgLVKaE p{margin:0;}#mermaid-svg-Tu6j84hAGrgLVKaE .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-Tu6j84hAGrgLVKaE text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-Tu6j84hAGrgLVKaE .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-Tu6j84hAGrgLVKaE .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-Tu6j84hAGrgLVKaE #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-Tu6j84hAGrgLVKaE .sequenceNumber{fill:white;}#mermaid-svg-Tu6j84hAGrgLVKaE #sequencenumber{fill:#333;}#mermaid-svg-Tu6j84hAGrgLVKaE #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-Tu6j84hAGrgLVKaE .messageText{fill:#333;stroke:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-Tu6j84hAGrgLVKaE .labelText,#mermaid-svg-Tu6j84hAGrgLVKaE .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .loopText,#mermaid-svg-Tu6j84hAGrgLVKaE .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-Tu6j84hAGrgLVKaE .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-Tu6j84hAGrgLVKaE .noteText,#mermaid-svg-Tu6j84hAGrgLVKaE .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-Tu6j84hAGrgLVKaE .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-Tu6j84hAGrgLVKaE .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-Tu6j84hAGrgLVKaE .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-Tu6j84hAGrgLVKaE .actorPopupMenu{position:absolute;}#mermaid-svg-Tu6j84hAGrgLVKaE .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-Tu6j84hAGrgLVKaE .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-Tu6j84hAGrgLVKaE .actor-man circle,#mermaid-svg-Tu6j84hAGrgLVKaE line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-Tu6j84hAGrgLVKaE :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 起 4s 供给探测窗口窗口内 requested==0 loadTiledGSNode(沙箱清单) RESOLVE TiledGSNode (实测 44-63ms) setCamera(轨道相机) setTileRequestCallback(cb) 当前固件：零瓦片请求(跨双设备复现) 声明降级原因 → 切整卡 loadGSNode 整卡 RESOLVE (实测 10-80ms) → 出画

探测降级的状态机（含世代令牌防迟到判定）：
#mermaid-svg-GJ6v6U9wWVX7oyjs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-GJ6v6U9wWVX7oyjs .error-icon{fill:#552222;}#mermaid-svg-GJ6v6U9wWVX7oyjs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-GJ6v6U9wWVX7oyjs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .marker.cross{stroke:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-GJ6v6U9wWVX7oyjs p{margin:0;}#mermaid-svg-GJ6v6U9wWVX7oyjs defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-GJ6v6U9wWVX7oyjs g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-GJ6v6U9wWVX7oyjs g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-GJ6v6U9wWVX7oyjs g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-GJ6v6U9wWVX7oyjs g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-GJ6v6U9wWVX7oyjs .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-GJ6v6U9wWVX7oyjs .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-GJ6v6U9wWVX7oyjs .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GJ6v6U9wWVX7oyjs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-GJ6v6U9wWVX7oyjs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GJ6v6U9wWVX7oyjs .edgeLabel .label text{fill:#333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .label div .edgeLabel{color:#333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-GJ6v6U9wWVX7oyjs .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-GJ6v6U9wWVX7oyjs .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-GJ6v6U9wWVX7oyjs .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs #statediagram-barbEnd{fill:#333333;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .cluster-label,#mermaid-svg-GJ6v6U9wWVX7oyjs .nodeLabel{color:#131300;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .note-edge{stroke-dasharray:5;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-note text{fill:black;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram-note .nodeLabel{color:black;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagram .edgeLabel{color:red;}#mermaid-svg-GJ6v6U9wWVX7oyjs #dependencyStart,#mermaid-svg-GJ6v6U9wWVX7oyjs #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-GJ6v6U9wWVX7oyjs .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-GJ6v6U9wWVX7oyjs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 选空间/点分块带看
RESOLVE + 回调注册
REJECT 且无整卡资产
REJECT 且有整卡资产
窗口内 requested>0
4s 零请求(声明原因)
世代失效(切模式/销毁)
整卡 RESOLVE 出画
离开视口(记账闭环)
离开视口(记账闭环)
分块加载
探测窗口
失败态
整卡降级
分块带看中
整卡带看中

两张图里各有一处工程细节值得展开：序列图里「世代失效」对应统一加载世代令牌 loadGen------页面销毁或模式切换即自增，所有异步续体、瓦片回调、探测定时器回来时先对世代，对不上就丢弃结果并销毁其携带的场景，迟到任务不再写状态、不再注册回调；状态图里「离开视口记账闭环」对应 Tab 切换不销毁组件的现实------ArkUI 的 Tabs 切走只隐藏不卸载，aboutToDisappear 不触发，会话记账必须靠激活态 @Prop @Watch 显式关闭。状态图还有一处刻意保留的简化要声明：探测窗口 --> 分块带看中 的判据目前只有 requested>0------请求到达只等于「链路激活」，不等于瓦片供给成功、更不等于出画；完整的四态判定（未观察到请求 / 已收到请求 / 供给成功 / 确认出画）留待回调真被触发的固件上实现，理由同 3.4：冷路径改造无法真机验证，与其写一套没跑过的状态机，不如把边界如实标出来。

会话记账的跨组件时序（6.3 竞态的结构化表达）：
SessionStats 单例数据页 Tabs 外壳带看页 SessionStats 单例数据页 Tabs 外壳带看页 #mermaid-svg-bs3aiYYfM56m7OqE{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bs3aiYYfM56m7OqE .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bs3aiYYfM56m7OqE .error-icon{fill:#552222;}#mermaid-svg-bs3aiYYfM56m7OqE .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bs3aiYYfM56m7OqE .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bs3aiYYfM56m7OqE .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bs3aiYYfM56m7OqE .marker.cross{stroke:#333333;}#mermaid-svg-bs3aiYYfM56m7OqE svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bs3aiYYfM56m7OqE p{margin:0;}#mermaid-svg-bs3aiYYfM56m7OqE .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-bs3aiYYfM56m7OqE text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-bs3aiYYfM56m7OqE .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-bs3aiYYfM56m7OqE .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-bs3aiYYfM56m7OqE .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-bs3aiYYfM56m7OqE .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-bs3aiYYfM56m7OqE #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-bs3aiYYfM56m7OqE .sequenceNumber{fill:white;}#mermaid-svg-bs3aiYYfM56m7OqE #sequencenumber{fill:#333;}#mermaid-svg-bs3aiYYfM56m7OqE #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-bs3aiYYfM56m7OqE .messageText{fill:#333;stroke:none;}#mermaid-svg-bs3aiYYfM56m7OqE .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-bs3aiYYfM56m7OqE .labelText,#mermaid-svg-bs3aiYYfM56m7OqE .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-bs3aiYYfM56m7OqE .loopText,#mermaid-svg-bs3aiYYfM56m7OqE .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-bs3aiYYfM56m7OqE .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-bs3aiYYfM56m7OqE .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-bs3aiYYfM56m7OqE .noteText,#mermaid-svg-bs3aiYYfM56m7OqE .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-bs3aiYYfM56m7OqE .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-bs3aiYYfM56m7OqE .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-bs3aiYYfM56m7OqE .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-bs3aiYYfM56m7OqE .actorPopupMenu{position:absolute;}#mermaid-svg-bs3aiYYfM56m7OqE .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-bs3aiYYfM56m7OqE .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-bs3aiYYfM56m7OqE .actor-man circle,#mermaid-svg-bs3aiYYfM56m7OqE line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-bs3aiYYfM56m7OqE :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} @StorageProp @Watch 与可见性刷新双通道, 任一记账事件必达, 时序无关会话开始(startTour/startWhole 记账起点) active=false(@Watch 触发) closeSession(写记录+version++) AppStorage 事件(ltStatsVersion) refresh(拉快照: records.slice+汇总值) 页面可见(onVisibleAreaChange) refresh(兜底再拉一次)

这张图是修复后的形态。修复前数据页只有一条「页面可见时拉快照」的通道，而关账发生在带看页失活的 @Watch 里，两者谁先谁后取决于框架当帧的调度顺序------首屏漏会话就是这么来的。把记账事件升级为广播后，顺序不再重要：迟到的关账也会把已挂载的数据页推一次刷新。

5、项目实战

环境声明：HarmonyOS 7.0.0.107（手机 ALN-AL80 为 SP8C00E105R4P3、MatePad Edge QXS-W00 为 SP8C00E105R6P5，均 API 26 Release 正式版），DevEco Studio 26.0.0（build DS-261.23567.138.36.2600821）、SDK 26.0.0；芯片平台麒麟 9000S（手机）与 2in1/PC 形态（MatePad Edge）。渲染侧无芯片门槛（GSPlugin 底座 6.0.1/API 21 起覆盖 Phone/PC/Tablet/TV）。

素材管线单独交代，因为本篇全部数据可复现的前提在这里：garden 庭院扫描全量 173MB PLY，先裁剪到 30 万高斯（71.2MB），再用 PlayCanvas splat-transform 生成 Streamed SOG 分块资产（22 瓦片 + 清单 JSON）与整卡对照档（LOD3 PLY，17MB、73,085 高斯）。分块与整卡来自同一份扫描、同一次重建，性能对照才同口径；裁剪比例与 LOD 档位都记在素材脚本里，换一台设备重跑能得到同一组量级的数据。坐标系统一为 Y-up（扫描产出经翻转脚本处理），包围盒中心与对角线由全量点云实测导出，写进空间描述符供相机推导使用------视锥参数不写死常量，是篇 1 就立下的纪律，本篇沿用。

5.1 分块 bootstrap：清单落沙箱 + 相机按包围盒推导

typescript 复制代码

// TiledGSLoader.bootstrap：分块链路四段各自 try，每步失败段位可辨、已建资源就地清理
static async bootstrap(manifestPath: string, cameraName: string,
    cameraPath: string): Promise<TiledLoadResult> {
  const t0: number = Date.now();
  // 段① 插件：与整卡链路共用进程级状态，走幂等入口；不可用直接返回统一结果
  if (!GSSceneLoader.ensurePlugin()) {
    return { ok: false, scene: null, tiledNode: null, camera: null,
             message: '当前设备未提供可用的 3D 渲染上下文，分块 3DGS 不可用',
             errorCode: 0, elapsedMs: Date.now() - t0 };
  }
  // 段② 场景：失败时尚无原生资源可清理，返回统一结果
  let scene: Scene;
  try {
    scene = await GSSceneLoader.loadScene();
  } catch (err) {
    const e = err as BusinessError;
    return { ok: false, scene: null, tiledNode: null, camera: null,
             message: `场景创建失败：${e.message}`, errorCode: e.code, elapsedMs: Date.now() - t0 };
  }
  // 段③ 相机：场景已建成，相机失败必须就地销毁场景防 GPU 泄漏（审查簇 H）
  let camera: Camera;
  try {
    camera = await GSSceneLoader.createCamera(scene, cameraName, cameraPath);
  } catch (err) {
    const e = err as BusinessError;
    GSSceneLoader.destroySceneQuietly(scene, 'tiled-bootstrap-camera-fail');
    return { ok: false, scene: null, tiledNode: null, camera: null,
             message: `相机创建失败：${e.message}`, errorCode: e.code, elapsedMs: Date.now() - t0 };
  }
  // 段④ 清单加载：相机视锥不写死常量，由空间包围盒对角线推导（篇 1 沿用的纪律，
  // 在调用方 configureCameraForBounds 里完成）；失败同样就地销毁场景
  try {
    const root = scene.root;
    if (root === null || root === undefined) { throw new Error('scene root is missing'); }
    const settings: spatialRender.TiledGSImportSettings = { uri: `file://${manifestPath}` };
    const node: spatialRender.TiledGSNode =
      await spatialRender.GSPlugin.loadTiledGSNode(scene, settings, root);
    node.visible = true;
    node.setCamera(camera);                                   // 驱动分块选择的相机
    return { ok: true, scene, tiledNode: node, camera, elapsedMs: Date.now() - t0,
             message: '', errorCode: 0 };
  } catch (err) {
    const e = err as BusinessError;
    GSSceneLoader.destroySceneQuietly(scene, 'tiled-bootstrap-load-fail');
    // Promise reject 的错误码与消息原文一字不改带出去（P3 观测点①）
    return { ok: false, scene: null, tiledNode: null, camera: null,
             message: `分块清单加载失败：${e.message}`, errorCode: e.code, elapsedMs: Date.now() - t0 };
  }
}

四段里最容易写错的是段③④的资源归属：场景一旦建成就持有原生资源，此后任何一段失败都必须就地销毁，否则就是 GPU 泄漏（审查簇 H 的落点，Scene.destroy(): void 已在本地 SDK 的 Scene.d.ts 核证存在）。段①②失败时尚无场景可清理，返回统一结果即可。四段返回同一个 TiledLoadResult 类型，调用方不需要区分「哪一步炸的」也能拿到 errorCode 与 message------失败段位可辨靠的是 message 前缀与日志 tag，不是不同的返回类型。

5.2 瓦片供给状态机：回调入口去重、并发与黑名单

typescript 复制代码

// TileSupply.handleRequest：渲染器回调入口（当前固件不触发，固件修复后即生效）
handleRequest(tiles: spatialRender.GSTile[], node: spatialRender.TiledGSNode): void {
  if (this.disposed) { return; }
  for (const tile of tiles) {
    this.stats.requested++;
    const uri: string = tile.uri;
    // 去重 + 在途合并：渲染器拖拽时会对同一瓦片重复发请求，
    // 不去重就会同一文件并发拷贝多次（内存与 IO 双浪费）
    if (this.supplied.has(uri) || this.inflight.has(uri) || this.blacklisted.has(uri)) {
      continue;
    }
    this.inflight.add(uri);
    this.supplyOne(tile, node, uri);   // 异步：取字节→落盘→notify；uri 显式传参
  }
  this.emitStats();
}

// 单个瓦片的供给：货仓定位 → 沙箱落盘 → notifyTileReady。
// inflight 生命周期纪律：本函数的每一条出口（成功/失败/dispose）都必须把 uri
// 移出 inflight，否则该瓦片被永久当作「在途」，后续合法请求全被去重逻辑吞掉
private async supplyOne(tile: spatialRender.GSTile,
    node: spatialRender.TiledGSNode, uri: string): Promise<void> {
  try {
    // 与工程一致，此处省略：uri 形态三分支解析（file:// 绝对路径 / '/' 开头 /
    // 裸相对路径按清单目录解析）与目标目录的递归创建，见 5.2 末预热段的同款处理
    const fileName: string = TileSupply.basename(uri);
    const dst: string = /* 三分支解析结果 */ `${this.resolveDir}/${fileName}`;
    // 演示形态声明：货仓是 rawfile 预置的「模拟远端」，真实产品把这一段换成
    // CDN/对象存储下载；状态机结构不变，只换字节来源
    const data: Uint8Array =
      await this.ctx.resourceManager.getRawFileContent(`${this.warehouseDir}/${fileName}`);
    if (this.disposed) { this.inflight.delete(uri); return; }  // dispose 出口①：丢弃回传
    // 与工程一致，此处省略：openSync/writeSync 落盘段------写失败 unlinkSync 清半截
    // 文件后 throw 进 catch（防毒化缓存），成功 closeSync
    node.notifyTileReady(tile);          // 拷贝完成才通知，顺序不能反
    this.inflight.delete(uri);           // 成功出口：移出在途
    this.supplied.add(uri);              // 记入已供给，后续重复请求直接去重
    this.stats.ready++;
    this.stats.distinct = this.supplied.size;
    this.emitStats();
  } catch (err) {
    const e = err as BusinessError;
    this.inflight.delete(uri);           // 失败出口：同样必须移出在途，允许后续重试
    this.stats.failed++;
    // 失败计数（审查簇 K）：同一 uri 失败 ≥3 次进黑名单，不再重试、不再刷屏
    const count: number = (this.failCounts.get(uri) ?? 0) + 1;
    this.failCounts.set(uri, count);
    if (count >= TileSupply.MAX_TILE_FAILURES) {
      this.blacklisted.add(uri);
    }
    this.emitStats();
  }
}

这段代码值得多说一句的原因：它是全篇唯一一段从未被真机执行过的代码 ------回调不触发，状态机就跑不起来。所以它的正确性只能靠两样东西保证：与工程内真实实现逐行一致（工程版已通过编译与源码审查 17 簇修订），以及把每条出口的生命周期义务写进注释。inflight 的三个出口（成功、失败、dispose）各有一句 delete，缺任何一句，这个瓦片就永久卡死在「在途」态------冷路径上这种 bug 不会在演示期暴露，只会在固件修复后的第一次真实供给里咬人。

与供给状态机配套的还有缓存预热：加载前把清单 filenames 声明的全部瓦片从 rawfile 货仓拷进沙箱清单同目录。产品语义是「把远端货仓提前落到本地，渲染器一旦发请求即零网络命中」；在排查期它同时是一组判别实验------预置 22/22 后仍零请求，直接排除「供给时序/文件缺失」假设。这段代码里有两个审查修订落点：

typescript 复制代码

// 预热主循环（节选）：fd 保护与 TOCTOU 容错
const file = fs.openSync(manifestPath, fs.OpenMode.READ_ONLY);
let buf: ArrayBuffer;
try {
  buf = new ArrayBuffer(fs.statSync(manifestPath).size);
  fs.readSync(file.fd, buf);                                  // 同步读段整体 try/finally 护住
} finally {
  fs.closeSync(file);                                         // readSync 抛错也不漏 fd
}
// ...
// accessSync→mkdirSync 之间存在 TOCTOU：并发 supplyOne 可能抢先建目录，
// 故 mkdirSync 用递归参数并自带 try/catch 容忍「已存在」，不把它当失败
try { fs.mkdirSync(dir, true); } catch (e) { /* 已存在即达标 */ }

清单只有数 KB（22 瓦片），同步读是刻意选择：微秒级开销换取链路段位清晰，异步化收益不抵复杂度；但这个选择只在清单体量可控时成立，代码注释里写明了边界。

5.3 探测降级：4 秒窗口 + 世代校验

typescript 复制代码

// 分块 resolve 后挂探测；gen 对不上说明期间切了模式或销毁了页面，判定作废
private armSupplyProbe(gen: number): void {
  setTimeout(() => {
    if (gen !== this.loadGen || this.degraded) { return; }    // 迟到判定直接丢弃
    const requested = this.lastStats !== null ? this.lastStats.requested : 0;
    if (requested === 0) {
      // 文案纪律：只声明「窗口内未观察到」，不声明「渲染器永远不会请求」------
      // 4s 阈值是当前固件恒零请求下的实测设定，固件修复后需重新校准（见 3.4）
      this.pushLog(`探测：resolve 后 ${SUPPLY_PROBE_MS}ms 窗口内未观察到瓦片请求，判链路不可用`);
      this.degrade(`探测：分块链路已通但 ${SUPPLY_PROBE_MS}ms 窗口内未观察到渲染器瓦片请求（当前固件现象）`, true);
    } else {
      this.pushLog(`探测通过：窗口内收到 ${requested} 个瓦片请求，分块链路工作正常`);
    }
  }, SUPPLY_PROBE_MS);
}

private degrade(reason: string, recordDegraded: boolean): void {
  if (this.space.wholeAsset.length === 0) {                   // 无兜底不发空横幅，走显式失败态
    this.statusText = `分块链路不可用且该空间无整卡资产可降级：${reason}`;
    return;
  }
  this.degraded = true;
  this.degradeBanner = `已降级整卡对照：${reason}`;
  this.closeSession();                                        // 分块会话先记账闭环（mode='tiled'）
  this.startWhole(recordDegraded);                            // 整卡接管记 'degraded'，世代自增
}

探测降级这条链路在真机上的完整一轮长什么样，直接贴复验轮的 hilog 原文（脱敏仅截短行宽，时间戳与内容一字未动，完整归档在工程 docs/evidence/af-hilog-auditfix.txt）：

text 复制代码

09-21 12:21:41.843 I JSAPP: [LightTour] 缓存预热 22/22 个瓦片到沙箱
09-21 12:21:41.885 I JSAPP: [LightTour] loadTiledGSNode RESOLVE 耗时=42ms
09-21 12:21:45.888 I JSAPP: [LightTour] 探测：resolve 后 4000ms 瓦片请求仍为 0，判瓦片供给链路在当前固件不可用
09-21 12:21:45.890 I JSAPP: [LightTour] 降级声明：探测：分块链路已通但渲染器零瓦片请求（当前固件现象）
09-21 12:21:45.950 I JSAPP: [LightTour] 整卡 RESOLVE 耗时=56ms，画面应可见
09-21 12:21:46.264 I JSAPP: [LightTour] scene destroyed (switch-to-whole)

六行日志把 3.4 的全部主张各钉了一枚钉子：预热 22/22（供给准备就绪）、RESOLVE 42ms（接口链路通）、4000ms 整（探测窗口足秒）、降级声明与整卡 RESOLVE 相隔 60ms（降级路径的开销就是一次整卡加载）、300ms 后准时销毁旧场景（簇 H 的延迟销毁时序）。注意这份归档里的探测文案还是修改前的「瓦片请求仍为 0」------横幅与日志文案的「窗口内」限定是本轮成稿审查后改的，改动只涉及措辞不涉及判定逻辑，下轮构建带上。

5.4 Component3D 场景重绑：ForEach 键强制重建

typescript 复制代码

// 实测结论：Component3D 只在首次实例化绑定 sceneOptions 里的 Scene，
// 之后替换 Scene 对象、改 .id() 都不重绑------整卡/分块互切会停在旧场景画面。
// 解法：ForEach 键 = 场景世代，换键即销毁重建组件，渲染器重绑新 Scene
ForEach([this.sceneGen], (gen: number) => {
  Component3D(this.sceneOptions as SceneOptions)
    .width('100%').height('100%')
}, (gen: number) => `gs_${gen}`)

旧场景的销毁时机也有讲究：先自增世代触发重建、再延迟 300ms 销毁旧 Scene，避开与 Component3D 卸载的同帧竞态；真机日志里每次切换后准时出现 scene destroyed (switch-to-whole/switch-to-tiled)。

5.5 世代令牌与统一清理：异步链路的所有权纪律

分块链路从点击到出画要经过清单落盘、瓦片预热、bootstrap、回调注册、探测窗口五段异步，任何一段回来时页面可能已经切了模式或销毁了。旧实现用 probeToken 只管探测一段，审查时被发现其余续体全裸奔：迟到的 bootstrap 结果会把旧场景写进 this.scene、把旧回调注册到新节点上。修订后统一为一个加载世代令牌：

typescript 复制代码

// 入口自增：aboutToDisappear / startTour / startWhole 三处
const gen: number = ++this.loadGen;
// 每个 await 之后、回调入口、探测定时器内先对世代
if (gen !== this.loadGen) {
  // 迟到结果整包丢弃；其携带的场景就地销毁（从未绑定视图，可立即销毁）
  GSSceneLoader.destroySceneQuietly(result.scene, 'stale-tiled-bootstrap');
  return;
}

与世代配套的是统一清理入口 clearTiledNode(tag)：置空 tiledNode 之前必先注销其瓦片回调并 dispose 供给状态机。旧实现的教训很具体------直接 this.tiledNode = null 会让销毁路径上的非空守卫落空，旧节点的回调变成永远清不掉的孤儿引用，重启分块后旧回调还会读到新 supply、新节点，跨世代错配。回调闭包捕获签发时的 gen/node/supply 三件套，陈旧世代的请求在入口直接 return，旧节点不可能再喂到新状态上。

这套纪律的成本是每个异步续体多两行校验，收益是「页面销毁后不再有任务写状态、注册回调、起会话」可以用日志证明：复验轮里切空间触发硬重建，旧组件准时打出 scene destroyed (page-disappear)，新组件独立走完加载链路，两条世代互不串线。

5.6 会话记账与数据页订阅：跨组件的事件总线

typescript 复制代码

// SessionStats.add：记账同时广播事件------数据页可能已挂载但快照过期
add(rec: SessionRecord): void {
  this.records.push(rec);
  this.version++;
  AppStorage.setOrCreate<number>('ltStatsVersion', this.version);
}

// DataPage：@StorageProp 订阅记账事件，任何一笔（含 Tab 切换途中迟到的
// closeSession）都驱动重拉快照；渲染树只读快照字段，状态变更必然重渲染
@StorageProp('ltStatsVersion') @Watch('onStatsVersionChanged') ltStatsVersion: number = 0;
onStatsVersionChanged(): void { this.refresh(); }

5.7 双设备实测数据

零瓦片请求现象在两台设备、两个固件 build、两个代码轮次上均复现：

指标	Mate 60 Pro（R4P3，审查修复轮）	MatePad Edge（R6P5，PC 形态，框架轮）
分块 `loadTiledGSNode` RESOLVE	首载 44--63ms，变体 10--15ms；修复轮 13--122ms	7--41ms
瓦片请求（回调触发次数）	恒 0（五变体 + 预置 + 拖视角）	恒 0（五变体探针矩阵同现象复现）
整卡 `loadGSNode` RESOLVE	10--80ms（lod3.ply，LOD3 档）	14--63ms
探测降级全程（分块 resolve → 整卡出画）	4s 窗口 + 75ms	4s 窗口 + 63ms
缓存预热	22/22 瓦片落沙箱	22/22
会话记账核对	5 会话 2/3，平均 57ms = (42+56+56+51+80)/5（tiled 口径见 3.4：RESOLVE 成功即记账，不代表分块出画）	3 会话 2/1，平均 42ms = (32+63+31)/3

素材口径：garden 庭院扫描全量 173MB PLY，裁剪 30 万高斯 71.2MB；分块管线用 PlayCanvas splat-transform 生成 Streamed SOG（22 瓦片 + 清单），整卡对照取 LOD3 档（17MB、73,085 高斯）。证据归档：截图 20 余张与 hilog 全量（含 D 级日志轮）在工程 docs/evidence/，复验矩阵与设备事故记录在 docs/p3-smoke-report.md。

6、避坑指南

本节的五个坑全部按「现象 → 根因 → 方案对比 → 最佳实践 → 验证」闭环写，证据来源只有两类：真机截图与 hilog 原文。前四个是 ArkUI 状态层的坑，第五个是取证工具链的坑------把它写进来是因为它真实地吃掉了我一个上午：设备服务栈挂死后所有命令失效，一度怀疑是新代码触发了图形栈异常，重启后逐条对时间线才把故障点定位到一条 dump 命令上。归因与观察分记：可重复的实测现象按事实写，推断单独标注。

6.1 Component3D 只在首次实例化绑定 Scene

现象：整卡出画后点「分块带看」，分块链路 RESOLVE 成功、日志全绿，画面仍是整卡场景；反过来降级后画面空白。

根因：Component3D 只在首次实例化时读取 sceneOptions 绑定 Scene，替换对象或改 .id() 均不重绑（.id() 只是测试标识，不触发卸载重建）。

方案对比 ：① 每次切换销毁整个视口容器------牵连手势与浮层状态，代价大；② 双 Component3D 叠放按模式显隐------原生资源双份，内存翻倍；③ ForEach 键 = 场景世代强制重建------只重建 3D 组件本身。

最佳实践 ：方案③，键用单调自增的 sceneGen。

验证：真机互切三轮 RESOLVE 38/10/13ms，每次切换后 300ms 出现 scene destroyed 日志，画面无残影。

6.2 @State 字段同名重复声明冻结按钮

现象：降级完成后顶栏按钮冻在「加载中...」，点击无日志。

根因：改状态时遗留了一个同名 private degraded 声明，与 @State degraded 并存，状态包装受扰，loading 复位 false 后顶栏不重渲染。

方案对比 ：无选型空间，属必须消除的声明错误；可复用的经验是补三处诊断日志（点击入链/loading 复位/guard 命中），hilog 一眼定位「点了没反应」是 guard 拦截还是渲染没刷新。

最佳实践 ：@State 字段全组件唯一声明；按钮 enabled 与文案引用的字段必须是 @State（私有字段不触发重渲染，篇 2 同款教训）。

验证：删除重复声明后 V1--V4 矩阵全过。

6.3 Tab 切换记账竞态：数据页首屏漏掉刚关账的会话

现象：带看中切到数据 Tab，首屏快照少一条会话，点「刷新」才齐全。

根因：Tabs 切走不销毁组件，带看页靠 @Prop @Watch('active') 在失活时关账；而数据页的可见性刷新（onVisibleAreaChange）与 Tabs.onChange 的执行顺序都早于或晚于关账的毫秒窗口，首屏快照读到的是关账前的记账数组。

方案对比 ：① Tabs.onChange 里同步 flush 待关账钩子------实测 onChange 触发晚于数据页可见性刷新，仍漏；② 数据页定时轮询------浪费且仍有窗口；③ 记账事件写 AppStorage，数据页 @StorageProp @Watch 订阅 ------任何一笔记账（含迟到的 closeSession）都驱动已挂载页面重拉快照，时序无关。

最佳实践 ：方案③，钩子 flush 保留作同步快路径。

验证：修复后首屏即含全部已关账会话，汇总卡与列表逐条吻合。

6.4 @Builder 按值传参不建立响应式依赖

现象：竞态修复后列表刷新正常，但三张汇总卡文案冻结在挂载当帧。

根因：summaryCard('本次会话', ${this.sumTotal}) 这类按值传参的 @Builder，参数在调用处求值一次，卡片体内不持有对 this.sumTotal 的依赖追踪，后续 @State 变化不重渲染卡片（列表 ForEach 体内直读 this.records 故正常）。

方案对比 ：① 把值拼进组件 key 强制重建------粗暴且丢动画状态；② 改 @Component 子组件 + @Prop------结构变重；③ 无参 @Builder 体内直读 @State ------依赖追踪建立在组件自身状态上，零额外结构。

最佳实践 ：方案③；需要复用的展示片段若依赖状态，一律体内直读而非参数传入。

验证：改后首屏 2 会话/1/1/49ms = (42+56)/2，卡与列表同步刷新。

6.5 取证工具链：前台 3D 渲染时不要跑 dumpLayout

现象：一轮复验中，应用前台正在做 Component3D 渲染时执行 uitest dumpLayout，其后所有需要系统服务 IPC 的命令（aa start、hilog、power-shell、uitest）全部挂死，纯 shell 命令正常，hdc reboot 也不生效；物理重启后一切恢复，faultlog 无崩溃记录。

根因（按证据推断，无法事后确证）：dumpLayout 需遍历窗口树并与前台应用交互取布局树，原生 3D surface 在该交互下拖垮了图形/窗口服务栈。方案对比 ：① 需要布局信息时先退后台或 force-stop 再 dump------可行但打断取证连续性；② 取证只依赖 snapshot_display 截图 + hilog 日志------截图不经过布局树 IPC，本轮全部证据即由此二者构成。

最佳实践 ：方案②为主；监控浮层与观测日志上屏的设计，本质就是让「截图即行为证据」成立，不依赖任何 dump 类命令。

验证：改纪律后连续六轮复验零故障。

7、总结

先把这篇最硬的一条边界放在总结第一句：在当前两台设备、两个固件 build 上，TiledGSNode 的瓦片请求恒为 0，按视口加载没有真正跑起来，用户看到的画面由整卡兜底承担。这不是实现的失败，是实测的结论------本篇交付的是「接口逐跳实证 + 零请求现象的完整证据链 + 一条显式设计的降级路径」，而不是一套已经生效的按视口加载体验。

在这个边界之内，TiledGSNode 的设计价值依然成立：它把 3DGS 大资产的加载模型从「推」改成「拉」------清单描述全量层级，渲染器按驱动相机拉瓦片，应用负责供给字节。这个模型决定了内存占用由视口而非场景总量决定（设计语义，待固件激活后实测），是大空间上手机的官方路径。本篇把应用侧闭环实现完整：清单落沙箱、回调注册两跳真机实证，供给状态机与 notifyTileReady 一跳完整实现待触发；接口可用性与链路可用性是两件事，探测降级就是把这两件事的差距变成一条被声明的产品路径。

回看这篇文里最花时间的部分，不是 TiledGSNode 本身，而是四个 ArkUI 状态层的坑：Component3D 的首次绑定、@State 的同名重复声明、Tab 切换的记账竞态、@Builder 的值传参不响应。它们有一个共同形状------渲染树只重渲染「依赖追踪命中」的部分，任何绕过追踪的写法都会在某一天以「数据对了但画面不对」的形式回来。监控浮层、观测日志上屏、会话记账对账这三件事，看起来是产品功能，实际是我给状态层装的仪表：没有它们，这四个坑每一个都要靠猜。

对准备接入 TiledGSNode 的同行，三条建议：清单 schema 以真机实测为准，官方未公开前不要假设兼容任何第三方格式；供给状态机从第一天就带去重、在途合并、失败黑名单与 dispose，渲染器一旦激活，回调频率会远超演示期直觉；把「链路不可用」当产品状态设计而不是异常处理，探测窗口、降级声明、分口径记账三件套的成本远低于一次客户面前的空白视口。