docs: rebuild audio and core api docs

docs/api/_guides/Core/Containers/Custom-Containers-Value-Semantics-And-Interop.md

@@ -0,0 +1,101 @@
+# Custom Containers, Value Semantics, And Interop
+
+## 这篇指南解决什么问题
+
+引擎为什么要有自己的 `String`、`Array`、`HashMap`，而不是直接把 `std::string`、`std::vector`、`std::unordered_map` 到处公开出去？以及，当前这套容器做到哪一步了，哪些地方还不能按标准库直觉来用？
+
+这篇指南就是回答这两个问题。
+
+## 为什么商业引擎常有自己的基础容器
+
+这不是单纯为了“重写一遍标准库”，而是因为引擎公共 API 通常希望控制几件事：
+
+- 跨模块接口的类型统一
+- 未来 allocator / profiler / serializer 的接入位置
+- 平台边界和 ABI 风险
+- 调试、日志、反射系统里的统一数据形状
+
+所以保留一层自定义容器，在商业引擎里是很常见的做法。
+
+## XCEngine 当前这层的定位
+
+按当前源码，`Core/Containers` 更准确的定位是：
+
+- 一组轻量、可用、值语义优先的基础容器
+- 不是完整 STL 等价层
+
+这一点很重要，因为如果你用标准库心智模型去要求它们的全部边界行为，很容易踩到当前实现差异。
+
+## 三个核心类型怎么理解
+
+### `String`
+
+- 适合做引擎公共接口里的文本参数和返回值
+- 当前是堆分配可变字符串
+- 支持基本拼接、截取、大小写与前后缀判断
+
+它最像轻量版 `std::string`，但不提供小字符串优化，也不是完整字符语义库。
+
+### `Array<T>`
+
+- 适合做“由当前对象拥有的一段有序元素”
+- 当前最接近 `std::vector<T>`
+- 支持顺序存储和基本扩容
+
+它适合当默认顺序容器，但当前不要拿它去承载太复杂的 move-only / allocator-heavy 场景。
+
+### `HashMap<Key, Value>`
+
+- 适合做键到值的快速查找
+- 和 `String` 配合很好，因为已有 `std::hash<String>` 特化
+- 当前更适合查找用途，不适合依赖成熟迭代器语义
+
+## 当前最重要的实践建议
+
+### 1. 把它们当值类型，不要脑补共享所有权
+
+这套容器默认都是值语义设计。拷贝意味着复制内容，移动意味着转移底层缓冲。
+
+### 2. 不要过度相信 allocator 钩子已经接通
+
+`Array::SetAllocator()` 和 `HashMap::SetAllocator()` 当前只是保存指针，底层实际分配仍然走默认路径。
+
+也就是说，当前不要把这两个接口当成“已经接入商业级内存系统”的保证。
+
+### 3. `HashMap` 现在优先拿来查，不要拿来遍历
+
+`Find()`、`Contains()`、`Insert()` 是当前相对可靠的主路径。
+
+`begin()` / `end()` 还不是完整整表迭代语义，先不要把它当标准关联容器使用。
+
+### 4. `Array<T>` 目前更适合 copy-friendly 类型
+
+因为扩容时当前实现是拷贝迁移，不是优先移动迁移，所以它对 move-only 类型并不友好。
+
+### 5. moved-from `String` 不要继续当空字符串用
+
+当前 move 之后源对象的 `m_data` 会变成 `nullptr`。析构和赋值没问题，但不应依赖它继续像普通空字符串那样工作。
+
+## 和 Unity / 商业引擎思路的关系
+
+如果做类比，这层更像商业引擎里的“Core Foundation Containers”：
+
+- 它不是玩法层 API
+- 也不是高层资源系统
+- 它是所有模块共同依赖的一层基础契约
+
+这种层一旦稳定下来，收益非常大，因为更上层的日志、资源、序列化、编辑器和运行时系统都能共享同一套容器约定。
+
+## 当前应该怎么用
+
+- 公共接口里的字符串优先使用 [String](../../../XCEngine/Core/Containers/String/String.md)
+- 顺序容器优先使用 [Array](../../../XCEngine/Core/Containers/Array/Array.md)
+- 查找表可用 [HashMap](../../../XCEngine/Core/Containers/HashMap/HashMap.md)，但当前避免依赖整表迭代
+- 如果你真的需要成熟 allocator 接入、复杂异常安全或完整 STL 语义，先确认当前实现是否已经覆盖
+
+## 相关 API
+
+- [Containers](../../../XCEngine/Core/Containers/Containers.md)
+- [String](../../../XCEngine/Core/Containers/String/String.md)
+- [Array](../../../XCEngine/Core/Containers/Array/Array.md)
+- [HashMap](../../../XCEngine/Core/Containers/HashMap/HashMap.md)