XCEngine/docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md

Library资产导入与缓存系统收口计划

归档状态：2026-04-03，当前 project 范围内的 Library 导入与缓存系统收口已完成，本文档转为归档记录。

0. 文档定位

这份文档不是上一轮“从零搭一套 Unity 式 Library 体系”的继续描述，而是当前阶段的正式收口文档。

0.1 当前执行进度（2026-04-03）

阶段	状态	当前结果
阶段 A：协议定稿与旧兼容删除	已完成	已删除 mesh= / materials= 旧兼容读取，项目资产序列化正式收敛到 AssetRef，路径字段仅保留给虚拟资源；scene 迁移工具链已移除。
阶段 B：导入与缓存边界收口	已完成	AssetImportService 已接管 Library 根目录、快照构建、缓存重建与 artifact 保证入口；ProjectAssetIndex 已只消费服务快照；ResourceManager 已收口为运行时缓存/异步调度入口，并提供 RefreshProjectAssets / RebuildProjectAssetCache。
阶段 C：进行中	已完成 xcmat 纹理绑定的 AssetRef + lazy resolve 首轮收口；下一步继续压缩缓存命中后的恢复成本，并检查是否还存在主线程等待点。
阶段 D：最小工具闭环	已完成	已完成 Reimport Selected Asset / Reimport All Assets / Clear Library 正式入口；已补 Project 面板最小导入状态输出；已接入 orphan artifact 清理。

0.2 当前已完成的收口结果（2026-04-03）

• 阶段 A 已完成并验证通过：
  • MeshFilterComponent 对项目 mesh 只序列化 meshRef，meshPath 只保留给 builtin://...
  • MeshRendererComponent 对项目 material 只序列化 materialRefs，materialPaths 只保留给 builtin://...
  • 旧的 mesh= / materials= 兼容读取已移除
  • scene 迁移命令、菜单、report 链路已删除
• 阶段 B 已完成并验证通过：
  • AssetImportService 对外新增 LookupSnapshot、ImportedAsset、GetLibraryRoot()、RebuildLibraryCache()
  • ProjectAssetIndex 不再直接拼装 AssetDatabase 细节，而是只刷新服务快照
  • ResourceManager 不再暴露旧式导入数据库心智，新增 RefreshProjectAssets()、RebuildProjectAssetCache()、GetProjectLibraryRoot()
  • AssetDatabase 初始化后会落盘 ArtifactDB/artifacts.db，使空 Library 结构稳定成型
• 阶段 C 已开始并完成首个子项：
  • Material 纹理绑定新增稳定 AssetRef 元数据，运行时按需把 AssetRef 解析为加载路径
  • xcmat 协议已升级为纹理绑定写入 AssetRef + load path hint
  • AssetDatabase importer version 已提升，旧 material artifact 将自动失效并重建
