XCEngine/docs/used/Library统一Artifact容器与多后端Shader缓存重构计划_阶段归档_2026-04-11.md

Library 统一 Artifact 容器与多后端 Shader 缓存重构计划

日期：2026-04-11

0. 当前执行状态（2026-04-11 更新）

当前整体进度：约 88%

已完成：

1. ArtifactContainer 读写、校验、虚拟 entry path 已落地，并有核心单测覆盖。
2. ShaderCompilationCache 已正式进入 Library 体系，D3D12 已有稳定命中路径与单测覆盖。
3. Texture / Material / Shader / Model / Volume / GaussianSplat 已切到单文件 artifact container 写入与读取语义。
4. Model 子资源已从真实 sibling 文件切到 container entry，AssetDatabase 子资源解析优先走 entry 解析。
5. XCUI 文档 artifact 也已补齐为单文件 container，避免 Library 内继续残留旧式 artifact directory 生产路径。
6. 新格式写入路径已经统一到 Library/Artifacts/<shard>/<artifactKey>.<ext>，旧格式保持读取兼容。
7. artifact_inspect 已落地，可直接查看 container entry 列表并导出指定 entry payload。

已验证：

1. ArtifactContainer.*
2. ShaderCompilationCache.*
3. TextureLoader 关键 artifact 回归
4. MaterialLoader 关键 artifact / reimport 回归
5. ShaderLoader 关键 artifact / dependency 回归
6. ModelLoader / ModelImportPipeline / MeshLoader 关键 container-entry 回归
7. VolumeFieldLoader 关键 artifact 回归
8. GaussianSplatLoader.*
9. UIDocumentLoader.*
10. UISchemaDocument.*

尚未收口：

1. ArtifactDB 还没有彻底升级到“显式 entry 元数据” schema，当前仍保留一部分旧字段语义用于兼容迁移。
2. Library 清理工具、最终性能报告、旧格式彻底收口文档还没完成。
3. Vulkan / OpenGL 目前已经接入统一 shader cache 框架边界，但还没有做到和 D3D12 同等级的完整产物复用能力。

1. 文档定位

这份计划不是在讨论“把 Library/Artifacts 的目录名字改得更像 Unity”。

这份计划要解决的是更底层的问题：

1. 现在的 artifact 基本存储单位是“一个目录 + 多个真实文件”，不是“一个统一工件”。
2. 复杂资源类型一增加，导入器、加载器、子资源解析、测试都会继续把这种多文件假设扩散到更多模块。
3. shader 运行时编译缓存虽然已经开始建立，但还没有上升为整个 Library 体系中的正式基础设施。

因此，本计划的目标是正式把 Library 重构为一套统一的缓存架构：

1. 导入产物统一落成单文件 artifact container。
2. 子资源从“磁盘上的 sibling 文件”变成“artifact 内部 entry”。
3. shader 编译产物纳入 Library 正式缓存体系，并支持多后端。
4. 整个系统继续保留现有 AssetDatabase / ResourceManager / ArtifactDB 的架构思路，不搞一套平行新系统。

---

2. 当前状态与根本问题

2.1 当前已经成立的基础

目前 Library 体系已经具备以下基础能力：

1. assets.db 与 artifacts.db 已经位于 Library 根目录。
2. AssetDatabase 已经负责 source asset 扫描、依赖签名、artifact 复用和重导。
3. 各资源导入器已经能够把 source asset 写入 artifact。
4. shader 编译缓存已经有初步命中机制，且收益已经被实际验证过。

2.2 当前真正的问题

当前问题不在于“有没有缓存”，而在于“缓存的基本抽象还不够统一”。

以模型为例，当前一个导入结果并不是一个真正的工件，而是一整个目录：

1. main.xcmodel
2. mesh_0.xcmesh
3. material_0.xcmat
4. texture_0.xctex
5. subassets.tsv

这意味着：

1. artifact 的语义是“目录”，不是“文件”。
2. loader 和测试可以直接依赖某个 sibling 文件的真实路径。
3. 子资源关系是通过外部文件名和外部 manifest 维持的。
4. 新增资源类型时，导入器很容易继续沿用“往 artifact 目录里再塞几个文件”的模式。

2.3 为什么这个问题越晚改越难

随着资源类型增加，当前模式会继续扩散到：

