xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89590242bd1e5b941a0d7ca32dd767040cdf0a9a
XCEngine/docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md

20 KiB
Raw Blame History

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、异步恢复链路，收成一套只服务当前项目、无旧包袱、可稳定重开的正式资产系统。

Reference in New Issue View Git Blame Copy Permalink