• 阶段 D 已开始并完成首轮工具口：
  • AssetDatabase 已新增 TryGetImportableResourceType()、ReimportAsset()、ReimportAllAssets()
  • AssetImportService 已新增 ClearLibraryCache()、ReimportAllAssets()、ReimportAsset()
  • ResourceManager 已新增 CanReimportProjectAsset()、ReimportProjectAsset()、ClearProjectLibraryCache()
  • editor Assets 菜单已新增 Reimport Selected Asset、Reimport All Assets、Clear Library
  • AssetImportService 已新增导入状态快照，Project 面板工具栏会显示最近一次导入/清库/清理状态
  • AssetDatabase 已新增 orphan artifact 清理，Refresh / Reimport / 自动重导入 后都会回收未被 ArtifactDB 引用的 Library/Artifacts/* 目录
• 已完成 focused 验证：
  • asset_tests：
    • ResourceManager_Test.ConcurrentAsyncLoadsCoalesceSameMeshPath
    • ResourceManager_Test.AssetLookupFallbackRefreshesSnapshotForNewProjectAsset
    • ProjectAssetIndex_Test.RefreshesSnapshotThroughImportServiceOnCacheMiss
    • AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs
    • ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState
    • AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly
    • AssetImportService_Test.ImportStatusTracksExplicitOperationsAndRefreshCleanup
    • ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath
  • editor_tests：
    • EditorActionRoutingTest.ProjectCommandsExposeAssetCacheMaintenanceActions
    • EditorActionRoutingTest.ProjectCommandsReimportSelectedAssetAndClearLibraryDriveAssetCache
    • EditorActionRoutingTest.ProjectCommandsReportWhenScriptAssembliesCanBeRebuilt
  • components_tests：
    • MeshRendererComponent_Test.SerializeAndDeserializeLoadsProjectMaterialByAssetRef
    • MeshRendererComponent_Test.DeferredSceneDeserializeLoadsProjectMaterialAsync
  • material_tests：46/46 通过
  • mesh_tests：33/33 通过
  • scene_tests：
    • Scene_ProjectSample.DeferredLoadBackpackSceneEventuallyRestoresBackpackMesh
    • Scene_ProjectSample.DeferredLoadBackpackSceneEventuallyProducesVisibleRenderItems
  • XCEditor Release 已成功编译

旧方案文档已经归档到：

• docs/plan/used/Unity式Library资产导入与缓存系统重构方案.md

归档原因很简单：

• 旧文档解决的是“从没有 Library，到建立 Library 基础设施”的问题。
• 现在的问题已经不是“要不要做 Library”，而是“怎么把当前这套半过渡、半正式的实现收成一套干净的正式系统”。

本轮收口以以下前提为准：

• 只服务当前 project 这一个项目。
• 不兼容旧版本 scene / component 资产引用格式。
• 不再提供旧格式迁移工具。
• 可以直接改写 project 下现有场景和资源源文件。
• 目标不是继续堆补丁，而是形成一套边界清晰、行为稳定、可长期维护的正式实现。

---

1. 当前收口基线

当前系统已经具备以下基础，这些不是本轮要推倒重来，而是本轮收口的起点：

• 已有 Unity 风格的 Library 目录结构：
  • Library/SourceAssetDB
  • Library/ArtifactDB
  • Library/Artifacts
• 已有 .meta + AssetGUID 机制，项目资产已经具备稳定身份。
• 已有 AssetRef 结构，运行时已经可以通过 AssetRef 回查项目资产。
• 已有纹理、材质、模型 artifact：
  • xctex
  • xcmat
  • xcmesh
• 已有 AssetImportService，用于承接导入与 artifact 保证逻辑。
• 已有 ProjectAssetIndex，用于承接项目资产路径与 AssetRef 快照索引。
• ResourceManager 已不再直接承担全部导入数据库职责，而是开始回到运行时调度器角色。
• scene 打开链路已经接入 deferred restore，MeshFilterComponent / MeshRendererComponent 能在反序列化后异步恢复项目资源。
• 当前 project/Assets/Scenes/Main.xc、project/Assets/Scenes/Backpack.xc 已经具备 AssetRef 版本数据，可作为最终格式收口的直接修改对象。

当前真正没有收口的，不是“功能不存在”，而是下面这三类问题还在：

• 还保留着旧格式兼容和双写逻辑。
• 组件 / scene / editor 工具链里还残留过渡期代码。
• 材质与贴图恢复仍不够轻，缓存命中后仍有额外同步成本。

---

2. 本轮收口的核心原则

2.1 不保留旧版本兼容

这是本轮与上一轮最大的区别。

本轮明确不做以下事情：

• 不兼容历史 mesh= / materials= 场景字段。
• 不兼容“项目资产仍按普通文件路径序列化”的旧格式。
• 不保留 path + AssetRef 双写作为长期状态。
• 不保留 Migrate Scene AssetRefs 之类的迁移工具与菜单。

允许保留的只有两类稳定引用：

• AssetRef
  • 用于 project/Assets 下的正式项目资产。
• builtin://...
  • 用于内置几何体、内置默认材质等虚拟内置资源。

这里的 builtin:// 不是旧版本兼容，而是引擎内部稳定资源协议，可以继续保留。

2.2 只对当前项目做干净落地

因为当前只服务一个项目，所以这轮不需要为了“以后可能导入旧项目”保留复杂迁移链路。

本轮允许直接做以下事情：

• 直接改写 project/Assets/Scenes/*.xc
• 直接删除旧序列化字段的读写逻辑
• 直接删除旧迁移命令、菜单、报告结构
• 直接调整测试数据到最终格式

2.3 运行时只负责“用缓存”，不负责“解释历史”

收口完成后，运行时层要满足：

• scene 反序列化只恢复最终格式数据
• ResourceManager 只做运行时缓存、异步调度、artifact 读取入口
• 导入与索引职责留在 AssetImportService / ProjectAssetIndex
• 不再在运行时主链路里背负旧协议兼容判断

2.4 收口优先级高于“继续设计更大系统”

本轮目标是把现有系统收干净，不追求继续扩成更庞大的框架。

因此本轮只做两件事：

• 删除过渡态
• 补齐正式版闭环

不在本轮追求：

• prefab 全面资产管线化
• 动画、音频、shader 全类型导入器
• 远程缓存
• 多项目兼容框架
• 一步到位把所有内部类都拆到最细

---

3. 收口后的目标形态

3.1 最终数据协议

收口后，scene / component 的资产引用协议定为：

• 项目 mesh：只写 meshRef
• 项目 material：只写 materialRefs
• 内置 mesh：写 meshPath=builtin://...
• 内置 material：写 materialPaths=builtin://...

不再允许以下状态作为正式协议存在：

• 项目资产依旧只存普通文件路径
• 项目资产同时写路径和 AssetRef
• 反序列化时优先猜测旧字段再兜底

3.2 最终运行时边界

收口后各层职责如下：

• AssetImportService
  • 工程扫描
  • .meta 管理
  • SourceAssetDB / ArtifactDB 维护
  • EnsureArtifact
  • Refresh
  • Reimport / Clear Library 入口
• ProjectAssetIndex
  • 项目资产路径快照
  • AssetRef <-> 项目路径 映射
  • 项目资产查找缓存
• ResourceManager
  • runtime object cache
  • async load coalescing
  • artifact runtime load dispatch
  • deferred scene load 控制
• Component / Scene
  • 只保存最终资产引用
  • 不承担旧协议迁移职责

3.3 最终用户行为

收口后应达到以下体验：

• 第一次导入可能慢，但之后再打开同一个 scene，不应再同步重跑原始 obj/png/jpg 导入。
• 打开含有大型 OBJ 的 scene 时，不应长时间卡死 editor 主窗口。
• 命中 artifact 后，mesh/material 恢复应尽量走异步路径。
• 关闭 editor 再打开后，项目资产引用应稳定恢复，不出现“模型丢失、材质丢失、内置 sphere 丢失”这类状态回退问题。
• 用户能明确知道当前是“命中缓存”还是“正在导入/重建缓存”。

---

4. 本轮必须删除的过渡态

这部分是收口计划的关键，不删掉这些内容，系统就始终处于过渡状态。

4.1 删除旧序列化兼容

目标：

• 删除 MeshFilterComponent 对旧 mesh= 字段的长期兼容读取。
• 删除 MeshRendererComponent 对旧 materials= 字段的长期兼容读取。
• 删除“项目资产 path 与 AssetRef 双写”的长期行为。

允许保留：

• 对 builtin:// 的显式处理。

禁止保留：

• “先读 path，不行再猜 AssetRef”
• “为了兼容老场景继续支持项目文件路径”

4.2 删除场景迁移工具

以下过渡期工具应整体移除：

• Migrate Scene AssetRefs 菜单项
• 对应 action / command / project manager migration report
• 专门为旧场景迁移设计的 editor 流程

原因：

• 当前项目只有一个，已有 scene 可以直接重写。
• 继续保留迁移工具，只会让新系统一直背着旧协议。

4.3 删除长期双轨测试

需要同步清理测试中的过渡态假设：

• 旧格式 scene 兼容测试
• 双写格式测试
• 迁移工具测试

替换成正式版测试：

• 最终 scene 协议测试
• 关闭 editor 重开后的稳定恢复测试
• artifact 命中路径测试
• 异步恢复与渲染可见性测试

---

5. 本轮必须补齐的正式能力

5.1 材质与贴图真正 lazy 化

当前模型 artifact 虽然已经存在，但材质恢复后仍然容易把关联贴图一起拉进来，导致：

• 场景虽然不在反序列化阶段阻塞
• 但资源真正恢复时仍然偏重

本轮必须补齐：

• xcmat 成为正式稳定 artifact
• Material 运行时对象只持有 texture AssetRef
• texture runtime handle 按槽位、按需解析
• mesh 恢复不顺手触发整套材质贴图同步加载

这是“缓存命中了但还是觉得重”的核心收口项。

5.2 明确导入与运行时边界

虽然最近已经引入：

• AssetImportService
• ProjectAssetIndex

但本轮要进一步明确：

• ResourceManager 外部不再暴露旧式导入心智
• 项目资产查找统一经过 ProjectAssetIndex
• artifact 生成统一经过 AssetImportService
• AssetDatabase 作为底层实现细节继续收口到 service 后面

本轮的目标不是一定把 AssetDatabase 拆成三个类，而是先把“对外边界”收干净。

也就是说，本轮要求：

• 类内可暂时还偏胖
• 但对外职责必须已经清晰

5.3 缓存运维闭环

正式版至少要有以下最小运维能力：

• 单资源 Reimport
• Reimport All
• Clear Library
• 项目启动时检查并重建缺失缓存
• 删除源资源后识别 orphan artifact

如果这些没有，系统虽然能工作，但一旦缓存脏掉就难以恢复，仍然不算收口。

5.4 可观测性闭环

本轮至少要做到用户能看见：

• 当前资源是命中 artifact 还是触发重导入
• 正在导入哪个资源
• 导入失败原因
• scene 正在等待哪些资源恢复

不要求本轮先做完整面板，但至少要把日志、状态文案、必要的调试输出整理成稳定可用的最小版本。

---

6. 实施阶段

阶段 A：协议定稿与旧兼容删除

目标

把当前半兼容、半正式的 scene / component 数据协议收成最终格式。

任务

• 改 MeshFilterComponent：
  • 项目资产只写 meshRef
  • 只对 builtin:// 保留 meshPath
  • 删除旧 mesh= 历史兼容读取
• 改 MeshRendererComponent：
  • 项目资产只写 materialRefs
  • 只对 builtin:// 保留 materialPaths
  • 删除旧 materials= 历史兼容读取
• 直接改写 project/Assets/Scenes/Main.xc
• 直接改写 project/Assets/Scenes/Backpack.xc
• 如果项目里还有其他 scene / snapshot / prefab 使用旧项目资产路径，一并直接改成最终格式

同步删除

• Migrate Scene AssetRefs action
• ProjectCommands 中对应 migration command
• ProjectManager 中对应 migration report / migration logic
• 相关测试

阶段完成标准

• 项目场景中不再存在旧项目资产路径协议
• engine/editor 中不再存在迁移工具入口
• 组件反序列化代码只处理最终协议与 builtin 协议

阶段 B：导入与缓存边界收口

目标

让 Library 系统对外呈现为一套明确的正式接口，而不是几个类拼在一起的过渡实现。

任务

• 把项目资产索引访问统一走 ProjectAssetIndex
• 把 artifact 生成与保证统一走 AssetImportService
• 收敛 ResourceManager 中剩余的导入数据库耦合
• 梳理 AssetDatabase 内部接口，限制它作为 service 内部实现使用
• 增加明确的 Refresh / Reimport / Clear Library 入口

阶段完成标准

• editor / runtime 外部调用时，心智模型已经稳定为：
  • 找项目资产：ProjectAssetIndex
  • 产出或校验 artifact：AssetImportService
  • 取 runtime object：ResourceManager

阶段 C：性能闭环

目标

把“看起来已经异步，但恢复仍然偏重”的成本继续压下去。

任务

• 材质贴图 lazy resolve
• 减少 mesh 恢复时顺手加载整套关联资源
• 校验首次导入、二次打开、关闭重开三种路径的时间差异
• 清理仍可能在主线程触发的大锁与同步等待点
• 必要时加入轻量 placeholder / loading state 文案

阶段完成标准

• 含 OBJ 的 scene 再次打开时，editor 主窗口不出现长时间假死
• artifact 命中时恢复成本显著低于首次导入
• 关闭 editor 重开后的恢复链路仍然稳定

阶段 D：最小工具闭环

目标

把这套系统变成“可维护”的，而不是只能靠调试日志救火。

任务

• 已完成：增加 Reimport Asset
• 已完成：增加 Reimport All
• 已完成：增加 Clear Library
• 已完成：增加最小导入状态输出
• 已完成：增加 orphan artifact 清理

阶段完成标准

• 用户可以主动重建缓存
• 缓存脏掉时不需要手工删文件再碰运气
• 导入失败时能直接看到原因

---

7. 验收标准

本轮收口完成，必须同时满足以下条件：

7.1 协议层

• 项目资产引用正式统一为 AssetRef
• 不再保留旧 scene / component 项目资产路径兼容协议
• 不再保留迁移工具

7.2 架构层

• AssetImportService / ProjectAssetIndex / ResourceManager 的对外职责稳定
• 运行时不再承担旧协议解释职责
• Library 已经是正式依赖，而不是临时缓存补丁

7.3 功能层

• OBJ / 贴图 / 材质二次打开优先命中 artifact
• 关闭 editor 重开后项目 scene 能稳定恢复
• builtin sphere / cube / default material 不会因为缓存系统而丢失

7.4 性能层

• 打开含大型 OBJ 的 scene 时不长时间卡死 editor
• 二次打开与首次导入的体感耗时有明显区分
• 命中 artifact 后不再退回源文件同步导入主路径

7.5 工具层

• 具备最小 Reimport / Reimport All / Clear Library 能力
• 有最小可观测性输出

---

8. 本轮不做的内容

为了尽快收口，本轮明确不做以下扩展：

• prefab 全量资产协议翻新
• 动画 / 音频 / shader 新 importer
• 远程缓存
• 多项目历史版本兼容框架
• 完整图形化导入面板
• 一次性把所有 AssetDatabase 内部实现拆到最细

这些内容后续可以继续做，但不应该阻塞当前正式收口。

---

9. 推荐执行顺序

建议按下面顺序推进，避免边做边反复回滚：

1. 先做阶段 A，直接把项目协议和旧兼容删干净。
2. 再做阶段 B，把对外边界稳定下来。
3. 然后做阶段 C，把“缓存命中了但恢复仍然重”的问题收掉。
4. 最后做阶段 D，补齐最小运维与可观测性。

原因是：

• 不先删旧兼容，后面所有逻辑都要双轨维护。
• 不先把边界定清，性能问题会一直和历史兼容问题缠在一起。
• 不先把主链路收稳，工具做出来也只是给过渡态续命。

---

10. 本轮涉及的主要代码范围

本轮预计重点落在以下文件：

• engine/src/Components/MeshFilterComponent.cpp
• engine/src/Components/MeshRendererComponent.cpp
• engine/include/XCEngine/Core/Asset/ResourceManager.h
• engine/src/Core/Asset/ResourceManager.cpp
• engine/include/XCEngine/Core/Asset/AssetImportService.h
• engine/src/Core/Asset/AssetImportService.cpp
• engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h
• engine/src/Core/Asset/ProjectAssetIndex.cpp
• engine/include/XCEngine/Core/Asset/AssetDatabase.h
• engine/src/Core/Asset/AssetDatabase.cpp
• editor/src/Managers/ProjectManager.cpp
• editor/src/Commands/ProjectCommands.h
• editor/src/Actions/EditorActions.h
• editor/src/Actions/MainMenuActionRouter.h
• tests/core/Asset/test_resource_manager.cpp
• tests/Components/test_mesh_render_components.cpp
• tests/Scene/test_scene.cpp
• project/Assets/Scenes/Main.xc
• project/Assets/Scenes/Backpack.xc

---

11. 一句话结论

从这一刻开始，这个模块的目标不再是“继续兼容旧系统”，而是：

把当前已经跑起来的 Library、artifact、AssetRef、异步恢复链路，收成一套只服务当前项目、无旧包袱、可稳定重开的正式资产系统。