1. Model
2. Shader
3. Volume
4. GaussianSplat
5. 未来的 AnimationClip / Skeleton / Audio / VFX / Prefab-like Asset

越往后，耦合会越来越深：

1. 更多 importer 会直接生成多个磁盘文件。
2. 更多 loader 会默认自己拿到的就是磁盘路径。
3. 更多测试会把 artifact 文件名结构视为系统契约。
4. 后面再做统一 container 时，每种资源都要单独回迁一次。

所以这次重构如果要做，越早越值。

---

3. 重构目标

本轮重构的最终目标如下：

1. Library 中“一个 artifactKey 对应一个单文件 container”。
2. artifact container 内部可以保存主资源和多个子资源 entry。
3. ArtifactDB 记录的是“工件文件 + 条目索引信息”，不再把目录结构当成核心语义。
4. loader 不再依赖 sibling 文件真实存在，而是通过 container entry 加载。
5. shader 编译缓存成为正式的 Library 子系统，支持 D3D12 / Vulkan / OpenGL 多后端扩展。
6. 老项目和旧 Library 尽量兼容迁移，避免一次性炸库。

---

4. 核心架构决策

4.1 一个 artifact 必须变成一个单文件 container

正式改为：

1. 一个 artifactKey 只对应一个 artifact 文件。
2. artifact 文件内部包含 header、目录表、entry 表、payload 区。
3. entry 可以表达：
   • main asset
   • subasset
   • import metadata
   • dependency snapshot
   • debug manifest

建议目标形态：

1. Library/Artifacts/07/071822a133c727103210833b93d2b846.xca
2. 或保留无扩展 hash 文件形式，但内部仍然是统一 container

这里更重要的是“单文件容器语义”，不是扩展名本身。

4.2 子资源必须从真实文件变成逻辑 entry

当前的：

1. mesh_0.xcmesh
2. material_0.xcmat
3. texture_0.xctex
4. subassets.tsv

后续都不再作为 artifact 目录中的真实文件暴露。

改为：

1. container entry main
2. container entry mesh/0
3. container entry material/0
4. container entry texture/0
5. container entry manifest/subassets

这样做的目的不是“隐藏文件”，而是统一系统抽象：

1. importer 只负责产出 entry。
2. loader 只负责按 entry 解析。
3. 外部磁盘布局不再影响运行时语义。

4.3 ArtifactDB 只维护工件语义，不维护目录语义

ArtifactDB 需要从当前的字段语义升级为：

1. artifactKey
2. artifactPath
3. artifactFormatVersion
4. mainEntryId
5. resourceType
6. dependencySignature
7. sourceHash / metaHash / importerVersion
8. 可选的 subasset index snapshot

不再把下列内容作为核心前提：

1. artifactDirectory
2. mainArtifactPath 必须是磁盘上的某个独立 sibling 文件

4.4 Shader 编译缓存必须纳入 Library 正式体系

shader 编译缓存不能继续以“某个功能修复补丁”的方式存在，必须被定义为 Library 正式缓存层的一部分。

正式目标：

1. 以编译 key 唯一标识一份 shader bytecode / program binary。
2. 编译 key 必须包含：
   • shader 源文件签名
   • include 依赖签名
   • keyword / variant 宏
   • backend 类型
   • compiler 类型与版本
   • profile / entry point
   • 相关编译选项
3. 多后端共用同一套 key 生成规则和缓存查询流程。
4. 后端各自写入自己的 payload，不共享错误的二进制格式。

4.5 必须坚持“统一接口，多后端实现”

这次重构不能只为 D3D12 做一套临时特化路径。

必须采用：

1. 上层统一的 ShaderCompilationCache 接口
2. 后端相关的 key 参与规则
3. 后端相关的 payload 类型
4. 后端相关的反序列化逻辑

这样后面：

1. D3D12 存 DXIL / DXBC
2. Vulkan 存 SPIR-V
3. OpenGL 可以先存 source variant 或 program binary capability 结果

都能挂到同一架构下，而不是分裂成三套缓存系统。

---

5. 目标目录与数据布局

5.1 Library 根目录

建议最终保留如下根层文件：

1. Library/assets.db
2. Library/artifacts.db
3. Library/shadercache.db
4. Library/assets.db.tmp/.bak/.lock
5. Library/artifacts.db.tmp/.bak/.lock
6. Library/shadercache.db.tmp/.bak/.lock

说明：

