docs: rebuild audio and core api docs

docs/api/_guides/Core/IO/Resource-Paths-Packages-And-Virtual-FileSystem.md

@@ -0,0 +1,127 @@
+# Resource Paths, Packages, And Virtual File System
+
+## 这篇指南解决什么问题
+
+`Core/IO` 这一层看起来像是在做很多事：路径拆分、loader、归档、包文件、虚拟文件系统。单看 API 名称，很容易把它想象成一套已经成熟的商业引擎内容访问系统。
+
+当前源码的真实状态更准确的理解应该是：
+
+- 分层方向已经对了
+- 但只有部分能力进入了可依赖状态
+
+这篇指南的目的，是把这套分层的角色关系和当前可用边界讲清楚。
+
+## 一条更清晰的心智模型
+
+可以把 `Core/IO` 理解成四层：
+
+### 1. 路径字符串层
+
+- [ResourcePath](../../../XCEngine/Core/IO/ResourcePath/ResourcePath.md)
+
+这层只负责路径拆分和 GUID 派生，不负责真实文件系统。
+
+### 2. 格式装载层
+
+- [IResourceLoader](../../../XCEngine/Core/IO/IResourceLoader/IResourceLoader.md)
+
+这层负责把字节数据解释成运行时资源对象，是当前 IO 层最关键、也最实用的一层。
+
+### 3. 容器格式层
+
+- [FileArchive](../../../XCEngine/Core/IO/FileArchive/FileArchive.md)
+- [ResourcePackage](../../../XCEngine/Core/IO/ResourcePackage/ResourcePackage.md)
+
+这层想解决“资源是否来自目录、归档或打包文件”的问题。
+
+### 4. 虚拟文件系统层
+
+- [ResourceFileSystem](../../../XCEngine/Core/IO/ResourceFileSystem/ResourceFileSystem.md)
+
+这层试图把前面几种来源统一起来，让上层按相对资源路径访问内容。
+
+## 为什么商业引擎都喜欢这么分
+
+因为资源系统最终总要面对这些现实问题：
+
+- 开发阶段想直接读散文件
+- 发行阶段想改成打包格式
+- patch 阶段想叠加新的挂载点
+- loader 不想关心内容来自真实目录还是包文件
+
+把路径、容器、加载器和虚拟文件系统拆开，后续替换任何一层都更容易。这也是这套结构本身的价值。
+
+## 当前最可靠的使用路径
+
+按当前实现，最可靠的路径其实不是包文件或虚拟文件系统，而是：
+
+1. 用 [ResourcePath](../../../XCEngine/Core/IO/ResourcePath/ResourcePath.md) 做轻量路径拆分
+2. 用具体 loader 实现 [IResourceLoader](../../../XCEngine/Core/IO/IResourceLoader/IResourceLoader.md)
+3. 通过 [ResourceManager](../../../XCEngine/Core/Asset/ResourceManager/ResourceManager.md) 做同步 `Load<T>()`
+
+这条路径已经是当前资源系统最接近可依赖运行时通路的部分。
+
+## 当前必须知道的几个差异点
+
+### 1. 路径扩展名约定不统一
+
+- `ResourcePath::GetExtension()` 返回 `.png`
+- `IResourceLoader::GetExtension()` 返回 `png`
+
+这不是文档风格问题，而是源码里的真实差异。写 loader 或做路径判断时，必须先确认自己用的是哪一套约定。
+
+### 2. `ResourcePath` 不是标准化路径工具
+
+它不会：
+
+- 折叠 `.` / `..`
+- 统一大小写
+- 做绝对路径解析
+- 检查目标是否存在
+
+所以它更像字符串助手，不像 `std::filesystem::path` 的资源版替代。
+
+### 3. `FileArchive` 现在更像目录适配器
+
+它并不会真的解析归档格式，而是把“archive path + relative path”拼起来直接读普通文件。
+
+### 4. `ResourcePackage` 还不能当发布格式闭环
+
+builder 和 reader 当前没有形成可靠闭环。现在去依赖它做正式资源打包，会碰到 manifest 缺失、条目为空、读回失败这类问题。
+
+### 5. `ResourceFileSystem` 还不是成熟 VFS
+
+按当前实现：
+
+- `AddArchive()` 没有真正挂载 archive 对象
+- `Exists()` 可能对不存在文件返回 true
+- `ReadResource()` 和 `GetResourceInfo()` 还有自死锁风险
+
+所以它目前更像 VFS 架构草图，而不是已完成的运行时文件系统。
+
+## 和 Unity 风格概念的关系
+
+如果一定要做类比，这一层更接近：
+
+- Unity 运行时内容读取层
+- `StreamingAssets`、资源包和内部 loader 之间的底层桥接
+
+它并不等价于 Unity `AssetDatabase`。`AssetDatabase` 是编辑器资产数据库和导入管线入口，而这里更多是运行时访问层的骨架。
+
+## 推荐使用建议
+
+- 目前优先把 `Core/IO` 当成“loader 支撑层”，而不是“成熟打包与 VFS 层”。
+- 写 loader 时先统一扩展名格式约定，避免一边带点一边不带点。
+- 用 `ResourcePath` 做拆分，不要把它当成路径规范化器。
+- 在正式依赖 `ResourceFileSystem` 之前，先补上真实存在性检查和重复加锁问题。
+- 在正式依赖 `ResourcePackage` 之前，先补完 manifest 写入和读取闭环。
+
+## 相关 API
+
+- [IO](../../../XCEngine/Core/IO/IO.md)
+- [ResourcePath](../../../XCEngine/Core/IO/ResourcePath/ResourcePath.md)
+- [IResourceLoader](../../../XCEngine/Core/IO/IResourceLoader/IResourceLoader.md)
+- [FileArchive](../../../XCEngine/Core/IO/FileArchive/FileArchive.md)
+- [ResourcePackage](../../../XCEngine/Core/IO/ResourcePackage/ResourcePackage.md)
+- [ResourceFileSystem](../../../XCEngine/Core/IO/ResourceFileSystem/ResourceFileSystem.md)
+- [Asset](../../../XCEngine/Core/Asset/Asset.md)