docs: rebuild audio and core api docs

docs/api/XCEngine/Core/SmartPtr/SmartPtr.md

@@ -1,18 +1,88 @@
 # SmartPtr
 
-**命名空间**: `XCEngine`
+**命名空间**: `XCEngine::Core`
 
-**类型**: `header`
+**类型**: `header-overview`
 
 **头文件**: `XCEngine/Core/SmartPtr.h`
 
-**描述**: 定义 `XCEngine/Core` 子目录中的 `SmartPtr` public API。
+**描述**: 定义 `std::shared_ptr` / `std::unique_ptr` 的引擎内别名，以及 `MakeRef()` / `MakeUnique()` 工厂函数。
 
-## 概述
+## 角色概述
 
-`SmartPtr.h` 是 `XCEngine/Core` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`SmartPtr.h` 是当前代码库里最直接、也最现代的一层所有权约定：
+
+- `Ref<T>` = `std::shared_ptr<T>`
+- `UniqueRef<T>` = `std::unique_ptr<T>`
+- `MakeRef<T>()` = `std::make_shared<T>()`
+- `MakeUnique<T>()` = `std::make_unique<T>()`
+
+这让代码在保持引擎命名风格的同时，仍然直接复用标准库语义。
+
+## 当前实现行为
+
+### 1. 这是薄封装，不是自定义智能指针系统
+
+当前头文件里没有自定义控制块、intrusive hook、调试统计或特殊 deleter 逻辑。它只是别名与便捷工厂函数。
+
+这意味着：
+
+- `Ref<T>` 的行为完全等同 `std::shared_ptr<T>`
+- `UniqueRef<T>` 的行为完全等同 `std::unique_ptr<T>`
+
+### 2. `MakeRef()` / `MakeUnique()` 只是便捷入口
+
+当前实现直接转发到标准库：
+
+- `MakeRef()` -> `std::make_shared`
+- `MakeUnique()` -> `std::make_unique`
+
+`tests/core/test_core.cpp` 已覆盖：
+
+- 默认构造
+- 拷贝共享
+- 移动语义
+- `nullptr` 检查
+
+### 3. 已有真实调用点
+
+当前源码里至少能看到：
+
+- `ResourceManager` 使用 `Core::MakeUnique<AsyncLoader>()`
+
+这说明它不是纯风格占位，而是已经进入实际实现。
+
+## 与 RefCounted 的关系
+
+这是这个头文件最容易被误解的地方。
+
+当前 [RefCounted](../RefCounted/RefCounted.md) 是侵入式手工引用计数基类，而 `Ref<T>` 是标准库 `shared_ptr`。两者当前没有自动打通。
+
+最安全的理解方式是：
+
+- `Ref<T>` / `UniqueRef<T>` 是当前更常规的 C++ RAII 工具
+- `RefCounted` 是单独存在的一套 intrusive RC 机制
+
+如果没有明确适配层，不要把继承自 `RefCounted` 的对象直接当成 `Ref<T>` 体系的一部分来想当然混用。
+
+## 线程语义
+
+- 线程语义沿用标准库智能指针本身的语义。
+- 文档不额外扩展任何引擎层线程保证。
+
+## 当前实现限制
+
+- 没有自定义内存统计、调试名或对象池集成。
+- 没有和 `RefCounted` 的统一 ownership 框架。
+- 头文件本身不提供额外行为，只提供命名和风格统一。
+
+## 相关指南
+
+- [Core Foundations: Ownership, Events, And Layers](../../../_guides/Core/Core-Foundations-Ownership-Events-And-Layers.md)
 
 ## 相关文档
 
-- [当前目录](../Core.md) - 返回 `Core` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Core.md)
+- [RefCounted](../RefCounted/RefCounted.md)
+- [Types](../Types/Types.md)
+- [API 总索引](../../../main.md)