1. 单文件数据库应放在 Library 根目录，不再额外套目录。
2. .tmp/.bak/.lock 是数据库运行期一致性与恢复所需的辅助文件，属于正常成本，应保留。

5.2 Artifact 内容目录

建议统一为：

1. Library/Artifacts/<2-hex-shard>/<artifactKey>.xca

说明：

1. 仍然保留分片目录，避免单目录堆积过多文件。
2. 从“目录工件”改为“单文件工件”。
3. 这里已经足够接近 Unity 的外观，但关键收益来自统一 container，不来自“像 Unity”本身。

5.3 Shader 编译缓存目录

建议使用：

1. Library/ShaderCache/<backend>/<2-hex-shard>/<compileKey>.xcbc

说明：

1. 这是运行时编译产物，不建议和 source artifact 混在同一目录。
2. 它本质上也是缓存工件，但生命周期和失效条件不同。
3. 数据库仍然在根目录，二进制 payload 用分片目录管理。

---

6. Artifact Container 格式设计

6.1 容器最小结构

每个 .xca 至少包含：

1. 文件头
2. 格式版本
3. 工件类型
4. entry 数量
5. entry 目录表
6. payload 区
7. 校验信息

6.2 Entry 元信息

每个 entry 需要至少记录：

1. entryId
2. entryName
3. resourceType
4. localID
5. offset
6. size
7. compression
8. flags

6.3 Manifest 内置化

原本外置的：

1. subassets.tsv

后续变为：

1. container 内置 manifest entry
2. 或者直接由 entry table 本身承担 manifest 作用

原则是：

1. 子资源映射不能再依赖工件目录里的额外文本文件。

6.4 调试能力不能丢

虽然外部从多文件变成单文件，但不能把可调试性彻底丢掉。

因此建议提供：

1. debug dump 工具
2. artifact inspect 命令
3. container 列表查看能力
4. 按需导出某个 entry 的开发期工具

这样能避免后续排障时变成纯黑盒。

---

7. 对导入链路的改造要求

7.1 Importer 层统一改为“写 entry”

各 importer 不再自己决定在 artifact 目录里创建几个文件。

统一改为：

1. importer 构建内存中的 artifact package
2. 向 package 写入 main entry
3. 按需写入 subasset entry
4. 由统一 ArtifactWriter 一次性落成单文件

7.2 各类资源的落地规则

建议采用如下规则：

1. Texture
   • 通常一个 main entry 即可
2. Material
   • 通常一个 main entry 即可
3. Shader
   • 主 entry + 变体元数据 entry + 预编译记录 entry
4. Model
   • 主 model entry + mesh/material/texture subasset entries
5. Volume
   • 主 volume entry + 可选页表/brick 元数据 entry
6. GaussianSplat
   • 主 splat entry + 索引/排序辅助元数据 entry

7.3 导入器必须停止暴露真实 sibling 文件路径

后续 importer 不应再让外部系统依赖：

1. mesh_0.xcmesh
2. material_3.xcmat
3. texture_1.xctex

如果某处仍然需要这种路径式访问，只能通过兼容层临时桥接，不能作为新架构继续扩散。

---

8. 对加载链路的改造要求

8.1 Loader 必须从“读文件路径”改成“读 artifact entry”

未来 loader 的输入应逐步变为：

1. artifact 文件路径
2. entry id / local id / entry name

而不是：

1. 一个已经存在于磁盘上的子文件路径

8.2 ResourceManager / AssetDatabase 需要新增解析能力

需要正式提供：

1. ResolveMainArtifactEntry(...)
2. ResolveSubAssetEntry(...)
3. OpenArtifactContainer(...)
4. LoadResourceFromArtifactEntry(...)

这样 AssetDatabase 和 ResourceManager 就能以“工件条目”作为统一边界。

8.3 允许阶段性兼容旧式 Loader

为了降低一次性改造风险，允许在迁移阶段存在：

1. 新容器 loader
2. 旧文件路径 loader

但要求：

1. 新导入默认只产出新容器
2. 旧 loader 仅承担读旧缓存或读测试基线的过渡职责
3. 最终必须收口到容器 entry 模型

---

9. Shader 编译缓存设计

9.1 目标

shader 缓存系统要解决三件事：

1. 避免同一 shader variant 在同一 backend 上反复现场编译
2. 避免 editor 启动时因大批 shader 同步编译造成长时间卡顿
3. 把编译结果纳入 Library 生命周期管理，而不是散落在临时模块里

