# Library 启动预热与运行时异步加载混合重构计划进度更新

文档日期：2026-04-04

对应主计划：
- `docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md`

## 本轮已完成

- `mesh_tests` 全量 `34/34` 通过。
- `scene_tests` 全量 `63/63` 通过。
- `asset_tests` 全量 `55/55` 通过。
- `texture_tests` 全量 `28/28` 通过。
- `XCEditor` Debug 构建通过。

- `Main.xc` 轻量场景测试预期已和当前项目夹具同步：
  - 当前场景对象是 `Sphere`
  - 不再沿用旧的 `Cube` 预期

- `AssetImportService::ImportStatusSnapshot` 已增加：
  - `startedAtMs`
  - `completedAtMs`
  - `durationMs`

- `ProjectPanel` 的 Library 状态展示已增强：
  - 状态文案可显示耗时
  - tooltip 可区分 operation / state / duration / target / imported count / removed count

- 一个阻塞当前回归验证的无关编译问题已修复：
  - `engine/src/Resources/UI/UIDocumentLoaders.cpp`
  - 不再非法调用 `IResourceLoader::GetExtension()` 的 protected 接口

## 当前阶段判断

当前这条 Library 重构线已经达到下面这个阶段性状态：

- 启动阶段负责恢复索引和缓存状态
- 运行时继续按需异步恢复 mesh / material / texture payload
- 关键回归测试已经稳定通过
- Editor 主程序可以正常构建

也就是说，前面最容易反复回退的两类问题已经清掉了：

- `Library` / artifact / `AssetRef` 主链路回归
- scene fixture 漂移导致的假失败

## 相对主计划的完成情况

- 阶段 1：已完成
  - `BootstrapProject()` / `BootstrapProjectAssets()` 已正式接入启动链路

- 阶段 2：已完成
  - artifact 直载
  - cache hit 快速校验
  - 避免把 artifact 路径重新误送回导入链路

- 阶段 3：已完成首轮并稳定
  - scene open 不再因为 Library 命中路径本身阻塞主线程
  - backpack 场景异步恢复链路回归通过

- 阶段 5：推进中
  - 主要阻塞点已经清掉
  - 但 editor 里剩余同步兜底访问点仍需继续系统化审计

- 阶段 6：推进中
  - 现在已经有 bootstrap/import 状态
  - 但还需要继续区分 bootstrap / scene restore / runtime streaming

- 阶段 0 / 阶段 4 / 阶段 7：未收口
  - 启动与首帧指标基线还没正式固化
  - metadata 预热策略还没补完
  - 最终收口文档和归档还没做

## 下一步建议

下一阶段不要再回头重做 `Library` 主链路本身，重点应当转到“观测”和“收口”：

1. 固化启动基线与场景首帧指标
2. 审计 editor 主线程剩余同步兜底点
3. 给 viewport / inspector / picker 加上未完成异步资源的占位与状态提示
4. 把“正在预热 / 正在导入 / 正在异步恢复”拆成更明确的 UI 状态

## 这一轮改动直接涉及的文件

- `engine/include/XCEngine/Core/Asset/AssetImportService.h`
- `engine/src/Core/Asset/AssetImportService.cpp`
- `editor/src/panels/ProjectPanel.cpp`
- `tests/core/Asset/test_resource_manager.cpp`
- `tests/Resources/Texture/test_texture_loader.cpp`
- `tests/Scene/test_scene.cpp`
- `engine/src/Resources/UI/UIDocumentLoaders.cpp`