本地完整参考包:D:/unityproject/Documentation/Reference/AllinXR-XR-Runtime-Reference。包含复盘、实际源代码、验证代码、依赖和校验清单;完整源代码在本地受控工程中维护。
下方 Markdown 说明可独立阅读,文中的 Source 链接须在完整本地参考文件夹内使用。当前包和真机验收边界以正文最新交付节为准。
# AllinXR 三平台启动、离线与图像定位故障复盘
> **随文附有实际代码**:完整文件夹为 `AllinXR-XR-Runtime-Reference`。先看 [源码索引](SOURCE-INDEX.md)、[依赖说明](DEPENDENCIES.md);第 19–25 节说明跨项目迁移、调用链、姿态契约、离线事务和验收规则。复制整个文件夹即可保留本文与代码之间的相对链接。
>
> 本次是资料整理,源代码快照保持原样。当前交付:PICO 1.0.27(25)、Meta 1.0.21(22)、Vision 1.2.10(13);最新点火真机验证待完成。历史小节中的“待打包”保留当时语境,不代表当前发布状态。
更新日期:2026-11-15。适用工程:Unity 6 的 AllinXR Vision Pro、PICO Swan、Meta Quest 3。本文整理本次实际代码、留存的诊断记录和用户真机反馈,供其他项目迁移思路时参考。**不要把本文的平台坐标修正直接复制到另一套 SDK 或另一套美术坐标约定中。**
## 1. 阅读边界与证据等级
本文用三种表述区分证据:
- **已定位**:代码路径与异常/Profiler 或可执行回归用例对应,能解释该次故障。
- **已修正风险、真机改善**:存在明确代码风险且已修正,但没有故障发生时的完整原生调用栈,不能断言它解释所有同类现象。
- **未确定**:用户观察成立,缺少能归因到具体函数的证据,不将推测写成结论。
历史发布基线为 PICO 1.0.25(23)、Meta 1.0.19(20)、Vision Pro 1.2.8(11)。PICO 联网与断网启动、双眼、圆环和重复定位已由用户验收;Vision Pro 随后确认测试正常。用户进一步确认**三个平台的 Dev 完整流程都已跑通**。这不等于所有平台的 Pro、所有路线和离线后台指令都经过验收。
2026-11-15 开始 Pro 测试时,PICO 暴露新的“切换环境后保存登录失败”问题,见第 13 节。其修复、安装和复测状态由同日 `AllinXR-ProLoginFix-20261115.json` 记录,不能用旧包验收结果替代新修复验收。
工程根目录:
| 平台 | 当前源工程 | 平台边界 |
| --- | --- | --- |
| Vision Pro | `D:/unityproject/shan2` | visionOS 原生图像 Provider;Mac 上编译和发布 |
| PICO Swan | `D:/unityproject/Shan2PICOSwan` | PICO 图像识别、平面与空间锚适配 |
| Meta Quest 3 | `D:/unityproject/shan2Meta` | Meta 相机/OpenCV/PnP 位姿适配 |
| 后端 | `D:/unityproject/NewProject/WebAdmin` | 当前香港海外后端;客户端安装包与内容快照分开管理 |
文中源文件相对路径从对应工程根目录开始计算。通用文件在三工程均维护;文件同名不代表整份实现完全相同。账号、店铺 Key、Token 和含凭据日志不放入本文。
## 2. 问题总表
| 现象 | 本次确认的原因/边界 | 主要修复入口 |
| --- | --- | --- |
| AB 已下载,随后提示还原失败 | Art 导入无法引用前一批已提交 Locate 根节点 | `ALS_ImportExportManager`、`ALabGameObjectUtils` |
| 图片阶段总耗时 7~9 秒 | 大图校验/解码、缩图及原生入库工作集中,存在重复工作;早期证据未定位每个耗时函数 | `ALS_ResourceImportSupport`、`ALS_DynamicImageManager`、`ALT_TrackImageManager` |
| 图片开始时约 1.39 秒长帧 | 调试预览在同一帧创建 10 张 Tight Sprite,轮廓追踪约 1.26 秒 | `ALT_TrackImageLandmark_Debug`、`ALS_DebugCenterUI` |
| Vision 下载到约 95% 闪退 | 未取到原生崩溃日志;修正峰值内存和异步纹理生命周期风险后用户确认不再闪退 | 图片访问/入库、Addressables 资源句柄 |
| Vision 提示看图但没有圆环 | 更新图像库时原生图像 Session 未真正重建,仍保留旧指针/回调状态 | 嵌入的 visionOS Provider 补丁 |
| Vision 校准后反向 180° | 图像外法线被直接当作场景美术定义的前向,二者相反 | `ALT_LandmarkRearm`、`ALT_TrackImageLandmark` |
| 同一张起点图只能校准一次 | 完成标志未重新开放;离开视野不一定触发 SDK removed 事件 | `ALT_LandmarkRearm`、定位对象状态机 |
| 诊断包圆环卡住 | MonoBehaviour 字段初始化阶段创建原生 `MaterialPropertyBlock`,加载线程异常 | `ALT_TrackImageLandmarkLoadingRing` |
| 有 AB 和图片仍无法离线启动 | 缺少完整、按账号/环境/版本隔离的启动快照及本地目录引导;缓存未 ready 被误判为缺失 | `ALS_OfflineStartup`、`ALT_AddressableOfflineCache` |
| 离线场景和语音正常,加载 UI 不消失 | 登录子进度停在 0.5,成功分支未完成该任务 | `ALS_FlowActions` |
| 每次启动都有图片下载进度 | 把校验、解码、注册与真实下载混用同一提示;不一定发生 HTTP 请求 | `ALS_LoadingUI`、图片准备阶段日志 |
| PICO 左眼花屏,退出应用恢复 | 修正跨异步等待泄漏 RenderTexture/sRGB 状态的明确风险;缺少原始合成器证据,不能包办所有花屏原因 | `ALT_RenderTargetScope`、PICO 缩图/回读 |
| 诊断包两个方形模型紫色 | 精确 Shader 原因未确定;同 AB 的正式包复测消失 | 保留故障边界,不能宣称 PSO 或 AB 损坏已证实 |
| 切到 Pro 后资料空白,新资料保存失败 | 环境独立缓存本来可能为空;新候选账号被误当成已保存账号校验 | `ALT_LoginManager`、`ALS_OfflineStartup` |
## 3. AB 下载成功为什么还会“还原失败”
### 3.1 原因
资源下载和场景对象引用恢复是不同阶段。本次 Art JSON 内有 `Mask/A8黑墙` 等引用,对象由前一批 Locate 导入创建。原事务的引用查找范围只有本次新建 Art 根节点,找不到已经正确提交的 Locate 对象,导致还原失败。文件已经下载完整并不能修复这个引用范围问题。
### 3.2 修改位置与做法
- `Assets/ALabSpace/Sources/ProjectConfig/ImportExport/Manager/ALS_ImportExportManager.cs`:`ImportDocumentsSafelyAsync`,维护 `committedImportIdentity` 与 `committedImportRoots`。
- `Assets/ALabToolkit/Json/ALabGameObjectUtils.cs`:`BindImportedRoots` 提供限定范围的引用解析。
- `Assets/ALabSpace/Sources/ProjectConfig/ImportExport/Utils/ALS_ImportUtils.cs`:组件恢复/引用处理。
解析时允许引用**同一项目、同一资源配置身份**已经成功提交的根对象;组件写入仍只作用于本事务新建对象。失败时回滚新对象,保留先前提交的 Locate。不要改成全场景按名称搜索,否则旧场景、隐藏对象或同名对象会被错误引用。
### 3.3 验证与迁移经验
`ALS_SequentialImportValidation.cs` 的历史验证包括 11 类场景:隐藏已提交对象引用、重复 Art 导入保留 Locate、未提交根拒绝、缺失子节点拒绝、跨根回滚、不同项目/版本拒绝、写入范围限制、Locate 替换刷新引用范围及作用域释放等。其他项目采用分批反序列化时,应明确区分“允许读取的对象集合”和“允许本事务修改的对象集合”。
## 4. 卡顿:先分开总耗时与单帧停顿
### 4.1 第一阶段:图片准备总耗时
PICO 1.0.15 的留存记录显示图片阶段约 7.466、8.697、8.810 秒,10 张 PNG 已缓存,合计 64,030,706 字节。当时调度轨迹显示 Unity 主线程负担重、渲染线程相对轻,但没有足够函数栈把全部耗时归给某一个 API。因此,当时的重复解码、字节摘要和缩放是需要排查的路径,**不是已经证明的 PSO 编译问题**。
已落地的改动:
1. `ALS_ResourceImportSupport.VerifyServerFile` 使用流式 SHA 校验,在 `Task.Run` 中执行文件工作,避免整份 PNG 再复制成托管数组。
2. `CacheIsValidAsync` 校验资源身份、文件长度和摘要。相同内容已经完成图像语义校验后,receipt 的 `imageValidationVersion` 避免每次启动重复做同一轮语义解码;并未取消文件完整性检查。
3. `LoadTextureFileAsync` 通过本地文件 URI 的 `UnityWebRequestTexture` 走原生纹理解码路径。Unity 对象访问仍留在主线程。
4. `VisitImageFilesAsync` 每次借出一张纹理,等待消费者完成原生入库任务,再在 `finally` 释放,并让出一帧,减少同时保留十张大图及其副本。
5. `ALS_DynamicImageManager.VisitDynamicImagesAsync` 按当前启动配置的清单访问文件,不把目录残留图片全读进来。
6. 平面调试可视化仅在需要显示时更新,避免无意义的 Mesh/文字重建。
`async` 不表示所有工作自动在后台运行。已完成的 `await` 可以继续在同一帧执行后续循环;Unity 纹理和组件 API 也不能为了“不卡顿”直接搬到线程池。
### 4.2 最后一处秒级长帧:已定位到 Sprite 轮廓生成
PICO 1.0.24 诊断包的 Unity 原始性能记录:
| 指标 | 数值 |
| --- | ---: |
| 最长一帧 | 1391.253 ms |
| `SpriteMeshGenerator.TraceShape` 调用次数 | 10 |
| 上述调用累计 | 1261.290 ms |
| 同帧 `XRUpdate` | 6.089 ms |
`ALT_TrackImageLandmark_Debug` 的运行时调试预览一次性把十张定位图转成 Sprite。默认 Tight 网格需要沿图片生成精细轮廓,大图连续处理把一帧阻塞了约 1.26 秒。这是本次 1.39 秒卡顿的主要来源。**这个证据不支持把该帧归因于 ARFoundation、PSO 缓存或 AB 下载。** 其他版本和其他帧仍需单独分析。
修复:
```csharp
// ALT_TrackImageLandmark_Debug.Start:此组件只供编辑器模拟预览。
#if !UNITY_EDITOR
gameObject.SetActive(false);
return;
#endif
// 仍需要的矩形预览显式使用 FullRect。
Sprite.Create(texture, rect, pivot, 100f, 0, SpriteMeshType.FullRect);
```
修改文件:
- 三端 `Assets/ALabToolkit/SLAM/ALT_TrackImageLandmark_Debug.cs`。
- 三端 `Assets/ALabSpace/Sources/Debug/ALS_DebugCenterUI.cs`:其余预览显式 FullRect,并释放预览 Sprite/Texture。
真正的定位原图、物理宽度和原生图像库没有因禁用调试预览而删掉。Vision 之前就不走这条头显预览路径,能解释用户反馈“Vision 图片阶段不卡”。
### 4.3 Addressables 目录的伴随优化
`Assets/ALabToolkit/Addressable/ALT_AddressableManager.cs` 的 `ScanCatalogKeysAsync`、`BuildAssetInfoListAsync` 改为 Unity 主线程按约 3 ms 预算分帧扫描,并去掉重复标签查询和逐资源刷日志。
目录查询内部会更新 SDK 的共享缓存,不能简单用 `Task.Run` 与加载线程并发查询。纯文件摘要适合后台,Unity/Addressables 状态查询不一定适合。3 ms 是在可让出执行权的位置检查预算,并非能够打断一次超过 3 ms 的原生调用。
### 4.4 最终效果与限度
PICO 1.0.25 的留存轨迹中,联网最大帧间隔 143.730 ms,离线 131.317 ms;前一轮对应记录约 1253.032 ms 和 1387.446 ms。本轮未再次捕获秒级间隔,用户反馈“现在不卡了”。
这里的 Perfetto 帧间隔和诊断包的 Unity CPU 帧时长不是完全相同的指标,不能直接作为严格同条件基准。仍存在短初始化尖峰,不能写成“所有帧都达到刷新率预算”。正式包关闭诊断 Profiler,只在专用诊断构建启用。
## 5. Vision Pro 95% 附近闪退:已修复风险与未确定原因
故障包为 1.2.4(7),下载接近结束或后续资源装载时退出。头显当时未连接 Mac,**没有取得这次真机 crash/jetsam 报告**,无法确证是内存终止、原生异常还是别的系统原因。进度条 95% 也不能证明异常发生在网络下载函数里。
代码审查修正的风险包括:
- 图片顺序访问、解码后及时释放,减少峰值并存纹理;例如一张 2048×2048 RGBA32 图本体约 16 MiB,十张约 160 MiB,还未计副本和原生库,这只是容量推导,不是该设备实测峰值。
- `ALT_TrackImageManager.BuildLibraryV2` 等待原生添加图片 Job 完成后再销毁输入纹理。即使场景/请求已过期,也先收尾已经提交的原生任务。
- Addressables 模型/NavMesh 失败路径释放拥有的句柄,避免无所有权的第二次兜底加载积累资源。
- 调试预览纹理/Sprite 有明确释放路径;资源准备各阶段拆开计时。
- 缓存命中、零下载字节也完成相应进度;缺少 Key 或查询失败不能伪装成“无需下载”。
主要代码为 `ALT_TrackImageManager.cs`、`ALS_DynamicImageManager.cs`、`ALS_ResourceImportSupport.cs`、`ALT_AddressableManager.cs`、`ALT_StartupTiming.cs`。后续包用户确认不再崩溃;应写成“风险修复后真机反馈恢复”,不能倒推“OOM 已被证明”。
其他项目遇到同类现象,应保存 `.ips`/jetsam、符号与版本,比较峰值纹理/原生内存,避免只凭进度百分比判断原因。
## 6. Vision 无圆环:图像库更新与原生 Session 生命周期
### 6.1 为什么移除全局 ARSession 重建后暴露问题
当时希望避免频繁重置整个 ARSession,但只给托管层赋新图像库并不足以更新当前 SDK 的原生图像会话。
当前嵌入的 visionOS XR Plugin 2.3.1 中,原 `imageLibrary` setter 请求会话更新,却保留非零 `m_ARSession`。后续 `TryStartNativeSession` 因该指针已有值而提前返回,未装入新图像库。另有未配置 Provider 缺少图像更新处理器、Stop 只注销而未真正停止原生图像会话的问题。
因此,**取消整套 Reset 暴露了图像 Provider 自身的生命周期缺陷**;不能说删除 Reset 与无识别完全无关,也不能因此恢复每次重置所有空间跟踪。
### 6.2 修复位置
仅 Vision 工程:
- `Packages/com.unity.xr.visionos/Runtime/VisionOSImageTrackingSubsystem.cs`:`imageLibrary`、`Stop`、`TryStopNativeSession`、`TryStartNativeSession`、`ImageTrackingUpdateHandler`。
- `Packages/com.unity.xr.visionos/Runtime/VisionOSSessionSubsystem.cs`:`ForgetStoppedProvider`。
- `Packages/com.unity.xr.visionos/ALLINXR-PATCH.md`:补丁说明与升级注意事项。
流程改为:停止旧**图像 Provider** → 清理旧状态/回调映射及锚点记录 → 替换配置 → 走正常启动路径创建新的原生图像会话并注册回调。忽略停止后迟到或空的回调。头部、手部、平面与世界跟踪保留。
### 6.3 应用层入库不能假装成功
`ALT_TrackImageManager.BuildLibraryV2` 用 `SemaphoreSlim` 串行保护图库更新,逐图调用 `ScheduleAddImageWithValidationJob`,等待完成并核验状态、图像数量增量。参考图的登记物理宽度为 0.5 m。
完成赋库后等待 `nativeImageTrackingRunning`,超时约 20 秒时显示权限/会话未就绪提示。不会在原生 Provider 没启动时提前显示“可以看图了”。世界感知权限仍需由设备授予。
历史验证对实际 Provider 使用确定性的原生 API 适配器,29 项检查通过,原始实现不能通过同一用例;这属于生命周期回归测试,不能替代 TestFlight 真机识别。后续用户真机已确认本轮可用。升级 Unity/visionOS 插件时应重新对照上游实现,不能遗失补丁,也不能盲目覆盖新 SDK。
## 7. Vision 定位后旋转 180°:坐标契约与变换组合
### 7.1 它不是已经证实的“镜像识别”
SVN 对照显示 Vision 早期 r1~r52 的相关公式为:
```csharp
Quaternion.LookRotation(transform.up, transform.forward)
```
它直接使用图像坐标的上轴作为场景前向。本项目图像框架的 `+Y` 表示朝外法线,而场景使用的 Unity Quad 正面沿局部 `-Z`,场景保存的 `+Z` 前向与图像外法线相反。把二者混为一个“方向”就产生 180° 差异。
缺少更早“正常包”的配套场景数据和位姿日志,无法解释每一次旧版本为什么看上去正确,不能称作“以前全部靠误打误撞”。本次也没有证据证明 SDK 把图案识别成镜像。
### 7.2 当前映射
`Assets/ALabToolkit/SLAM/ALT_LandmarkRearm.cs` 的 `ToAuthoredRotation`:
```csharp
Vector3 forward = Vector3.ProjectOnPlane(imageFrame * Vector3.down, Vector3.up);
return forward.sqrMagnitude > 0.000001f
? Quaternion.LookRotation(forward, Vector3.up)
: Quaternion.identity;
```
对当前素材/SDK 契约,取图像 `-Y`,投影到水平面后作为美术定位前向。这个负号是**本项目坐标约定**的结果,不是“所有 AR 图片都应该减 180°”的通用规则。
`ALT_TrackImageLandmark` 调用此转换时,后续跟随 Origin 变动仍保存原始图像 frame 的相对旋转,不能把已经转换为美术方向的 rotation 再当作原生图像 rotation 转第二次。
### 7.3 重复校准还要求正确的世界空间组合
设观测定位图世界位置/方向为 O,配置目标为 T,当前 XR Origin 为 R。只求世界竖直轴上的 yaw 差 Δ:
```text
Δ = 绕 worldUp 旋转 SignedAngle(水平观测前向, 水平目标前向)
t = T.position - Δ * O.position
新 Origin.position = Δ * R.position + t
新 Origin.rotation = Δ * R.rotation
```
注意是**左乘**世界空间旋转。首次 Origin 恰为单位旋转时,错误的局部/世界组合可能不明显;经过一次重定位后再次使用就会出现偏差。`ALT_LandmarkRearm.TryRelocate` 和 `ALT_RelocationManager.FixCameraOffsetByLandmark` 修正这一组合,测试覆盖多个目标 yaw、多个已有 Origin yaw 和重复应用。
### 7.4 平面方向是否要求夹角小于 90°
需要先说明比较的是“有正反的法线”还是“同一个几何平面”:
- Vision 的平面匹配保留图像朝外 `+Y` 法线用于有符号方向比较,当前过滤阈值约 30°,并有面积/范围筛选和图像位姿回退。不能把第 7.2 节的负前向直接替代这里的朝外法线。
- PICO 几何匹配允许用 `abs(dot)` 判断是否接近同一个平面,随后再根据观察者所在侧确定朝外法线;其旋转依赖平面和重力,并非直接取摄像机朝向。不能把 `abs(dot)` 的结果直接当最终正面方向。
- 单独增加“小于 90°”并不能修复“图像法线与美术前向不是同一含义”的错误,也不能解决错误的 Origin 旋转乘法。
### 7.5 三个平台一致到什么程度
统一的是“原始跟踪坐标 → 明确的平台/素材坐标转换 → 世界 yaw/平移校准 → 持续注视避免重复触发、离开后允许重定位”的行为契约。Vision、PICO 与 Meta 的原生位姿轴定义、平面条件、锚点操作和稳定性判定存在差异。
PICO 使用 `ALT_PicoCalibrationGeometry.ToRelocationRotation` 等专用几何代码,且校准前后处理原生锚基线;Vision 保留自己的 Provider/锚点流程;Meta 的相机/PnP 坐标转换保留在 Meta 适配层。不要整份覆盖平台实现来追求表面上的“算法一致”。
## 8. 同图只识别一次、定位圆环卡住与定位失败
### 8.1 已完成标志不等于永久禁用
此前 `m_AlreadyFixCameraOffset` 在成功后持续为真,而图像离开视野时 SDK 可能继续保留该 trackable,不触发 removed/重新创建。只依赖 removed 事件清除标志,同一张 `ALabHouse101` 就只能校准一次。
通用 `ALT_LandmarkRearm` 的逻辑:
```text
待校准 → 识别有效且稳定停留 → 实际重定位成功 → 已完成
已完成且仍持续看图 → 保持完成,不每帧重新移动场景
已完成且跟踪丢失/离开视野持续约 0.6 秒 → 重新开放
回看 → 重新累计稳定停留 → 再次校准
```
`Observe` 将单次 deltaTime 限制在 0~0.1 秒,避免一次长帧把离开时长直接积满。视野判断使用头显相机 forward 与图像方向的夹角,不是眼动追踪 API。重新开放时同时复位圆环进度、稳定性计时、平面置信状态和完成特效。
Vision 的稳定性检查使用连续观测变化,PICO 的 `ALT_PicoCalibrationDwell` 使用参考基线;两者均有限制,但不能将二者描述成完全相同的滤波器。成功标志只在 `RelocationTimes` 真正增加后设置,不能把失败的重定位也锁定为“已完成”。
### 8.2 清理对象和事件生命周期
`ALT_TrackImageManager`、`ALT_TrackImageLandmark`、`ALT_RelocationManager` 对重复 GUID/移除事件/销毁进行清理;去掉嵌套 Instantiate 产生的孤立未初始化定位对象。销毁时退订事件,防止旧对象回调干扰当前圆环或校准次数。
### 8.3 1.0.24 新引入的圆环回归
为减少材质分配,曾把 `MaterialPropertyBlock` 放入 MonoBehaviour 字段初始化器:
```csharp
// 有问题:Unity 可能在加载线程执行组件构造/字段初始化。
readonly MaterialPropertyBlock properties = new MaterialPropertyBlock();
```
PICO 日志出现原生 `CreateImpl` 加载线程异常,随后更新圆环时不断空引用。这是本次优化引入的回归,不是图案质量或设备系统天然不支持。
三端 `Assets/ALabToolkit/SLAM/ALT_TrackImageLandmarkLoadingRing.cs` 改为:
```csharp
MaterialPropertyBlock m_Properties;
MaterialPropertyBlock Properties => m_Properties ??= new MaterialPropertyBlock();
```
首次调用发生在主线程的正常组件更新/属性设置入口;共享同一 block 同时维护 `_Color` 和 `_FillAmount`,避免更新颜色把进度覆盖,或更新进度把颜色清掉。增加组件克隆、首次调用与颜色/进度同时保留的回归检查。正式 1.0.25 日志未出现该构造异常,用户确认圆环和多次定位恢复。
### 8.4 用错图也会导致“定位失败”
之前用户展示的 SH11(`ImageTrack_ShanHai_11.png`)属于沿途定位图,不能作为当前起点。此流程使用 `ALabHouse101.png`,牌面 L01。识别名称、参考图 GUID、后端定位配置和起点/点火标记必须对应。
使用完整原图,不只截取文字牌,不拿合成示意图代替原图;实际展示宽度需要与登记的 0.5 m 物理宽度相符。像素尺寸 2048×2048 不代表实际宽度 0.5 m。排查时应依次确认“Provider 活跃 → 图像入库成功 → SDK 输出跟踪 → GUID 对应 → 平面/稳定条件 → 重定位执行 → UI 反馈”,不能只看有没有圆环。
## 9. 完整离线启动:缓存文件只是必要条件
### 9.1 原流程为什么不完整
缓存过 AB、PNG 或登录信息,不代表启动不依赖网络。启动仍可能需要 launch 配置、定位/美术 JSON、Localization、目录地址/Hash、模型 Key 对应的依赖、Mask 等。缺少其中一环,断网时仍会卡在登录、查目录或还原。
### 9.2 新的成功快照契约
`Assets/ALabSpace/Sources/HttpDownLoad/ALS_OfflineStartup.cs`:只有一次联网启动完成所需配置、媒体、AB、场景还原等工作后,才调用 `CommitAsync` 发布“完整内容快照”。单独成功登录或下载到 100% 不代表快照已经可用。
身份隔离包含:后端、服务地区、平台/SDK 目标、请求 Dev/Pro 环境、登录身份、Player release/build 标识与摘要。请求环境与服务端批准的实际内容环境分开记录,不能让 `SetProjectInfo` 的实际环境回写改变本次缓存身份。
提交顺序:复制 DTO 并清除 token → 固定离线目录版本 → 验证依赖 → 生成内容摘要 → 写唯一临时文件并复读验证 → 主线程再次检查当前请求 → 原子替换完成快照。失败的新启动不会覆盖上一份完整快照。
`CaptureGuard` 对异步继续执行做所有者、generation、账号、环境、配置引用与资源身份检查,避免旧任务写坏新登录。这是必要保护,但在线“候选登录”不能套用“已保存登录”的前提,相关修正见第 13 节。
### 9.3 Addressables 必须真正走本地闭环
`Assets/ALabToolkit/Addressable/ALT_AddressableOfflineCache.cs` 与 `ALT_AddressableManager.cs`:
- 保存选定 catalog 的真实字节及设置摘要,完整快照固定 `catalogId`。
- 离线从明确本地 catalog 引导,不查询远端 hash、不跟随“最新目录”替代已完成快照。
- 递归检查所需资源的依赖,按 bundleName + Hash 精确核对 Unity 缓存。
- 离线 Provider 禁止转成 HTTP 下载、隐式重试下载或清理现有缓存。
- 缺少或损坏明确报错,不能把失败转成“空内容启动成功”。
### 9.4 缓存冷启动的误判
原生 `Caching.ready` 在应用刚启动时可能仍为 false。旧检查把“缓存系统还没就绪”当作“AB 不在缓存中”,造成磁盘有文件却报离线校验失败。
`WaitForCacheReadyAsync` 在依赖校验和本地 Provider 访问前异步等待,约 30 秒超时、16 ms 间隔。超时、Hash 不正确、真正缺少 AB 分别处理。修复不是跳过 Hash 验证,也不是重下所有 AB 或清缓存。
### 9.5 离线图片与网络边界
`ALS_ResourceImportSupport.DownloadResourceAsync` 在离线模式只使用完整且匹配的缓存;缺失直接报错,不在失败分支悄悄联网。完整快照还要覆盖当前 Locate/Art 引用的 Mask、图片等媒体。
`ALT_LoginManager` 与 `ALS_BackendHeartbeat` 不恢复旧 deviceToken,不开启旧心跳/SSE。自动离线回退仅针对传输不可用;401/403、无效店铺、设备环境不允许等业务拒绝不能当成断网绕过。
当前能力是**已经完成过联网准备的对应账号/版本,断网启动并还原内容、加载定位图、进行本地校准**。首次安装、升级、更换环境/账号/项目、系统清理缓存或资源未齐,都需要重新联网完成准备。静态资源可能可复用,完整启动身份不能跨作用域冒用。
后台远程点火/巡游指令依然需要网络。用户提出的“本地事件触发点火”属于后续功能,不能把当前离线启动修复写成该功能已经实现。
## 10. 离线进度停一半与每次图片“重下载”
### 10.1 场景已播放,UI 为什么还在
PICO 1.0.23 用户确认场景、语音和校准正常,但 UI 一直显示“离线启动,正在检查本地资源”,总进度停在一半。`ALS_FlowActions.LoginAndInitSystem` 给登录子任务设置了 0.5,离线成功分支没有把它设置为 1。
修复在本地配置与必要初始化成功后完成 Login 子任务,让聚合进度自然结束。`Assets/ALabSpace/Sources/UI/ALS_LoadingUI.cs` 仍负责真实阶段/失败状态,不能通过强行隐藏整个 Canvas 来掩盖还没完成或失败的准备工作。PICO 1.0.25 断网复测确认 UI 能结束。
### 10.2 出现进度不等于发生网络下载
图片准备包含:清单/摘要校验 → 必要时下载 → 解码 → 原生识别库注册 → 跟踪启动。原生图库通常属于本次进程,PNG 已在磁盘也仍需注册。
通过 `ALS_LoadingUI.ImagePreparationPhase`、资源准备阶段以及 `ALS_DynamicImageManager.DownloadImage` 区分文案;缓存命中日志记录 `networkRequests=0`。判断是否每次重新下载应看请求数、资源摘要和缓存命中,而不是看进度条是否重新出现。
## 11. PICO 单眼花屏与紫色材质
### 11.1 渲染目标不能跨 await 泄漏
用户报告左眼花屏,退出 allinxr 返回系统后恢复。这说明当时现象与应用运行有关,不能直接判为系统或硬件坏了。
`ALT_PicoSwanTracking` 缩图路径执行 Blit 后等待 GPU 回读,旧路径没有及时恢复 `RenderTexture.active` / `GL.sRGBWrite`,让临时目标/色彩状态跨越异步等待暴露给后续渲染。
修复为同步作用域保存并恢复状态:
```text
创建临时 RT
进入 ALT_RenderTargetScope
Blit / 配置需要的渲染状态
退出作用域,立即恢复原 RenderTexture.active 与 GL.sRGBWrite
等待 GPU 回读
finally 释放临时 RT
```
主要文件:
- PICO `Assets/ALabToolkit/SLAM/ALT_PicoSwanTracking.cs`(具体文件位置以附录索引为准)。
- 三端 `Assets/ALabToolkit/Common/Utils/ALT_RenderTargetScope.cs`。
- 三端 `Assets/ALabToolkit/Login/ALT_FileUtils.cs` 的图像复制/回读工具。
Windows D3D11 与 Mac Metal 实际渲染验证覆盖恢复和失败路径,PICO 后续双眼真机正常。代码状态泄漏风险已确认并修正,但没有原故障时的 GPU/合成器追踪,不能据此解释所有将来出现的单眼花屏。
### 11.2 紫色模型的结论必须保守
两个远处方形模型仅在 1.0.24 诊断包出现紫色。正式 1.0.25、相同 AB 内容下用户确认不再出现。没有锁定那两个 Renderer 的 Shader/关键字/剔除变体,因此精确原因仍未确定。
若复发,应记录对象路径、材质/Shader、关键字、构建类型、图形 API 与实际 catalog/AB Hash,再检查变体剔除和材质绑定。不要因看到紫色就重建所有 AB,也不要把 PSO 缓存缺失当成已证实结论。
## 12. 可复用的诊断和回归方法
### 12.1 先定位阶段,再锁定函数
1. 固定版本、平台、Player/AB/catalog 标识、账号作用域与联网状态,保留原始记录。
2. 记录用户看见的提示与代码阶段时间,不把整个“下载图片”UI 对应成单一下载函数。
3. Android 同时记录 logcat 和 Perfetto;需要函数级证据时使用专门诊断包的 Unity Profiler。正式验收再回到正常构建。
4. 比较主线程、渲染线程、XRUpdate 与具体函数耗时;没有栈时把候选原因标为候选。
5. 修复后保留同类场景的前后数据,注明指标和采样条件差异。
### 12.2 真机回归矩阵
| 场景 | 应检查的结果 |
| --- | --- |
| 首次联网完整启动 | AB/媒体完整、资源引用恢复、进度结束、快照成功提交 |
| 已缓存再次联网启动 | 无无意义重下、原生图库就绪、转头时无秒级停顿 |
| 杀进程后断网冷启动 | 等缓存 ready、固定本地 catalog、无网络兜底、场景/语音/进度正常 |
| 第一次看起点图 | 正确图/GUID、有效跟踪、圆环推进、位置和朝向正确 |
| 一直盯着同一张图 | 完成后不每帧重复移动场景 |
| 移开约 1 秒再看同图 | 重新出现校准反馈并能再次完成 |
| Origin 已旋转后再次定位 | 世界旋转/平移组合正确,不累积 180° 或平移误差 |
| 双眼显示与图片回读 | 正常颜色、双眼一致,无临时渲染目标污染 |
| 切换 Dev/Pro、设备或地区 | 作用域隔离,新登录可提交,旧异步结果不能覆盖新状态 |
| 错误账号/业务拒绝 | 保留原有效保存信息,不伪装成离线成功 |
| 缺文件/坏摘要/清缓存 | 明确失败,不能强制隐藏 UI 伪装成功 |
### 12.3 自动化检查与真实边界
现有 Editor 验证入口在 `Assets/ALabSpace/Sources/HttpDownLoad/Editor/`,包括:
- `ALS_SequentialImportValidation`:分批场景导入、引用范围与回滚。
- `ALS_ImagePreparationValidation`:图像清单/receipt/图片准备。
- `ALS_RuntimeReliabilityValidation`:资源/生命周期风险。
- `ALS_OfflineStartupValidation`:身份、摘要、原子发布、异步 guard、离线媒体;本轮追加候选登录检查。
- `ALS_OfflineCatalogValidation`:实际 catalog 与依赖结构。
- `ALT_HardwareFixValidation`:方向、世界变换、重新开放校准等数学/源码检查。
- `ALT_RenderStateValidation`:渲染目标恢复、圆环实例化/属性、矩形 Sprite。
- `ALS_PlayerScriptValidation`:对应 Player 平台编译。
这些检查各有范围:数学通过不表示相机追踪已经通过;可执行 guard 测试不等于真正服务端成功登录;代码检查不能替代编译,编译不能替代设备观察。报告应保留 coverage/limitations,不能只汇报一个总“通过”。
## 13. Pro 登录失败:离线保护过度约束了新登录
### 13.1 现象与日志
三端 Dev 验收后,PICO 关闭 Dev,填写 Pro 账号并保存,界面报登录失败;重新打开面板资料为空。2026-11-15 logcat 捕获到:
```text
[ALT_LoginUI] Submit failed at login-and-launch-cache: OperationCanceledException.
```
这是客户端保存链路异常,不能仅凭 UI 的“网络/输入”文案认定账号错误或后端故障。
### 13.2 两个概念被混用
`ALT_Constant.BackendCacheScope` 按后端、平台、SDK 和请求环境隔离登录文件。首次进入 Pro 没有保存资料时显示空白是合理的,Dev 文件没有因此被删除。
错误在于 `ALT_LoginManager.LoginV2(candidate)` 使用了要求“当前已保存账号必须等于传入账号”的 `CaptureGuard`。面板刚输入的新设备号/Key 本来就可以与旧账号或空账号不同,验证却在网络请求前将其判为过期调用。另一个条件是切换偏好后,在新 generation/请求环境建立之前进行旧偏好检查,也可能立即取消合法请求。
UI 原设计是在服务端成功后才 `manager.LoginInfo = candidate`。这个顺序应保留,不能为了通过检查先保存未验证的新资料。旧版因为验证根本过不去,所以 Pro 一直没有成功保存,下次打开仍为空。
### 13.3 三端修复
- `ALS_OfflineStartup.BeginLoginAttempt(candidate)`:先解析当前缓存作用域,再建立新的 generation/请求环境;允许候选资料与当前保存资料不同。
- 内部 `CaptureGuardCore`:同时捕获候选身份与保存资料的基线身份。等待期间候选被修改、保存账号被改变、所有者替换、环境变化或新请求开始,旧请求仍会取消。
- `ALT_LoginManager.LoginV2` 使用新的在线候选 guard,删除“新登录必须已经保存”的错误前置检查。
- 原 `CaptureGuard(login, config)` 继续严格保护离线读取、资源还原与完整快照提交,不能因此放开跨账号/环境缓存。
- 保存成功仍发生在验证返回之后;失败不写候选账号,Dev/Pro 缓存继续独立。
新增回归覆盖:新账号与已保存账号不同、首次空缓存、新候选被修改、等待中保存资料变化、新请求淘汰旧请求、管理器替换、偏好切换前后、真实 `LoginV2` 失败路径保留原保存资料。网络成功、覆盖安装后的 UI 保存与重启需真机另行确认,进度见当前交付记录。
这是可迁移的教训:**“新身份认证事务”和“使用已认证身份的启动事务”不能共享同一个未经区分的前置条件。** 同时也不能为修复首次登录把所有取消检查移除。
### 13.4 修复包复测又报错:第二个原因是发布流程遗漏
PICO 1.0.26(24)第一次复测仍显示“网络/输入”,但日志已经从本地 `OperationCanceledException` 变为服务端 HTTP 409。检查发现,Player 26 的构建状态为 confirmed,`published` 仍为 false;本次交付在覆盖安装之前漏做了发布到 Pro 的步骤。原包 Player 25 已发布,此项不是最初旧包登录失败的原因。
后端 `lib/shan2/runtime.js` 对 Pro 请求要求包内 Player 版本既已确认又已发布;`lib/shan2/content.js` 的 `/as/v2/app/publish` 负责发布。补齐 Player 26 的发布元数据前,核对了包内 build ID、snapshot digest、AB 1 和四个项目快照,内容与上一发布版本一致;历史 Player 不变。**本地 APK 不提供云端下载,仍然需要对应 Player 元数据允许 Pro 启动。** 两者是不同的发布动作。
这次没有靠改成 Dev 或放宽后端认证规避问题。复测结论以同日交付记录为准。以后交付顺序应为:包身份与签名核验 → 构建确认 → 对照内容快照发布指定 Player → 检查 Pro 可用状态 → 再通知用户测试。通用“网络/输入”错误文字无法区分客户端取消与服务端业务拒绝,排查时必须保存实际异常类型和 HTTP 状态。
## 14. 主要代码索引
下列路径在相应工程中核对;共享实现迁移时按方法逐段合并,保留平台 SDK 适配。
| 模块 | 文件相对路径 | 重点入口 |
| --- | --- | --- |
| 媒体缓存/校验 | `Assets/ALabSpace/Sources/HttpDownLoad/ALS_ResourceImportSupport.cs` | `CacheIsValidAsync`、`LoadTextureFileAsync`、`VisitImageFilesAsync`、`DownloadResourceAsync` |
| 动态图片流程 | `Assets/ALabSpace/Sources/Image/ALS_DynamicImageManager.cs` | `DownloadImage`、`VisitDynamicImagesAsync` |
| 原生图库 | `Assets/ALabToolkit/SLAM/ALT_TrackImageManager.cs` | `BuildLibraryV2`、移除/重复图片清理 |
| 图像定位对象 | `Assets/ALabToolkit/SLAM/ALT_TrackImageLandmark.cs` | 位姿转换、稳定计时、重定位结果与重新开放 |
| 调试预览 | `Assets/ALabToolkit/SLAM/ALT_TrackImageLandmark_Debug.cs` | Player 禁用;FullRect Sprite |
| 调试中心 | `Assets/ALabSpace/Sources/Debug/ALS_DebugCenterUI.cs` | 图像预览资源与环境偏好 |
| 圆环 | `Assets/ALabToolkit/SLAM/ALT_TrackImageLandmarkLoadingRing.cs` | 延迟创建 MaterialPropertyBlock、颜色/进度同步 |
| 共用数学/重新开放 | `Assets/ALabToolkit/SLAM/ALT_LandmarkRearm.cs` | `Observe`、`ToAuthoredRotation`、`TryRelocate` |
| 场景校准 | `Assets/ALabToolkit/SLAM/ALT_RelocationManager.cs` | `FixCameraOffsetByLandmark` |
| Addressables | `Assets/ALabToolkit/Addressable/ALT_AddressableManager.cs` | 目录扫描、依赖/句柄、缓存就绪 |
| 本地目录 | `Assets/ALabToolkit/Addressable/ALT_AddressableOfflineCache.cs` | 固定本地 catalog、缓存 Provider/依赖验证 |
| 完整离线启动 | `Assets/ALabSpace/Sources/HttpDownLoad/ALS_OfflineStartup.cs` | `ReadAsync`、`CommitAsync`、`CaptureGuard`、`BeginLoginAttempt` |
| 登录 | `Assets/ALabToolkit/Login/ALT_LoginManager.cs`、`ALT_LoginUI.cs`、`ALT_Constant.cs` | 候选登录、成功后保存、环境缓存作用域 |
| 离线流程/UI | `Assets/ALabSpace/Sources/Flow/Actions/ALS_FlowActions.cs`、`Assets/ALabSpace/Sources/UI/ALS_LoadingUI.cs` | Login 子进度、图片准备文案 |
| 服务端连接 | `Assets/ALabSpace/Sources/HttpDownLoad/Server/ALS_BackendHeartbeat.cs` | 离线时不使用旧 Token/远程点火 |
| 渲染状态 | `Assets/ALabToolkit/Common/Utils/ALT_RenderTargetScope.cs`、`Assets/ALabToolkit/Login/ALT_FileUtils.cs` | 临时渲染目标/色彩状态恢复 |
| 场景导入 | `Assets/ALabSpace/Sources/ProjectConfig/ImportExport/Manager/ALS_ImportExportManager.cs` | 已提交根引用、事务写入范围 |
| 引用解析 | `Assets/ALabToolkit/Json/ALabGameObjectUtils.cs` | `BindImportedRoots` |
| 阶段计时 | `Assets/ALabToolkit/Common/Utils/ALT_StartupTiming.cs` | 区分下载、初始化、图片与还原阶段 |
Vision 专属 Provider 路径见第 6 节;PICO 专属 `ALT_PicoCalibrationGeometry`、`ALT_PicoCalibrationDwell`、`ALT_PicoSwanTracking` 在 PICO 工程中按类名定位;Meta 专属校准在 `Assets/ALabToolkit/Meta/` 下,不替换为 Vision 的轴转换。
## 15. 留存证据、版本与交付约束
本机可复查的中心记录:
- [场景还原记录](EVIDENCE.md)
- [早期启动性能记录](EVIDENCE.md)
- [启动稳定性记录](EVIDENCE.md)
- [Vision Provider 修复记录](EVIDENCE.md)
- [1.0.24 函数级长帧归因](EVIDENCE.md)
- [1.0.25 联网/离线真机验收](EVIDENCE.md)
- [Vision 用户真机验收](EVIDENCE.md)
- [Vision 平面/坐标核查](EVIDENCE.md)
- [旧修复的源代码 SVN 记录](EVIDENCE.md)
- [旧修复最终提交记录](EVIDENCE.md)
Vision 方向修正关键提交为 r53;后续运行时代码与资料提交以记录中的逐仓库修订号为准。不同 SVN 仓库的同一个数字没有可比关系。
原始 logcat、性能文件和私有诊断放在本机发布目录的 `private` 子目录,可能包含账号/session 数据,不上传公开文档。不要为改写总结覆盖历史发布报告。本文与本轮交付记录追加最新反馈,旧失败包仍保留其当时状态。
PICO/Meta 安装包只保留本地安装;Vision 通过 Mac 构建并按发布任务上传 TestFlight。纯文档更新不需要重打 AB 或客户端;运行时代码修复需要新 Player,只有资源依赖变化才决定是否重打 AB。对未来迁移项目,应保留诊断构建与正式构建区分、符号、精确源码版本和可复现用例。
<!-- runtime-postmortem-20261115 -->
## 16. Pro 复测与后续三端包(2026-11-15)
PICO 1.0.26(24)补齐 Player 26 的 Pro 发布状态后,用户确认“保存成功,重启正常”。日志记录首次 Pro 准备下载 10 张图片,随后两次校验均为 `networkRequests=0`,并提交了完整离线快照。本轮没有单独验证 Pro 断网冷启动或完整点火路线。
Meta 1.0.20(21)和 Vision Pro 1.2.9(12)已包含同一登录修复;对应 Player 均已发布到 Pro,四项目配置预检通过,AB 和项目快照沿用原内容。Meta APK 仅本地交付;Vision 上传获 Apple 接受,处理完成及测试者可用状态尚未独立确认。两端新包的 Pro 真机验收待用户进行。当前交付记录为 `AllinXR-ProLoginRelease-20261115.json`。
## 17. 四种版本编号与“发布到 Pro”
| 平台 | 对外版本 | 系统构建号 | 后端 Player | AB |
| --- | --- | ---: | ---: | ---: |
| PICO | 1.0.26 | 24 | 26 | 1 |
| Meta | 1.0.20 | 21 | 29 | 2 |
| Vision Pro | 1.2.9 | 12 | 18 | 1 |
这四个编号分别管理安装包显示版本、系统升级顺序、后端构建身份/内容快照及资源产物。它们不要求相同,也不是四次下载。Player 编号按平台/SDK 记录,与成功安装次数无关。构建前预留记录,成功后 confirmed,允许正式使用时发布到 Pro。Dev 主要使用当前开发内容;Pro 还检查该 Player 的发布状态并读取其冻结项目快照。发布元数据不会把 APK 上传到服务器,也不会自动更新已安装头显。PICO/Meta 的本地安装策略与后端 Pro 授权相互独立。
## 18. 常见问题速查
操作版统一入口:[完整功能手册](https://webadmin.allinxr.com/environments/production/system-guide.html),可从导航返回登录、设备管理、常见问题与 Pro 发布步骤。
### 保存提示“登录失败:网络/输入”
**先检查:** 先记录版本、Dev/Pro、平台和发生时间;维护者查看实际异常或 HTTP 状态,界面这句提示不能单独判断原因。
**处理:** 核对 SDK、正式/开发设备绑定及 Key。HTTP 409 还要核对该包的 Player 是否已确认并发布到 Pro;旧包的候选登录取消问题需使用本次修复包。
**是否重打:** 仅遗漏 Pro 发布状态:不重装;客户端缺少修复:更新客户端;不因此重打 AB。
### 关闭 Dev 后,设备号和 Key 显示空白
**先检查:** Dev 与 Pro 使用独立登录缓存;第一次切换到尚未保存资料的环境时会空白。
**处理:** 输入该环境的正确资料,保存成功后关闭再打开面板,再重启检查。切回 Dev 应读取原 Dev 资料;不需要清除应用数据。
**是否重打:** 正常切换不重打包;保存成功仍丢失时保留日志排查写入或作用域。
### 日志是 400、401、403、409、429 或连接失败
**先检查:** 400:请求/必填项;401:账号或会话凭据;403:SDK/环境/权限不允许;409:发布、快照或配置未就绪;429:尝试过多。具体以响应说明为准。
**处理:** 不要统一当网络断开。检查输入、设备绑定和发布状态;限流时按提示等待再试。只有真正的连接不可用才按离线缓存流程处理,业务拒绝不能靠离线绕过。
**是否重打:** 先修配置或网络;是否更新客户端取决于实际错误,不按状态码一律重包。
### Player V29 和 APK 1.0.20(21)不一样,选哪个
**先检查:** 它们分别是后端记录、显示版本和系统构建号;AB 2 又是资源版本。
**处理:** 按交付表对照,在全局管理选择该包对应的 Player。头显只安装正确版本,不手工填写 Player。不要因为数字不同就改包或改设备号。
**是否重打:** 编号不同是正常的;发布已有已确认 Player 不重新打包。
### Dev 能用,Pro 失败或仍是旧内容
**先检查:** 检查项目是否已发布、该 Player 是否已发布、构建时冻结的快照是否包含当前项目与内容。
**处理:** 如果项目是在构建之后才改的,旧包继续使用旧快照是预期行为。先发布新项目内容,再构建并确认新 Player,再将该 Player 发布到 Pro。
**是否重打:** 快照内容需要改变时交付新 Player;AB 是否重建看资源依赖是否改变。
### 每次启动都有“下载图片/图片准备”进度
**先检查:** 首次切换环境可能下载;后续进度也包含本地校验、解码及原生识别库建立。
**处理:** 同一账号/环境/内容下看 ResourceCache 是否为 verified disk hit、networkRequests=0。若持续真实下载,检查缓存完整性、资源版本、应用清理和作用域变化;不要仅凭进度条判断。
**是否重打:** 正常准备不重包;缓存损坏先联网完成准备;持续异常需日志定位。
### AB 和图片都下载过,断网还是启动不了
**先检查:** 还需要该账号、地区、SDK、Dev/Pro 和安装包身份对应的完整启动快照;单独下载文件不等于整套准备完成。
**处理:** 先联网完整启动到加载结束,确认完整快照保存,再退出应用断网冷启动。升级、换账号/环境、清数据或资源不齐时重新联网准备。缓存系统未就绪和真正缺文件应分别处理。
**是否重打:** 当前修复包支持完整快照;不为离线错误直接清缓存或重新构建 AB。
### 离线能还原场景,后台却不能点火
**先检查:** 本地内容恢复与远程控制是不同能力。离线不会恢复旧 token、心跳和 SSE。
**处理:** 当前远程点火、暂停等后台指令需要网络。本地事件点火是后续功能,不能把离线启动支持当作该功能已经完成。
**是否重打:** 这不是资源下载故障;新增本地事件功能需单独开发和验证。
### 场景和语音正常,离线进度一直停一半
**先检查:** 历史包有登录子进度停在 50% 的缺陷;当前包已修正成功分支。
**处理:** 核对实际安装版本。新包复现时记录提示、时间和场景是否已运行,保留日志;不要强制隐藏整个加载 UI 来掩盖失败。
**是否重打:** 旧包更新客户端;新包先查日志,不默认重打 AB。
### 提示看向路牌,却没有圆环或无法校准
**先检查:** 先核对图名/GUID、当前项目、权限、跟踪是否就绪和真实展示尺寸。当前山海流程起点为 ALabHouse101(L01),SH11 是沿途定位图。
**处理:** 使用完整原图,不只截取文字牌;按参考图配置的真实宽度展示,减少反光与遮挡,稳定看图。Vision 检查世界感知权限及图像 Provider 就绪;PICO 还需满足平面与稳定条件。
**是否重打:** 用错图/权限不重包;旧识别库生命周期或圆环回归需更新修复客户端。
### 同一张图第二次看没有反应
**先检查:** 持续盯着已完成的图时,不会每帧重复移动场景,这是正常设计。
**处理:** 移开视线约 1 秒再回看,重新稳定停留并观察圆环。仍无法再次定位时,检查是否使用本次修复包,以及图像跟踪和重新开放状态日志。
**是否重打:** 旧一次性锁定问题已改客户端;无需因此重做定位图或 AB。
### 校准后模型反向 180°
**先检查:** 区分图像外法线、平面法线与美术定位前向,同时核对平台和目标定位点。
**处理:** 使用当前已修复的坐标转换版本。复现时提供图名、期望方向和实际方向;不要给全部场景统一再转 180°,也不要直接认定为镜像识别。
**是否重打:** 若代码坐标契约错误需改客户端;若定位配置错误需按项目发布/快照流程更新。
### 图片装载瞬间卡一下,是 ARFoundation 或 PSO 吗
**先检查:** 本次约 1.39 秒长帧已定位到调试预览的 Sprite 轮廓生成;其他停顿需分别看实际函数耗时。
**处理:** 先核对是否正常修复包、是否仍有运行时调试预览。复现时记录提示阶段,由维护者抓 logcat/性能追踪;诊断包与正式包分开验收。
**是否重打:** 不要凭“卡一下”就重做全部 Shader/AB;按证据决定改动。
### AB 下载完成,随后提示还原失败
**先检查:** 下载成功不等于对象引用还原成功;历史故障为 Art 找不到先前 Locate 导入的 Mask 根引用。
**处理:** 记录具体异常和安装版本,使用包含分批导入修复的客户端。资源缺失、引用范围、版本不匹配分别排查,不先清空所有 AB。
**是否重打:** 引用范围代码问题更新客户端;实际资源/配置损坏按对应版本修复。
### 模型变成紫色
**先检查:** 记录具体模型、材质、版本及是否诊断包。历史两个紫色方形模型只在诊断包出现,精确 Shader 原因未确认。
**处理:** 用正常发布包对比;维护者检查材质/Shader、变体与构建差异、实际目录和资源摘要。不要把这次现象写成已经证明的 PSO 问题。
**是否重打:** 需依据材质/资源或客户端构建的实际原因决定,不盲目重建所有包。
### 只有一只眼花屏
**先检查:** 先退出应用观察系统界面是否恢复;这只能帮助区分发生范围,不能直接证明硬件或系统坏了。
**处理:** 核对修复版本并记录哪只眼、发生阶段。当前修复包含临时渲染目标与 sRGB 状态恢复;仍复现需抓取应用/渲染日志。
**是否重打:** 应用渲染问题可能需更新客户端;不能仅靠重下 AB 判断。
### 校准成功,后台点“巡游开始”仍没反应
**先检查:** 检查选择的设备、SDK、Dev/Pro、在线状态与唤醒状态,以及指令是否到达并有执行回执。
**处理:** 在设备管理核对该设备详情,使用“巡游开始”;查看是否 pending、expired 或 failed,确认现场已准备好及本项目事件可执行。不要反复批量发送代替排查。
**是否重打:** 先检查连接、设备与指令状态;是否重包取决于事件代码,不默认需重打。
### 上传成功,但 TestFlight 还看不到新版本
**先检查:** Apple 接受上传、处理完成、测试组可用、头显安装是不同状态。
**处理:** 先核对版本和构建号,等待处理后刷新 TestFlight;仍不可用由管理员检查对应测试组/账号资格。当前 1.2.9(12)已获上传接受,测试者可用尚未独立确认。
**是否重打:** 不因暂时未显示就反复重打同一构建号或重复上传。
### 后台没有 PICO/Meta APK 下载入口
**先检查:** 这是当前明确的分发策略:Android 包只保留本地,Vision 使用 TestFlight。
**处理:** 使用交付记录里的本地 APK 路径覆盖安装;后端 Player 发布只批准正式使用,并不上传 APK。恢复在线下载需另行安排。
**是否重打:** 无需重新打包来恢复入口;不能把已发布到 Pro 等同于 APK 可下载。
### 切中文或身处中国,为什么仍连香港
**先检查:** 语言、系统地区路由、服务地区和 Dev/Pro 是独立配置。当前国内及其他系统地区均路由香港海外区,国内入口尚未开放。
**处理:** 使用当前统一新后台。国内域名/备案/服务准备好后按地区接入方案配置;不要改回旧项目接口。
**是否重打:** 未来路由/包内配置改变需按地区方案重打;语言切换本身不要求新包。
### 内容跟着头走,或者手势点不到 UI
**先检查:** 先区分系统世界追踪、应用对象跟随、空间 Canvas/输入模块和平台权限。
**处理:** 对比系统空间界面是否稳定;记录设备系统版本、权限与应用恢复过程。输入问题需要对应头显验证,编辑器鼠标可点不能代替手势验证。
**是否重打:** 按具体追踪或交互原因处理,不把所有现象都归因定位图。
<!-- ignition-flow-20261115 -->
## 2026-11-15:首次点火延迟与错误成功回执
本节保留打包前的三端源码修复记录;当时尚未制作或安装新客户端,后续已交付版本见下一节。现有 Vision 1.2.9(12)、PICO 1.0.26(24)、Meta 1.0.20(21)不包含此修改;AB 和后台业务代码未改。
### 现场证据与不能确定的部分
- 香港时间第一次:12:38:42.433 创建开始指令,12:38:57.857 成功回执,间隔 **15.424 秒**。第二次:12:40:50.510 创建、12:40:50.703 回执,间隔 **0.193 秒**。两次都不是一直未收到回执;用户反馈第二次正常。
- WebAdmin `lib/shan2/business.js` 只在按钮操作时创建 pending 指令;`lib/shan2/runtime.js` 根据成功 ACK 更新会话与 playing,也接收心跳上报状态。不能把“巡游中”解读为服务器仅发出指令就直接改状态。
- 旧客户端若未真正执行场景事件却回成功,后台同样会显示巡游中。已用真实客户端方法隔离复现这种缺陷,但没有第一次头显逐阶段日志,无法证明现场必然走了该分支。15.424 秒可能包含准备、SSE 建连/重连和心跳补收;不能直接称为网络丢包、ARFoundation 卡顿或固定 15 秒定时器。
- 旧代码的重复起点定位重连有 15 秒门限,但这是再次校准时的节流条件,不是每次点火强制等待 15 秒。没有现场第二次校准时刻,不能仅凭数字相近归因。
### 复现与代码修复(相同必要改动已同步三工程)
| 文件 | 原因 | 修复 |
| --- | --- | --- |
| `Assets/ALabSpace/Sources/HttpDownLoad/Server/ALS_BackendHeartbeat.cs` | 一般心跳 20 秒;定位注册不提前已有调度。执行前先写 playing,场景动作返回即认为成功。 | 注册时立即安排补收;waiting / 待回执每 2 秒,其余仍 20 秒;就绪谓词未满足时保留指令不消费;必需场景回调成功返回后才设置 playing。增加命令 ID、UTC 派发/延期/ACK 记录。 |
| `Assets/ALabToolkit/Login/ALT_LoginManager.cs` | 旧回调在登录持有者失效或取消时静默 return,也可能被上层当成功。 | 传递并保留 readiness,重连沿用;失效执行明确抛出取消异常;本地自动启动也先调用成功再写 playing。 |
| `Assets/ALabToolkit/SLAM/ALT_RelocationManager.cs` | `OnIgnitionReceived` 没确认场景点火监听者存在,派发空事件也标记已开始。 | 就绪要求当前未开始、事件管理器和点火监听者存在;用 `DispatchRequired` 派发 `96727f3076034853afb9208febb2ff7f`。执行前保留已开始保护,避免部分执行后再次启动。 |
| `Assets/ALabSpace/Sources/Trigger/ALS_EventTriggerManager.cs` | 普通 Dispatch 对无监听静默返回;监听异常只记录日志,被调用者无法知道失败。 | 增加 HasListeners 和仅用于必需动作的 DispatchRequired;派发前后确认监听者,聚合并传播同步监听异常。其他普通事件仍沿用既有派发方式。 |
| `Assets/ALabSpace/Sources/HttpDownLoad/Editor/ALS_IgnitionValidation.cs` | 原有指令账本测试不包含真实定位回调与场景监听失败。 | 新增端到端方法链的隔离测试,运行真实定位回调、事件派发和命令账本,不访问线上账号或发送真实点火。 |
### 保持的约束和边界
- 指令未准备好时不确认成功、不消耗一次性启动机会;超时后仍按原有有效期拒绝。必须先校准标记为 TriggerDianHuo 的起点牌;普通定位牌不会自动进入等待。空闲时发出的有效指令仍可排队,不改变既有后台操作协议。
- 同一命令重复收到时不重复触发;回执丢失只重发回执;部分执行抛错后记录失败并暂停,防止重试造成重复副作用;需查明错误并重新开始应用流程。登录代际隔离、截止时间和过期检查保留。
- 2 秒是网络可用、没有阻塞请求时的补收调度间隔,不承诺两秒内播放。当前判定为同步场景事件派发成功;异步动画、异步资源加载后续失败仍需内容层反馈,不能用 ACK 证明画面已经完成。
- 普通 OnEventDispatched 的数据恢复订阅只记录事件,不是场景点火监听者。未修改既有恢复格式,也未把记录写盘当作点火成功证据。
- 未增加离线远程点火;离线资源还原、图像校准按原流程。未改 ARSession、图片或朝向算法。
### 验证结果与下一次真机验收
修复前 3 项隔离检查复现:20 秒调度未提前、无场景监听仍成功、监听抛错仍成功。修复后 PICO、Meta、Vision 各通过 13 项点火检查和 80 项离线启动检查;Android / visionOS 目标脚本编译分别通过(89 / 88 / 84 个程序集),Vision 在 Mac 工程运行。13 项包含实际方法链、监听中途移除、取消、延后就绪、无 SSE 的心跳补收,以及现有重复通知、丢 ACK、旧登录在途返回和截止时间回归。源码与 Mac 同步摘要记录在交付目录。
这些是源码/编辑器验证,不是真机验收。后续需制作三端新客户端,先验证首次启动:校准触发点火起点牌 → 等待 → 一次开始 → 场景实际播放;再测丢失实时通知的补收、短断网、重复通知以及失败提示。记录服务器 createdAt、客户端注册/延期/派发/ACK UTC 与服务器 acknowledgedAt,才能拆开现场延迟。此改动本身不需重打 AB;继续遵守 PICO/Meta 仅本地安装、Vision TestFlight 的分发策略。
<!-- ignition-release-20261115 -->
## 2026-11-15:点火修复三端新包交付
上节“源码已修、待新包”是打包前记录。本次已生成 PICO **1.0.27(25)**、Meta **1.0.21(22)**、Vision Pro **1.2.10(13)**,包含同一套点火修复。
| 平台 | Player | AB | 交付方式 |
| --- | ---: | ---: | --- |
| PICO | 27 | 1 | 仅本地 APK |
| Meta | 30 | 2 | 仅本地 APK |
| Vision Pro | 19 | 1 | TestFlight 上传获 Apple 接受 |
三端新包均已核对真实版本、签名、构建身份和编译后的点火方法;AB 目录与原发布匹配且无 PDB。新的 Player 已确认并发布到 Pro;24 组四内容 Dev/Pro 编辑器启动配置预检通过,未替换现场设备登录会话。源码版本:shan2 r62、Shan2PICOSwan r76、shan2Meta r74。
现场验收仍待用户进行;Apple 处理完成及测试者可用状态未独立确认。第一次测试请保持联网,完成带 TriggerDianHuo 标记的起点图校准,核对等待状态后发送一次开始,再观察回执和场景真实开场。退出重启后重测,分别记录首次与第二次延迟。当前修复保证的是同步事件派发结果,不证明异步动画已完成,也不承诺所有点火两秒内完成。
当前交付记录:`AllinXR-IgnitionRelease-20261115.json`;详细代码原因和验证边界仍见上节。
## 19. 把本文件夹带到其他项目:先看这里
这个文件夹包含复盘正文、**实际源码快照**、测试源码、依赖版本和文件摘要。`Source` 内的代码直接复制自本次读取时已提交的工作副本,未为了示例而改写。它是跨项目迁移参考资料,不是可以整目录拖入 `Assets` 的 Unity 插件。
| 文件或目录 | 用法 |
| --- | --- |
| `README.md` | 本文:原因、修复、证据边界、迁移步骤和验收方法 |
| [SOURCE-INDEX.md](SOURCE-INDEX.md) | 每份实际代码的可点击路径、用途、平台、SVN 来源及重点方法行号 |
| [manifest.json](manifest.json) | 每个源文件的原始绝对路径、原工程、逐文件修订号、字节数和 SHA-256 |
| [DEPENDENCY-VERSIONS.json](DEPENDENCY-VERSIONS.json) | 本轮读取的 Unity 和包依赖版本;不是未来项目必须照搬的版本清单 |
| [DEPENDENCIES.md](DEPENDENCIES.md) | 未包含的组件、程序集和平台依赖,以及如何使用测试源码 |
| [VERIFY.py](VERIFY.py) | 离线校验快照与清单;运行 `python VERIFY.py`,不访问原工程或网络 |
| `Source/Common` | 仅收录 Vision、PICO、Meta **逐字节一致**的文件;相同不等于与平台/业务无关 |
| `Source/Vision`、`Source/Pico`、`Source/Meta` | 存在差异或平台独有的版本,保留原工程相对目录 |
| `Source/WebAdmin` | 后台命令、ACK、Player 发布逻辑参照;不是完整后端发行包 |
三个平台共享的是启动事务、缓存完整性、事件结果、重新开放等约束。原生图像识别、平面、相机位姿和 SDK 生命周期仍由各平台适配。不要挑一个平台文件覆盖另两个平台来“统一算法”。完整阅读顺序建议为:问题总表 → 对应章节 → 源码索引 → 依赖说明 → 本节以后的迁移及验收规则。
快照不包含业务账号、店铺凭据表、会话日志、`.env`、证书、签名密钥、APK、AB、PDB 或完整第三方 SDK。`Source/Vision/Packages/com.unity.xr.visionos` 的补丁文件保留了原许可证和补丁说明;复制源码不改变其许可。其他项目使用相应 SDK 时,应在自己的已授权 SDK 版本上核对补丁。未复制 `.meta`、Prefab、场景和 Shader,原工程里的序列化引用不会随这些 `.cs` 自动转移。
### 19.1 当前版本和历史验收的区别
本快照包含截至 2026-11-15 点火修复发布后的代码。当前交付为 PICO 1.0.27(25)/ Player 27、Meta 1.0.21(22)/ Player 30、Vision 1.2.10(13)/ Player 19;AB 分别为 1、2、1。最新包的点火真机复测仍待用户完成,Apple 接受上传也不等同于已核实所有测试者可下载。
PICO 1.0.25(23)已由用户确认在线和离线启动、两眼显示、材质、圆环和多次校准正常;PICO 1.0.26(24)另确认了 Pro 保存与重启。Vision 方向修复版本已有用户真机通过反馈。旧版本通过的项目不能自动写成最新包所有组合均通过。本文第 16、17 节与点火修复前半段保留历史版本背景,当前包以上述版本和“三端新包交付”节为准。
## 20. 用调用链定位:进度条所在阶段不等于卡住的函数
```text
登录候选/启动身份
→ 在线获取配置或读取完整离线快照
→ 固定 Addressables catalog,等待 Unity Cache 就绪,校验 Bundle 依赖
→ 图片文件检查(只有缺失/失效才在线下载)
→ 逐张解码 → 消费者/原生入库任务完成 → 释放纹理 → 让出帧
→ SDK 图像库安装及原生 Provider 运行确认
→ Locate / Art 等场景事务还原,解析已提交对象引用
→ 图像追踪 → GUID/配置匹配 → 有效性与稳定性门槛
→ 原始图像坐标转场景约定 → 重定位实际成功 → 圆环成功/重新开放
→ 带 TriggerDianHuo 的起点校准 → 点火就绪/等待
→ 事件执行成功 → ACK/播放状态上报
```
这是排障依赖关系图,不表示各平台把所有步骤都放在一个同步函数、严格串行执行。实际顺序以对应 `ALS_FlowActions`、`ALT_TrackImageManager` 和平台追踪入口为准。
### 20.1 卡顿的四类度量必须分别记录
| 度量 | 能说明什么 | 不能说明什么 |
| --- | --- | --- |
| 阶段墙钟时间,例如图片准备 8 秒 | 用户等待和流水线总时间 | 8 秒内每一帧都卡;某一个 API 耗时 8 秒 |
| 主线程函数时间/调用栈 | 哪段 CPU 工作占住当前帧 | GPU、合成器、全部网络时间 |
| Perfetto 线程调度/帧间隔 | 线程阻塞与系统时序、可见长间隔 | 没有函数采样时猜出具体 Unity 函数 |
| GPU/渲染/合成器数据 | GPU 饱和、读回同步和眼图链路 | 仅凭 CPU 进度条证明 Shader/PSO 根因 |
本次最强证据是诊断包一帧约 **1391.253 ms**,其中十次 `SpriteMeshGenerator.TraceShape` 共约 **1261.290 ms**,而该帧 `XRUpdate` 约 **6.089 ms**。所以修复对象是启动调试图片的 Tight Sprite 轮廓生成。即使后台已经缓存 AB 和 PNG,这段运行时 CPU 工作仍会再次发生。不能因为界面写“图片加载”,就把这帧归因于下载、AB 或 ARFoundation。
后续迁移项目应先保留同样阶段标记,确认首次调用栈;关闭 Player 调试缩略图,或为确需显示的矩形预览明确使用 `SpriteMeshType.FullRect`,并释放纹理/Sprite。不要因此关闭实际识别图库,也不要在没有 Shader 证据时增加一轮笼统的预热,把长帧挪到另一个阶段。
### 20.2 几个容易再次制造卡顿或闪退的写法
| 容易出错的做法 | 本次约束 |
| --- | --- |
| `async` 循环里面没有真正等待,十张图同帧全处理 | 耗时步骤后有明确让帧点;目录扫描按时间预算拆分 |
| `Task.Run` 包住创建 Texture、Sprite、Material 或 SDK 查询 | 后台只做纯文件/摘要等工作;Unity/原生 SDK 对象按线程契约访问 |
| 先读齐全部 PNG,再解码十张并保存列表 | 借出一张,等使用者结束再释放,限制峰值 |
| 用户取消就立即 Destroy 仍被原生 Job 使用的图片 | 等本次原生 Job 安全完成,再取消后续步骤及释放对象 |
| 把临时 RT 状态保持到 `await` 后才恢复 | 同步作用域内恢复渲染状态,GPU 任务所需资源另外保持存活 |
| 测试包增加调试图片后沿用正式包性能结论 | 调试功能自身也纳入差异清单和追踪 |
每帧 3 ms 等预算只是合作式检查点,不能抢占某个已经开始的单次 Unity API 调用。若一次调用本身超过预算,要减少该调用成本、改变数据布局或调整初始化阶段,不能靠循环里的计时判断解决。
## 21. 姿态契约:比“加 180°”更值得复用的部分
### 21.1 在纸上先写出四个空间
1. **SDK 图像坐标**:原生识别返回的轴、单位、时间戳。当前 Vision 路径的 `imageFrame * Vector3.up` 用作图像朝外法线。
2. **场景作者坐标**:设计时定位牌对象的轴;本项目 Unity Quad 可见面是局部 `-Z`,场景校准使用对象 `+Z`。
3. **追踪原点/相机坐标**:设备追踪坐标如何进入 Unity 世界,是否已经受上一次定位影响。
4. **场景世界坐标**:目标牌、XROrigin 和模型各自的世界位置/朝向。
“检测到墙面”“图像匹配正确”和“姿态适合直接给目标牌”是三件事。先把 SDK 的位姿变成场景作者约定,再计算世界变换。Vision 原始朝外法线仍用于选择平面,给重定位的朝向则使用 `ToAuthoredRotation`;二者不能混为一份已经转换过的姿态,再转换一次。
### 21.2 世界空间左乘示例
令当前观测图像为 `observed`,目标图像为 `target`,当前原点为 `origin`。只修正水平朝向时,计算把观测水平前向转到目标水平前向的旋转 `R`,然后:
```text
newOrigin.rotation = R * origin.rotation
newOrigin.position = R * origin.position + target.position - R * observed.position
```
可手算一个用例:Unity 中绕 Y 轴 +90° 把 `(0,0,1)` 转到 `(1,0,0)`。当观测图像在 `(1,0,0)`、目标在 `(0,0,2)`、原点在 `(0,0,0)` 时,`R * observed.position = (0,0,-1)`,平移量为 `(0,0,3)`。应用后观测点恰好落在目标 `(0,0,2)`。再用同一目标校准,应接近恒等修正,而不是每次累计转 180°。
应测试带有既有原点旋转和位移的用例;只测原点恒等姿态,会掩盖 `origin.rotation * R` 与 `R * origin.rotation` 的顺序错误。投影后前向接近零、NaN 或无穷值必须拒绝/按平台既定降级处理,不能把无效测量当成功定位。
### 21.3 平面正反面不是用一个夹角阈值解决
PICO 的平面匹配先用法线点积绝对值衡量几何平行性,同时检查图像到平面的距离和边界;物理墙面的法线可能有两种符号。随后用观察者处于墙的哪一侧选符号,朝向仍来自测得的平面和重力方向。`abs(dot)` 只适合该几何候选步骤,不等于允许最终场景朝向正反都算正确。
相机位置在这条路径中用于选“面向观察者的这一面”,不是让定位牌始终朝向相机。侧向退化、距离过远、未稳定、非有效追踪仍需拒绝。`ALT_PicoCalibrationDwell` 与几何类在**同一个** `ALT_PicoCalibrationGeometry.cs` 文件中,不要寻找一个不存在的同名独立文件。
Meta 则把采集时相机位姿与 PnP 相对结果组合到世界空间;异步计算回来时还需检查追踪原点是否改变。它有自己的坐标适配和背面判断选项。当前参考包保留 `ALT_MetaImageTracking`、`ALT_MetaCalibration` 和 `Calibration` 下的 Solver/Profile/Marker,不能直接塞入 Vision 的 `Vector3.down` 转换。
## 22. 离线启动与异步资源所有权
### 22.1 “可离线”是一项完整事务
```text
ONLINE_CANDIDATE
→ 验证账号/地区/环境/平台/Player/内容身份
→ 配置、定位数据、媒体及 AB 依赖准备完成
→ 固定本地 catalog、剥离会话令牌、计算完整性信息
→ 写临时快照 → 回读验证 → 再核对登录代际 → 原子提交
→ OFFLINE_READY
OFFLINE_START
→ 检查当前身份匹配 → 检查快照完整性
→ 等 Cache 就绪 → 检查全部依赖与媒体
→ 本地还原/图库准备 → UI 完成 → 可体验本地内容
```
新资源下载失败、中途取消或切换账号时,旧的成功快照不能被半成品替换。文件齐全却没有成功快照,也不能绕过身份与配置检查“碰运气启动”。`CaptureGuard` 负责识别旧异步请求,`BeginLoginAttempt` 则让尚未保存的新候选账号可以合法验证;二者不能再次被合并成“输入必须等于旧账号”。
离线启动不能依赖远程 catalog 的 hash 查询、最新版本探测、隐式下载,也不能借用旧登录 Token 启动心跳/SSE。401/403/409 等业务拒绝不应悄悄变成离线成功。首启离线、升级后身份变化、Dev/Pro 切换、缓存破损等情况必须有可解释结果,不能无限等待。
### 22.2 三种不同的生命周期
| 对象 | 何时允许释放 | 需要避免 |
| --- | --- | --- |
| 借出的 Texture2D | 异步消费者及其原生入库任务完成后 | 取消时提前 Destroy;重复缓存所有原图 |
| Addressables Handle | 本拥有者不再使用且不转交给其他拥有者时 | 失败路径漏 Release;无归属备用加载返回另一份句柄 |
| 临时 RenderTexture | GPU 读回结束,且不再被请求引用后 | 只恢复 `RenderTexture.active` 就立刻释放尚在使用的 RT |
渲染全局状态与 GPU 资源寿命要分开:`ALT_RenderTargetScope` 的同步作用域结束时恢复 `RenderTexture.active` 和 `GL.sRGBWrite`;这不表示 GPU 已经读完纹理。反过来,GPU 还没结束也不是让全局 RT 状态跨帧泄漏的理由。
### 22.3 图片准备 UI 应有结束条件
UI 应体现校验、本地读取、实际下载、解码和原生入库,不应每次都笼统暗示重新联网下载。最有用的诊断是具体请求次数/字节和阶段耗时。离线 Login 子阶段在有效本地配置完成后必须设置完成值;场景播放成功并不会自动改掉另一个子进度一直停在 0.5 的状态。
远程后台点火仍需要网络。本次支持离线资源还原与校准,没有把未来的“本地事件点火”作为已经实现的功能。
## 23. 圆环、定位失败和点火:逐层检查表
| 停在哪一层 | 应记录/检查 | 对应源码入口 |
| --- | --- | --- |
| 提示看图但没有任何追踪事件 | 原生 Provider 是否运行,图库图片数/注册结果,权限与应用恢复状态 | 平台 `ALT_TrackImageManager`;Vision Provider 补丁 |
| 有追踪但不是当前起点 | 原图 hash/名称/GUID、配置清单、物理宽度、当前内容/DevPro | `ALS_DynamicImageManager`、`ALT_TrackImageLandmark` |
| 追踪已匹配但迟迟不进入校准 | Tracking 状态、头部视野、稳定计时、平面/姿态/距离门槛 | `CanFixCameraOffset`、PICO Geometry/Dwell、Meta 稳定观测 |
| 圆环出现后卡住 | 是否有主线程 API 异常,加载线程字段初始化,进度是否继续变化 | `ALT_TrackImageLandmarkLoadingRing` |
| 圆环完成但场景未定位 | `RelocationTimes` 是否真正增加,变换有效性、实际原点是否更新 | `ALT_RelocationManager`、`TryRelocate` |
| 第一次成功,第二次无反应 | 是否持续看着同一图、离开/失跟多久、重新开放与旧对象清理 | `ALT_LandmarkRearm.Observe`、Removed/OnDestroy 路径 |
| 校准后后台仍空闲 | 该图是否配置 TriggerDianHuo;是否当前会话/同环境;点火监听是否就绪 | `ALT_RelocationManager`、`ALT_LoginManager` |
| 后台已巡游但场景无开场 | 命令 ID/派发结果/ACK,以及内容异步播放结果 | Heartbeat、`DispatchRequired`、WebAdmin runtime |
当前重新开放使用的是头部前向视锥与追踪状态,不是眼球注视传感器。持续离开/失跟累计达到 0.6 秒才重新开放,单次累加最大 0.1 秒,避免一帧长停顿被当成完成整个离开过程。一直盯着同一张图不应连续重定位。测试时移开视线约一秒再回看,确认新圆环与新的实际校准次数。
Vision 的连续观测稳定性和 PICO 的基线稳定计时并非完全相同算法;不要把某一平台阈值写成全平台统一事实。所有阈值都是本项目当前实现,迁移后要根据真实尺寸、距离和定位噪声重新验收。
### 23.1 点火时间线要包含“实际开始”
建议在未来项目统一记录 `command.created`、`listener.ready`、`command.received`、`dispatch.begin/end`、`ack.sent/accepted`,并由内容层另报 `experience.started`。所有记录带命令 ID 和同一时间基准,敏感会话凭据不写公开日志。
本次 `DispatchRequired` 能区分无监听、同步抛错和同步成功;未就绪延后不消费命令,失败与部分执行不会盲目自动重试。它仍不能观察一个回调内部启动的异步动画最终是否成功。后台“巡游中”和用户看到开场并非同一个观测点。第一次 15.424 秒尚缺头显阶段日志,保留这个边界,比把修复后代码缺陷反推成唯一现场原因更可靠。
## 24. 迁移次序与验收标准
1. **固定基线**:记录原工程版本、SDK、渲染管线、AB/catalog/图片摘要;保存可复现输入与阶段日志。先只接入计时,建立对照。
2. **建立坐标适配**:为目标 SDK 明确图像法线、可见面、世界/局部空间和采集时刻;先测恒等、90°、180°、已有原点旋转、第二次校准及退化输入。
3. **修复资源生命周期**:逐张图片借用、原生任务完成后释放、Addressables 句柄归属、RT 状态同步恢复。随后测内存峰值、取消、失焦/恢复。
4. **独立处理 Provider**:确认运行时更换图库的原生行为;只对证据指向的子系统重配,不把全局 ARSession reset 当通用重试。对目标 SDK 升级前后运行相同回归。
5. **完成离线事务**:先有一次完整在线成功,再测真正断网冷启动;故意破坏一个必要文件,验证明确报错、无隐式下载、旧有效快照保护。
6. **恢复 UI 与交互闭环**:圆环参数更新必须在正确线程;失败不伪装成功,完成标志不能永久禁用同图;进度结束条件与业务完成一致。
7. **接入点火结果协议**:先就绪再派发,区分排队、同步失败、ACK 与内容真正开始;保留去重、过期、登录代际和失败后的副作用保护。
8. **逐平台真机验收再发布**:编辑器数学测试和构建通过只完成部分工作。校准方向、双眼、短暂停顿、原生 Session、离线冷启动必须在相应头显验证。
| 回归场景 | 预期 | 推荐证据 |
| --- | --- | --- |
| 已缓存资源联网冷启动,加载时转头 | 无本次调试 Sprite 秒级长帧;区分少量正常波动 | 主线程函数时间、帧间隔、阶段请求计数 |
| 无缓存首启 | 明确下载后准备,峰值受控 | 请求/字节、内存、入库逐张日志 |
| 完整成功后断网杀进程再启动 | 场景/语音/图库可用,进度结束,不访问后端 | 本地快照摘要、依赖验证、网络请求计数 |
| 删除一个必需 AB/PNG | 给出缺失说明,不无限卡进度或假成功 | 指定缺失文件/依赖和失败阶段 |
| 启动途中切账号/DevPro/地区 | 旧请求不覆盖新身份或快照 | generation/owner 与结果提交记录 |
| 同图首次 → 看开 → 再看 | 两次有效圆环和两次实际校准 | Trackable ID、稳定计时、RelocationTimes |
| 不移开持续看图 | 不反复触发重定位 | 完成与重新开放状态 |
| 90°/180°/已旋转原点再定位 | 目标姿态一致,无累积翻转 | observed/target/origin 与修正后的残差 |
| Provider 换库、暂停恢复 | 新图可识别,旧回调不串入 | 原生会话/库代次与注册状态 |
| 第一轮点火、丢实时通知、丢 ACK | 延后就绪/心跳补收,单次执行,重发回执 | 全命令时间线与内容实际开场 |
| 无监听/同步监听抛错 | 不报成功,不把失败显示巡游 | 失败回执与本地错误 |
| 平台图形读回并行进行 | 两眼稳定,RT 状态未泄漏 | 渲染状态测试和真机观察 |
## 25. 本参考包的验证边界
本次文档任务验证源文件与快照逐字节一致、源代码是已提交状态、链接/清单/压缩包可用、三工程与 WebAdmin 文档同步。**本次未修改运行时代码、未新建 APK/AB/Archive、未再次运行头显体验。** 附带测试是供迁移者理解和运行的实际源码,历史测试通过数见正文,不将复制测试文件视为重新执行测试。
`ALS_OfflineStartupValidation` 的 80 项检查有明确覆盖边界:快照完整性、部分身份/守卫/命令逻辑已测;完整真实网络到配置、媒体、catalog、场景还原、定位和恢复的全链路不由这套隔离测试独立证明。`CommitAsync` 的完整依赖环境和真实在途 I/O 竞争也不能用几个模拟延时断言替代。
可以确认的功能缺陷,应保留能让旧代码失败、新代码通过的最小回归。没有 native crash/合成器/Shader 堆栈的事故,保留“已修复具体风险/新包未复现”的结论;不要升级成已证实 OOM、PSO、系统问题或图片镜像。这个区分是后续其他项目排障时最需要复用的方法。