9.2 Shader 缓存分层

建议分成两层：

1. Shader Artifact
   • 记录 shader 源资源、变体定义、依赖签名、反射元数据
2. Shader Bytecode Cache
   • 记录某 backend、某 profile、某 variant 的实际编译产物

这样做的原因是：

1. shader 资源本身是 source artifact 的一部分
2. 字节码则是“shader artifact 在某后端上的派生产物”

9.3 多后端适配策略

必须从一开始就定义好多后端字段：

1. backend = D3D12 / Vulkan / OpenGL
2. compiler = DXC / glslang / driver / other
3. profile = ps_6_0 / vs_6_0 / spirv-vulkan1.2 / glsl-450
4. bytecodeFormat = DXIL / SPIRV / GL_PROGRAM_BINARY / SOURCE_FALLBACK

9.4 OpenGL 的现实处理

OpenGL 不一定能像 D3D12 一样稳定落真正可移植字节码，因此计划要区分：

1. 理想路径：驱动支持 program binary，可缓存 program binary
2. 保守路径：缓存预处理后的 shader source / variant expansion 结果
3. 最低保证：即使不能完全复用最终 program，也要复用前置预处理和 variant 展开结果

也就是说，多后端适配不等于三端完全同构，而是统一框架下允许 payload 能力不同。

---

10. 迁移策略

10.1 不能一次性硬切

因为当前项目已经存在：

1. 老 Library
2. 老 artifact 目录结构
3. 依赖老结构的 loader
4. 依赖老结构的测试

所以必须采用兼容迁移。

10.2 建议迁移阶段

阶段 A：底层能力先落地

1. 新增 ArtifactContainerReader/Writer
2. 新增 container format version
3. 新增 ShaderCompilationCache 正式接口
4. 新增调试工具和 dump 工具

阶段 B：数据库与解析接口升级

1. ArtifactDB 加入新字段
2. AssetDatabase 提供 entry 级解析
3. ResourceManager 能按 entry 加载

阶段 C：先迁移低复杂度资源

1. Texture
2. Material
3. Shader

原因：

1. 这三类资源 entry 结构简单
2. 容器化收益直接
3. 风险比 Model 低

阶段 D：迁移复杂资源

1. Model
2. Volume
3. GaussianSplat

这里才是这次重构的真正硬骨头。

阶段 E：兼容收口

1. 新导入全面只写新 container
2. 老 artifact 仅保留读取兼容
3. 清理临时桥接路径
4. 测试与工具全部对齐新语义

10.3 旧缓存处理策略

建议采用：

1. 读旧、写新
2. 命中新格式则直接用
3. 命中旧格式则读取并标记可重导
4. 必要时提供“一键清空旧缓存并全量重导”入口

---

11. 分阶段执行计划

Phase 1：方案冻结与底层抽象

目标：

1. 冻结 artifact container 格式
2. 冻结 shader compile key 规则
3. 冻结 ArtifactDB 新字段语义

交付物：

1. ArtifactContainer 设计文档
2. ShaderCompilationCache 设计文档
3. Library 目录与文件命名规范

验收：

1. 所有核心模块对新名词和新边界达成一致
2. 不再新增基于目录 sibling 文件的新逻辑

Phase 2：容器读写基础设施

目标：

1. 写出可工作的 .xca 读写器
2. 写出 entry table、payload、校验、版本管理

交付物：

1. ArtifactContainerWriter
2. ArtifactContainerReader
3. artifact inspect / dump 工具
4. 单元测试

验收：

1. 可写入多个 entry
2. 可随机读取指定 entry
3. 可检测格式版本与损坏文件

Phase 3：数据库与资源解析升级

目标：

1. 让 AssetDatabase 和 ResourceManager 理解 entry 语义

交付物：

1. ArtifactDB schema 升级
2. entry 级 resolve API
3. 新旧格式兼容查询路径

验收：

1. 不依赖真实 sibling 文件也能定位主资源和子资源
2. 旧缓存仍可读

Phase 4：Shader 缓存正式化

目标：

1. 把 shader 编译缓存正式接入 Library
2. 打通多后端 key 体系

交付物：

1. shadercache.db
2. Library/ShaderCache/...
3. D3D12 正式字节码缓存
4. Vulkan/OpenGL 占位与接口接入
5. 计时日志、命中日志、失效日志

