XCEngine/docs/used/Library启动预热与运行时异步加载混合重构计划_进度更新_过期归档_2026-04-11.md

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

归档状态：2026-04-11。本进度更新对应的主计划已被后续细分方案覆盖，不再单独作为活跃跟踪文档保留，现转入 docs/used 作为阶段历史记录。

文档日期：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