验收：

1. D3D12 重启 editor 后能稳定命中缓存
2. shader compile log 能明确区分 cache hit / miss
3. Vulkan/OpenGL 不破坏接口一致性

Phase 5：低复杂度资源迁移

目标：

1. 先迁移 Texture / Material / Shader

交付物：

1. 新 importer 写 container
2. 新 loader 读 container
3. 旧逻辑兼容桥接

验收：

1. 三类资源脱离目录式 artifact
2. 现有测试通过

Phase 6：复杂资源迁移

目标：

1. 迁移 Model / Volume / GaussianSplat

交付物：

1. Model 子资源 entry 化
2. Volume 复杂数据 entry 化
3. GaussianSplat 复杂数据 entry 化
4. 新的 subasset resolve 机制

验收：

1. 不再需要 subassets.tsv
2. 不再依赖 mesh_0.xcmesh/material_0.xcmat/... 真实文件
3. 场景加载、运行时 streaming、编辑器选择与重载行为正常

Phase 7：兼容收口与库清理

目标：

1. 清理临时桥接逻辑
2. 完成旧格式收口

交付物：

1. 旧 artifact 兼容策略文档
2. Library 清理工具
3. 最终回归测试与性能报告

验收：

1. 新项目默认只产生新格式
2. 旧项目迁移路径明确
3. 文档、测试、工具全部收口

---

12. 风险评估

12.1 高风险点

1. Model 子资源引用路径改造
2. 旧 loader 和新 loader 并存期间的行为分叉
3. ArtifactDB schema 迁移
4. shader 缓存 key 设计不完整导致误命中或漏命中
5. OpenGL 后端缓存能力不如 D3D12/Vulkan 稳定

12.2 主要回归风险

1. 资源重复导入
2. 子资源引用失效
3. 重启后缓存不命中
4. editor 启动时再次出现同步长阻塞
5. 清理 Library 后行为和旧项目不一致

12.3 风险控制原则

1. 每种资源类型单独迁移、单独验收
2. 每阶段都保留明确日志
3. 优先做“读旧写新”，不要先做“只认新格式”
4. 性能优化必须建立在日志可证伪的基础上，不能靠感觉判断

---

13. 验收标准

重构完成后，应满足以下标准：

1. Library/Artifacts 中一个 artifactKey 对应一个单文件 container。
2. assets.db / artifacts.db / shadercache.db 位于 Library 根目录。
3. Texture / Material / Shader / Model / Volume / GaussianSplat 都能通过统一 container 读写。
4. 新增资源类型时，不需要再发明“这个类型自己往 artifact 目录塞几个文件”的模式。
5. shader 缓存在 D3D12 上稳定命中，Vulkan / OpenGL 具备同框架下的扩展位。
6. editor 启动和场景 ready 时间相较当前基线有可测收益。
7. 调试工具可以查看 container 内部 entry，不会因为单文件化而失去排障能力。

---

14. 本计划明确不做的事情

本计划不做以下偏题内容：

1. 为了“长得像 Unity”而做无意义目录重命名
2. 把所有缓存强行塞进一个数据库 blob 字段里
3. 为了单文件化而牺牲调试能力
4. 只做 D3D12 特化、把其他后端晾着不管
5. 一次性删掉旧 Library 兼容路径

---

15. 推荐执行顺序

建议严格按下面顺序推进：

1. 先冻结 container 格式和 shader key 规则
2. 再做底层 reader/writer 与数据库升级
3. 先迁移 Texture / Material / Shader
4. 再迁移 Model / Volume / GaussianSplat
5. 最后做兼容收口、清理和性能复盘

这条顺序的原因很简单：

1. 先做底层，后续每种资源都能复用
2. 先啃简单资源，能尽快验证架构不是错的
3. 把最难的复杂资源放在基础设施稳定之后处理，整体风险最低

---

16. 最终判断

这个重构的代价不小，但如果项目接下来还会持续扩展资源类型，那么它属于“越早做越划算”的长期基础设施工程。

真正值得做的不是把目录外观改得像 Unity，而是：

1. 统一 artifact 的存储模型
2. 统一子资源的表达方式
3. 统一 shader 编译缓存的 Library 化管理
4. 统一多后端的缓存接口

只要这四件事做对了，后面资源类型再增加，系统复杂度才不会继续失控。