fix: improve doc link navigation and tree display

- Fix link resolution with proper relative/absolute path handling
- Improve link styling with underline decoration
- Hide leaf nodes from tree, only show directories
- Fix log file path for packaged app

docs/api/memory/allocator/allocate.md

@@ -0,0 +1,38 @@
+# IAllocator::Allocate
+
+```cpp
+virtual void* Allocate(size_t size, size_t alignment = 0) = 0;
+```
+
+从分配器请求指定大小的内存块。如果 `alignment` 大于 0，则返回的地址将按该对齐值对齐。分配成功时返回有效指针，失败时返回 `nullptr` 或抛出异常（取决于具体实现）。
+
+**参数：**
+- `size` - 请求的字节数
+- `alignment` - 内存对齐要求，默认为 0（表示使用实现默认对齐）
+
+**返回：** 分配成功返回已分配内存块的指针，失败返回 `nullptr`
+
+**复杂度：** O(1)（固定块分配器）或 O(n)（需要搜索合适大小的块）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        // 使用系统 new 分配
+        return ::operator new(size);
+    }
+    // ... 其他方法实现
+};
+
+MyAllocator alloc;
+void* ptr = alloc.Allocate(256);      // 分配 256 字节
+void* aligned = alloc.Allocate(64, 16); // 分配 64 字节，16 字节对齐
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/allocator.md

@@ -0,0 +1,72 @@
+# IAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class` (abstract interface)
+
+**描述**: 内存分配器抽象接口，定义标准分配协议。
+
+## 概述
+
+`IAllocator` 是 XCEngine 内存管理系统的核心抽象接口。它定义了分配、释放和重新分配内存的标准方法，以及内存统计接口。所有专用分配器（LinearAllocator、PoolAllocator、ProxyAllocator）都实现此接口。
+
+## 公共方法
+
+### 内存操作
+
+| 方法 | 描述 |
+|------|------|
+| `Allocate` | 分配内存 |
+| `Free` | 释放内存 |
+| `Reallocate` | 重新分配内存 |
+
+### 统计信息
+
+| 方法 | 描述 |
+|------|------|
+| `GetTotalAllocated` | 获取已分配总字节数 |
+| `GetTotalFreed` | 获取已释放总字节数 |
+| `GetPeakAllocated` | 获取峰值分配字节数 |
+| `GetAllocationCount` | 获取分配次数 |
+
+### 元信息
+
+| 方法 | 描述 |
+|------|------|
+| `GetName` | 获取分配器名称 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        return ::operator new(size);
+    }
+    
+    void Free(void* ptr) override {
+        ::operator delete(ptr);
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override {
+        void* newPtr = Allocate(newSize);
+        Free(ptr);
+        return newPtr;
+    }
+    
+    size_t GetTotalAllocated() const override { return m_allocated; }
+    size_t GetTotalFreed() const override { return m_freed; }
+    size_t GetPeakAllocated() const override { return m_peak; }
+    size_t GetAllocationCount() const override { return m_count; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+```
+
+## 相关文档
+
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [MemoryManager](../manager/manager.md) - 内存管理器
+- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
+- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器

docs/api/memory/allocator/free.md

@@ -0,0 +1,40 @@
+# IAllocator::Free
+
+```cpp
+virtual void Free(void* ptr) = 0;
+```
+
+释放之前通过 `Allocate` 分配的内存块。如果 `ptr` 为 `nullptr`，则此调用无效果。部分分配器（如 LinearAllocator）可能不支持此操作。
+
+**参数：**
+- `ptr` - 指向要释放内存块的指针
+
+**返回：** 无
+
+**复杂度：** O(1)（固定块释放）或 O(n)（需要搜索）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        return ::operator new(size);
+    }
+    
+    void Free(void* ptr) override {
+        if (ptr) ::operator delete(ptr);
+    }
+    // ... 其他方法实现
+};
+
+MyAllocator alloc;
+void* ptr = alloc.Allocate(512);
+alloc.Free(ptr); // 释放内存
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/get-allocation-count.md

@@ -0,0 +1,52 @@
+# IAllocator::GetAllocationCount
+
+```cpp
+virtual size_t GetAllocationCount() const = 0;
+```
+
+返回当前处于已分配状态（未释放）的内存块数量。此方法用于监控活跃分配的数量。
+
+**参数：** 无
+
+**返回：** 当前已分配块的数量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+    size_t m_count = 0;
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        ++m_count;
+        return ::operator new(size);
+    }
+    
+    void Free(void* ptr) override {
+        if (ptr) {
+            --m_count;
+            ::operator delete(ptr);
+        }
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
+    
+    size_t GetTotalAllocated() const override { return 0; }
+    size_t GetTotalFreed() const override { return 0; }
+    size_t GetPeakAllocated() const override { return 0; }
+    size_t GetAllocationCount() const override { return m_count; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+
+MyAllocator alloc;
+alloc.Allocate(64);
+alloc.Allocate(128);
+size_t count = alloc.GetAllocationCount(); // 返回 2
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/get-name.md

@@ -0,0 +1,40 @@
+# IAllocator::GetName
+
+```cpp
+virtual const char* GetName() const = 0;
+```
+
+返回分配器的名称字符串。此方法用于调试、日志记录和内存报告，帮助识别不同分配器的使用情况。
+
+**参数：** 无
+
+**返回：** 分配器的名称字符串
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); }
+    void Free(void* ptr) override { if (ptr) ::operator delete(ptr); }
+    void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
+    
+    size_t GetTotalAllocated() const override { return 0; }
+    size_t GetTotalFreed() const override { return 0; }
+    size_t GetPeakAllocated() const override { return 0; }
+    size_t GetAllocationCount() const override { return 0; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+
+MyAllocator alloc;
+const char* name = alloc.GetName(); // 返回 "MyAllocator"
+printf("Allocator: %s\n", name);
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/get-peak-allocated.md

@@ -0,0 +1,57 @@
+# IAllocator::GetPeakAllocated
+
+```cpp
+virtual size_t GetPeakAllocated() const = 0;
+```
+
+返回此分配器自创建以来达到的峰值分配字节数。该值在每次分配后更新，用于监控内存使用高峰。
+
+**参数：** 无
+
+**返回：** 峰值分配字节数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+    size_t m_peak = 0;
+    size_t m_current = 0;
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        void* ptr = ::operator new(size);
+        m_current += size;
+        if (m_current > m_peak) m_peak = m_current;
+        return ptr;
+    }
+    
+    void Free(void* ptr) override {
+        if (ptr) {
+            size_t size = 256; // 需要外部记录
+            ::operator delete(ptr);
+            m_current -= size;
+        }
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
+    
+    size_t GetTotalAllocated() const override { return 0; }
+    size_t GetTotalFreed() const override { return 0; }
+    size_t GetPeakAllocated() const override { return m_peak; }
+    size_t GetAllocationCount() const override { return 0; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+
+MyAllocator alloc;
+alloc.Allocate(100);
+size_t peak1 = alloc.GetPeakAllocated(); // 100
+alloc.Allocate(50);
+size_t peak2 = alloc.GetPeakAllocated(); // 150
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/get-total-allocated.md

@@ -0,0 +1,50 @@
+# IAllocator::GetTotalAllocated
+
+```cpp
+virtual size_t GetTotalAllocated() const = 0;
+```
+
+返回此分配器自创建以来累计分配的字节总数。这是一个只读查询操作，不会修改任何内部状态。
+
+**参数：** 无
+
+**返回：** 累计已分配的字节数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+    size_t m_allocated = 0;
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        void* ptr = ::operator new(size);
+        m_allocated += size;
+        return ptr;
+    }
+    
+    void Free(void* ptr) override {
+        if (ptr) ::operator delete(ptr);
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
+    
+    size_t GetTotalAllocated() const override { return m_allocated; }
+    size_t GetTotalFreed() const override { return 0; }
+    size_t GetPeakAllocated() const override { return m_allocated; }
+    size_t GetAllocationCount() const override { return 0; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+
+MyAllocator alloc;
+alloc.Allocate(100);
+alloc.Allocate(200);
+size_t total = alloc.GetTotalAllocated(); // 返回 300
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/get-total-freed.md

@@ -0,0 +1,50 @@
+# IAllocator::GetTotalFreed
+
+```cpp
+virtual size_t GetTotalFreed() const = 0;
+```
+
+返回此分配器自创建以来累计释放的字节总数。部分分配器（如 LinearAllocator）可能始终返回 0，因为它们不跟踪单个释放操作。
+
+**参数：** 无
+
+**返回：** 累计已释放的字节数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+    size_t m_freed = 0;
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); }
+    
+    void Free(void* ptr) override {
+        if (ptr) {
+            size_t size = 256; // 需要外部记录
+            ::operator delete(ptr);
+            m_freed += size;
+        }
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
+    
+    size_t GetTotalAllocated() const override { return 0; }
+    size_t GetTotalFreed() const override { return m_freed; }
+    size_t GetPeakAllocated() const override { return 0; }
+    size_t GetAllocationCount() const override { return 0; }
+    const char* GetName() const override { return "MyAllocator"; }
+};
+
+MyAllocator alloc;
+void* ptr = alloc.Allocate(128);
+alloc.Free(ptr);
+size_t freed = alloc.GetTotalFreed(); // 返回 128
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/allocator/reallocate.md

@@ -0,0 +1,55 @@
+# IAllocator::Reallocate
+
+```cpp
+virtual void* Reallocate(void* ptr, size_t newSize) = 0;
+```
+
+调整已分配内存块的大小。如果 `ptr` 为 `nullptr`，行为等同于 `Allocate(newSize)`。如果 `newSize` 为 0，行为等同于 `Free(ptr)` 并返回 `nullptr`。如果分配器不支持重新分配，应返回 `nullptr` 并保持原内存不变。
+
+**参数：**
+- `ptr` - 指向现有内存块的指针
+- `newSize` - 新的字节大小
+
+**返回：** 调整后的新内存块指针（可能与原指针不同）
+
+**复杂度：** O(n)，需要分配新内存并复制数据
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/Allocator.h>
+
+class MyAllocator : public IAllocator {
+public:
+    void* Allocate(size_t size, size_t alignment = 0) override {
+        return ::operator new(size);
+    }
+    
+    void Free(void* ptr) override {
+        if (ptr) ::operator delete(ptr);
+    }
+    
+    void* Reallocate(void* ptr, size_t newSize) override {
+        if (newSize == 0) {
+            Free(ptr);
+            return nullptr;
+        }
+        if (!ptr) return Allocate(newSize);
+        
+        size_t oldSize = /* 需要外部记录 */ 256; // 示例中硬编码
+        void* newPtr = Allocate(newSize);
+        memcpy(newPtr, ptr, oldSize < newSize ? oldSize : newSize);
+        Free(ptr);
+        return newPtr;
+    }
+    // ... 其他方法实现
+};
+
+MyAllocator alloc;
+void* ptr = alloc.Allocate(128);
+void* bigger = alloc.Reallocate(ptr, 256); // 扩展到 256 字节
+```
+
+## 相关文档
+
+- [IAllocator 总览](allocator.md) - 返回类总览

docs/api/memory/linear-allocator/allocate.md

@@ -0,0 +1,41 @@
+# LinearAllocator::Allocate
+
+```cpp
+void* Allocate(size_t size, size_t alignment = 8) override;
+```
+
+在缓冲区的当前位置顺序分配内存。每次分配都会将内部偏移量向前推进（对齐后）。如果剩余空间不足，则分配失败返回 `nullptr`。默认对齐值为 8 字节。
+
+**参数：**
+- `size` - 请求的字节数
+- `alignment` - 内存对齐要求，默认为 8 字节
+
+**返回：** 分配成功返回已对齐的指针，失败返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+
+// 分配 256 字节（8 字节对齐）
+void* ptr1 = allocator.Allocate(256);
+
+// 分配 128 字节（16 字节对齐）
+void* ptr2 = allocator.Allocate(128, 16);
+
+// 分配 64 字节（默认 8 字节对齐）
+void* ptr3 = allocator.Allocate(64);
+
+// 检查是否成功
+if (!ptr1) {
+    // 分配失败，缓冲区已满
+}
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/clear.md

@@ -0,0 +1,37 @@
+# LinearAllocator::Clear
+
+```cpp
+void Clear();
+```
+
+清空分配器，将内部偏移量重置为 0，所有已分配的内存被视为已释放。下一次 `Allocate` 将从缓冲区起始位置开始。此方法不实际释放或修改底层内存，适合作为帧分配器使用，每帧开始时调用 Clear 重置。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024 * 1024);
+
+// 第一帧
+void* frame1_ptr = allocator.Allocate(256);
+void* frame1_ptr2 = allocator.Allocate(128);
+// ... 第一帧渲染逻辑
+
+// 帧结束时清空
+allocator.Clear();
+
+// 第二帧重新开始
+void* frame2_ptr = allocator.Allocate(256);
+// 此时 frame1_ptr 已无效，但内存已被回收复用
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/free.md

@@ -0,0 +1,35 @@
+# LinearAllocator::Free
+
+```cpp
+void Free(void* ptr) override;
+```
+
+此方法对 LinearAllocator 无实际效果。线性分配器不支持单个内存块的释放，因为内存是顺序分配的，释放中间某块会破坏后续分配的完整性。需要释放所有内存时使用 `Clear()` 方法。
+
+**参数：**
+- `ptr` - 被忽略
+
+**返回：** 无
+
+**复杂度：** O(1)（空操作）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+void* ptr = allocator.Allocate(256);
+void* ptr2 = allocator.Allocate(128);
+
+// Free 实际上什么都不做
+allocator.Free(ptr);
+allocator.Free(ptr2);
+
+// 如需释放所有内存，应使用 Clear
+allocator.Clear();
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/get-capacity.md

@@ -0,0 +1,33 @@
+# LinearAllocator::GetCapacity
+
+```cpp
+size_t GetCapacity() const;
+```
+
+返回分配器的总容量，即预分配缓冲区的大小。此值在构造时确定，之后保持不变。
+
+**参数：** 无
+
+**返回：** 总容量（字节数）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024 * 1024); // 1MB
+
+size_t capacity = allocator.GetCapacity(); // 1048576
+
+allocator.Allocate(512);
+allocator.Allocate(256);
+
+size_t used = allocator.GetUsedSize();   // 768
+size_t remaining = allocator.GetCapacity() - allocator.GetUsedSize(); // 1047808
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/get-marker.md

@@ -0,0 +1,43 @@
+# LinearAllocator::GetMarker
+
+```cpp
+void* GetMarker() const;
+```
+
+获取当前分配位置的标记。标记是内部偏移量（`m_offset`）的快照，可用于 `SetMarker` 恢复到该位置。此方法用于实现临时分配的撤销功能。
+
+**参数：** 无
+
+**返回：** 当前位置标记（偏移量值），类型为 `void*`
+
+**注意：** 返回值是偏移量数值，不是指针。将其传给 `SetMarker` 可恢复到此分配位置。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+
+// 分配一些数据
+void* ptr1 = allocator.Allocate(128);
+
+// 保存标记（用于回滚点）
+void* marker = allocator.GetMarker();
+
+// 分配临时数据
+void* temp = allocator.Allocate(64);
+void* temp2 = allocator.Allocate(32);
+
+// 临时数据用完了，恢复到标记位置
+allocator.SetMarker(marker);
+
+// 此时 temp 和 temp2 的内存已被回收
+// ptr1 仍然有效
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/get-used-size.md

@@ -0,0 +1,39 @@
+# LinearAllocator::GetUsedSize
+
+```cpp
+size_t GetUsedSize() const;
+```
+
+返回当前已使用的字节数，即内部偏移量的值。此值在 `Allocate` 后增加，在 `Clear` 或 `SetMarker` 后可能减少（取决于设置的目标位置）。
+
+**参数：** 无
+
+**返回：** 已使用的字节数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+
+size_t before = allocator.GetUsedSize(); // 0
+
+allocator.Allocate(128);
+allocator.Allocate(256);
+
+size_t after = allocator.GetUsedSize(); // 384
+
+void* marker = allocator.GetMarker();
+allocator.Allocate(64);
+size_t with_temp = allocator.GetUsedSize(); // 448
+
+allocator.SetMarker(marker);
+size_t after_rollback = allocator.GetUsedSize(); // 384
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/linear-allocator.md

@@ -0,0 +1,66 @@
+# LinearAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 线性分配器，适合帧分配和临时对象。
+
+## 概述
+
+`LinearAllocator` 是一种顺序分配器，预分配一个大缓冲区，每次分配从缓冲区起始位置顺序分配，偏移量递增。它不适合需要释放任意块的场景，但分配和清除非常高效，常用于帧分配器。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `LinearAllocator` | 构造线性分配器 |
+| `~LinearAllocator` | 析构函数，释放底层缓冲区 |
+| `Allocate` | 顺序分配内存 |
+| `Free` | 无效果（不支持） |
+| `Reallocate` | 不支持（始终返回 nullptr） |
+| `Clear` | 清空所有分配 |
+| `GetMarker` | 获取当前位置标记 |
+| `SetMarker` | 回滚到指定标记位置 |
+| `GetUsedSize` | 获取已使用字节数 |
+| `GetCapacity` | 获取总容量 |
+
+## 构造函数
+
+```cpp
+explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
+~LinearAllocator() override;
+```
+
+构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。
+
+**参数：**
+- `size` - 预分配的缓冲区大小（字节数）
+- `parent` - 父分配器，用于分配底层缓冲区，默认为 `nullptr`（使用系统分配）
+
+**返回：** 无
+
+**复杂度：** O(n)，需要分配 `size` 大小的缓冲区
+
+**注意：** `Free` 和 `Reallocate` 方法无实际效果。`Free` 是空操作，`Reallocate` 始终返回 `nullptr`。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+// 使用系统分配器创建 1MB 线性分配器
+LinearAllocator allocator1(1024 * 1024);
+
+// 使用指定的父分配器
+IAllocator* parent = MemoryManager::Get().GetSystemAllocator();
+LinearAllocator allocator2(1024 * 1024, parent);
+
+// 默认 8 字节对齐
+void* ptr = allocator1.Allocate(256);
+```
+
+## 相关文档
+
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口

docs/api/memory/linear-allocator/reallocate.md

@@ -0,0 +1,35 @@
+# LinearAllocator::Reallocate
+
+```cpp
+void* Reallocate(void* ptr, size_t newSize) override;
+```
+
+线性分配器不支持重新分配。此方法始终返回 `nullptr`，原内存块保持不变。由于线性分配器的顺序分配特性，无法调整现有块的大小。
+
+**参数：**
+- `ptr` - 不被使用（始终返回 nullptr）
+- `newSize` - 不被使用（始终返回 nullptr）
+
+**返回：** 始终返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+void* ptr1 = allocator.Allocate(128);
+
+// Reallocate 不支持，始终返回 nullptr
+void* ptr2 = allocator.Reallocate(ptr1, 256);
+if (!ptr2) {
+    // 线性分配器不支持重新分配
+    // ptr1 仍然有效
+}
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/set-marker.md

@@ -0,0 +1,41 @@
+# LinearAllocator::SetMarker
+
+```cpp
+void SetMarker(void* marker);
+```
+
+恢复到之前通过 `GetMarker` 获取的标记位置。所有在标记之后的分配都将被丢弃，内部偏移量重置为该标记位置。此方法不会释放内存，只是移动偏移量指针。
+
+**参数：**
+- `marker` - 通过 `GetMarker` 获取的标记指针
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+LinearAllocator allocator(1024);
+
+// 基础数据
+void* base = allocator.Allocate(256);
+void* marker = allocator.GetMarker();
+
+// 可选的扩展数据
+void* ext1 = allocator.Allocate(64);
+void* ext2 = allocator.Allocate(128);
+
+// 决定不使用扩展数据，回滚
+allocator.SetMarker(marker);
+
+// 扩展数据内存已被回收
+// 可以重新分配其他数据
+void* new_data = allocator.Allocate(128);
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/linear-allocator/~linear-allocator.md

@@ -0,0 +1,29 @@
+# LinearAllocator::~LinearAllocator
+
+```cpp
+~LinearAllocator() override;
+```
+
+销毁线性分配器，释放预分配的缓冲区。如果提供了 `parent` 分配器，则使用它释放缓冲区；否则使用系统默认释放（`::operator delete`）。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/LinearAllocator.h>
+
+{
+    LinearAllocator allocator(1024 * 1024);
+    void* ptr = allocator.Allocate(256);
+    // ... 使用 allocator
+} // 析构时自动释放 1MB 缓冲区
+```
+
+## 相关文档
+
+- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

docs/api/memory/manager/create-linear-allocator.md

@@ -0,0 +1,32 @@
+# MemoryManager::CreateLinearAllocator
+
+```cpp
+std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
+```
+
+创建并返回一个新的 LinearAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
+
+**参数：**
+- `size` - 分配器缓冲区大小（字节）
+
+**返回：** LinearAllocator 的 unique_ptr
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+auto linear = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
+void* ptr = linear->Allocate(256);
+void* marker = linear->GetMarker();
+linear->Allocate(128);
+linear->SetMarker(marker);
+linear->Clear();
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览
+- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器

docs/api/memory/manager/create-pool-allocator.md

@@ -0,0 +1,37 @@
+# MemoryManager::CreatePoolAllocator
+
+```cpp
+std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count);
+```
+
+创建并返回一个新的 PoolAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
+
+**参数：**
+- `blockSize` - 每个内存块的大小（字节）
+- `count` - 内存池中块的数量
+
+**返回：** PoolAllocator 的 unique_ptr
+
+**复杂度：** O(blockSize * count)（需要预分配所有块）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+struct Particle {
+    float x, y, z;
+    float life;
+};
+
+auto pool = MemoryManager::Get().CreatePoolAllocator(sizeof(Particle), 1000);
+void* block = pool->Allocate();
+auto* p = new (block) Particle{1.0f, 2.0f, 3.0f, 5.0f};
+p->~Particle();
+pool->Free(block);
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览
+- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器

docs/api/memory/manager/create-proxy-allocator.md

@@ -0,0 +1,36 @@
+# MemoryManager::CreateProxyAllocator
+
+```cpp
+std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name);
+```
+
+创建并返回一个新的 ProxyAllocator 实例，包装系统分配器并使用指定名称。返回的 `unique_ptr` 管理分配器生命周期。
+
+**参数：**
+- `name` - 代理分配器的名称
+
+**返回：** ProxyAllocator 的 unique_ptr
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+auto proxy = MemoryManager::Get().CreateProxyAllocator("FrameData");
+void* ptr = proxy->Allocate(1024);
+void* ptr2 = proxy->Allocate(512);
+
+const auto& stats = proxy->GetStats();
+printf("Peak: %zu bytes, Count: %zu\n",
+    stats.peakAllocated, stats.allocationCount);
+
+proxy->Free(ptr);
+proxy->Free(ptr2);
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览
+- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器

docs/api/memory/manager/dump-memory-leaks.md

@@ -0,0 +1,31 @@
+# MemoryManager::DumpMemoryLeaks
+
+```cpp
+void DumpMemoryLeaks();
+```
+
+输出当前未释放的内存分配信息。如果启用了内存跟踪，此方法会遍历所有记录并报告疑似泄漏的分配。应在程序退出前调用，以便发现资源泄漏。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+MemoryManager::Get().Initialize();
+
+// ... 程序运行 ...
+
+// 程序退出前检查泄漏
+MemoryManager::Get().DumpMemoryLeaks();
+MemoryManager::Get().Shutdown();
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/generate-memory-report.md

@@ -0,0 +1,37 @@
+# MemoryManager::GenerateMemoryReport
+
+```cpp
+void GenerateMemoryReport();
+```
+
+生成并输出当前内存使用情况的详细报告。报告内容包括各分配器的统计信息、峰值使用量、分配次数等。应在启用内存跟踪后调用。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+MemoryManager::Get().Initialize();
+
+auto proxy = MemoryManager::Get().CreateProxyAllocator("GameFrame");
+proxy->Allocate(1024 * 1024);
+proxy->Allocate(512 * 1024);
+
+// 生成内存报告
+MemoryManager::Get().GenerateMemoryReport();
+
+proxy->Free(proxy->Allocate(256 * 1024));
+MemoryManager::Get().GenerateMemoryReport();
+
+MemoryManager::Get().Shutdown();
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/get-system-allocator.md

@@ -0,0 +1,27 @@
+# MemoryManager::GetSystemAllocator
+
+```cpp
+IAllocator* GetSystemAllocator();
+```
+
+获取系统默认分配器。该分配器使用标准 C 库的 `std::malloc` 和平台特定的对齐分配函数（如 Windows 的 `_aligned_malloc`）作为后端，适用于通用内存分配场景。
+
+**参数：** 无
+
+**返回：** 系统分配器指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+void* ptr = sysAlloc->Allocate(1024);
+sysAlloc->Free(ptr);
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/get.md

@@ -0,0 +1,39 @@
+# MemoryManager::Get
+
+```cpp
+static MemoryManager& Get();
+```
+
+获取 MemoryManager 单例实例。如果尚未创建则内部构造。此方法是获取内存管理器实例的唯一途径。
+
+**参数：** 无
+
+**返回：** MemoryManager 单例引用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+// 获取单例
+MemoryManager& manager = MemoryManager::Get();
+
+// 初始化
+manager.Initialize();
+
+// 访问系统分配器
+IAllocator* sysAlloc = manager.GetSystemAllocator();
+
+// 关闭
+manager.Shutdown();
+
+// 多次调用返回同一实例
+MemoryManager& manager2 = MemoryManager::Get();
+// manager == manager2 为 true
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/initialize.md

@@ -0,0 +1,33 @@
+# MemoryManager::Initialize
+
+```cpp
+void Initialize();
+```
+
+初始化内存管理器。创建系统默认分配器，设置内存跟踪标志。应在程序启动早期调用，且仅可调用一次。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+int main() {
+    // 程序启动时初始化
+    MemoryManager::Get().Initialize();
+    
+    // 使用内存系统...
+    
+    MemoryManager::Get().Shutdown();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/manager.md

@@ -0,0 +1,85 @@
+# MemoryManager
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class` (singleton)
+
+**描述**: 全局内存管理器单例，提供系统分配器和各种专用分配器的创建。
+
+## 概述
+
+`MemoryManager` 是 XCEngine 内存管理系统的核心单例。它负责维护系统分配器，提供分配器工厂方法，并支持内存泄漏检测和报告。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `Get` | 获取单例实例 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `Initialize` | 初始化内存管理器 |
+| `Shutdown` | 关闭内存管理器 |
+| `GetSystemAllocator` | 获取系统默认分配器 |
+| `CreateLinearAllocator` | 创建线性分配器 |
+| `CreatePoolAllocator` | 创建内存池分配器 |
+| `CreateProxyAllocator` | 创建代理分配器 |
+| `SetTrackAllocations` | 设置是否跟踪分配 |
+| `DumpMemoryLeaks` | 输出内存泄漏报告 |
+| `GenerateMemoryReport` | 生成内存使用报告 |
+
+## 宏定义
+
+### XE_ALLOC
+
+```cpp
+#define XE_ALLOC(allocator, size, ...) allocator->Allocate(size, ##__VA_ARGS__)
+```
+
+内存分配宏。
+
+### XE_FREE
+
+```cpp
+#define XE_FREE(allocator, ptr) allocator->Free(ptr)
+```
+
+内存释放宏。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+// 初始化
+MemoryManager::Get().Initialize();
+
+// 获取系统分配器
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+
+// 创建专用分配器
+auto linearAlloc = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
+auto poolAlloc = MemoryManager::Get().CreatePoolAllocator(sizeof(MyObject), 1000);
+auto proxyAlloc = MemoryManager::Get().CreateProxyAllocator("GameFrame");
+
+// 使用宏分配
+void* ptr = XE_ALLOC(proxyAlloc, 256);
+XE_FREE(proxyAlloc, ptr);
+
+// 跟踪内存
+MemoryManager::Get().SetTrackAllocations(true);
+MemoryManager::Get().GenerateMemoryReport();
+
+// 关闭
+MemoryManager::Get().Shutdown();
+```
+
+## 相关文档
+
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口
+- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
+- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
+- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器

docs/api/memory/manager/set-track-allocations.md

@@ -0,0 +1,35 @@
+# MemoryManager::SetTrackAllocations
+
+```cpp
+void SetTrackAllocations(bool track);
+```
+
+设置是否启用内存分配跟踪。启用后系统会记录所有分配操作，用于生成内存报告和泄漏检测。
+
+**参数：**
+- `track` - true 启用跟踪，false 禁用跟踪
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+MemoryManager::Get().Initialize();
+
+// 禁用跟踪（提升性能）
+MemoryManager::Get().SetTrackAllocations(false);
+
+// ... 大量内存操作 ...
+
+// 重新启用跟踪进行分析
+MemoryManager::Get().SetTrackAllocations(true);
+MemoryManager::Get().GenerateMemoryReport();
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/manager/shutdown.md

@@ -0,0 +1,35 @@
+# MemoryManager::Shutdown
+
+```cpp
+void Shutdown();
+```
+
+关闭内存管理器。执行内存泄漏检测报告，释放系统分配器。应在程序退出前调用。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+int main() {
+    MemoryManager::Get().Initialize();
+    
+    // ... 游戏主循环 ...
+    
+    // 程序退出前关闭
+    MemoryManager::Get().DumpMemoryLeaks();
+    MemoryManager::Get().Shutdown();
+    
+    return 0;
+}
+```
+
+## 相关文档
+
+- [MemoryManager 总览](manager.md) - 返回类总览

docs/api/memory/memory.md

@@ -0,0 +1,72 @@
+# Memory 模块概览
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `module`
+
+**描述**: XCEngine 的内存管理模块，提供多种内存分配器实现。
+
+## 概述
+
+Memory 模块提供了一套完整的内存管理解决方案，包括基础分配器接口和各种专用分配器实现。
+
+## 模块内容
+
+### 分配器接口
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [IAllocator](allocator/allocator.md) | `Allocator.h` | 内存分配器抽象接口 |
+
+### 分配器实现
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [LinearAllocator](linear-allocator/linear-allocator.md) | `LinearAllocator.h` | 线性分配器，适合帧分配 |
+| [PoolAllocator](pool-allocator/pool-allocator.md) | `PoolAllocator.h` | 内存池分配器，适合固定大小对象 |
+| [ProxyAllocator](proxy-allocator/proxy-allocator.md) | `ProxyAllocator.h` | 代理分配器，用于统计和跟踪 |
+
+### 管理器
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [MemoryManager](manager/manager.md) | `MemoryManager.h` | 全局内存管理器 |
+
+## 分配器类型对比
+
+| 分配器 | 适用场景 | 特点 |
+|--------|----------|------|
+| `IAllocator` | 基类接口 | 定义标准分配协议 |
+| `LinearAllocator` | 帧分配、临时对象 | 快速分配，只支持按顺序释放 |
+| `PoolAllocator` | 同尺寸对象池 | 高效分配，消除碎片 |
+| `ProxyAllocator` | 调试和统计 | 记录分配信息，跟踪内存使用 |
+
+## 宏定义
+
+| 宏 | 描述 |
+|----|------|
+| `XE_ALLOC(allocator, size, ...)` | 内存分配宏 |
+| `XE_FREE(allocator, ptr)` | 内存释放宏 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+
+// 获取系统分配器
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+
+// 创建线性分配器
+auto linearAlloc = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
+
+// 使用代理分配器跟踪统计
+auto proxyAlloc = MemoryManager::Get().CreateProxyAllocator("FrameData");
+
+// 分配内存
+void* ptr = XE_ALLOC(linearAlloc, 1024);
+XE_FREE(linearAlloc, ptr);
+```
+
+## 相关文档
+
+- [Containers 模块](../containers/containers.md) - 使用分配器的容器

docs/api/memory/pool-allocator/allocate.md

@@ -0,0 +1,38 @@
+# PoolAllocator::Allocate
+
+```cpp
+void* Allocate(size_t size, size_t alignment = 0) override;
+```
+
+从内存池中分配一个空闲块。每次分配一个固定大小的块。如果 `size` 超过块大小或池中没有空闲块，返回 `nullptr`。分配操作从空闲链表头部取出一个块。
+
+**参数：**
+- `size` - 请求的大小，如果超过构造时指定的块大小则分配失败
+- `alignment` - 被忽略（构造时确定）
+
+**返回：** 分配成功返回块指针，池空返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+// 创建能容纳 1000 个整数的内存池
+PoolAllocator pool(sizeof(int), 1000, alignof(int));
+
+// 分配（忽略 size 参数，只分配固定大小的块）
+void* block1 = pool.Allocate(1);     // 分配一块（实际大小为 sizeof(int)）
+void* block2 = pool.Allocate(10000); // 也分配一块（实际大小为 sizeof(int)）
+
+if (block1 && block2) {
+    // 使用分配的内存块
+    int* arr = static_cast<int*>(block1);
+    arr[0] = 42;
+}
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/contains.md

@@ -0,0 +1,38 @@
+# PoolAllocator::Contains
+
+```cpp
+bool Contains(void* ptr) const;
+```
+
+检查给定的指针是否属于此内存池的地址范围。由于池在构造时预分配连续内存，可通过指针地址区间判断所有权。此方法用于调试和内存验证。
+
+**参数：**
+- `ptr` - 要检查的指针
+
+**返回：** 指针属于此池返回 `true`，否则返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int), 100);
+
+void* inside = pool.Allocate();
+void* outside = ::operator new(sizeof(int));
+
+if (pool.Contains(inside)) {
+    // inside 属于此内存池，可以安全 Free
+}
+
+if (!pool.Contains(outside)) {
+    // outside 不属于此池，不能调用 pool.Free()
+    ::operator delete(outside);
+}
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/free.md

@@ -0,0 +1,38 @@
+# PoolAllocator::Free
+
+```cpp
+void Free(void* ptr) override;
+```
+
+将内存块归还到空闲链表中。如果 `ptr` 为 `nullptr` 则无效果。释放操作将块插入空闲链表头部。必须传入从此池分配的指针，传入外部指针会导致未定义行为。
+
+**参数：**
+- `ptr` - 指向要释放的内存块
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int), 100);
+
+void* block = pool.Allocate();
+if (block) {
+    int* num = static_cast<int*>(block);
+    *num = 123;
+    
+    pool.Free(block); // 归还到空闲链表
+    block = nullptr;
+}
+
+// 检查空闲块数量
+size_t freeCount = pool.GetFreeBlockCount();
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/get-block-size.md

@@ -0,0 +1,31 @@
+# PoolAllocator::GetBlockSize
+
+```cpp
+size_t GetBlockSize() const;
+```
+
+返回内存池中每个内存块的大小。此值在构造时确定，之后保持不变。
+
+**参数：** 无
+
+**返回：** 每个内存块的字节大小
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int) * 100, 50);
+
+size_t blockSize = pool.GetBlockSize(); // 400 字节
+
+void* block = pool.Allocate();
+int* arr = static_cast<int*>(block);
+// arr 指向的大小为 blockSize 字节的内存块
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/get-free-block-count.md

@@ -0,0 +1,40 @@
+# PoolAllocator::GetFreeBlockCount
+
+```cpp
+size_t GetFreeBlockCount() const;
+```
+
+返回当前空闲块的的数量。每次 `Allocate` 成功后减 1，每次 `Free` 后加 1。
+
+**参数：** 无
+
+**返回：** 当前可分配的空闲块数量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int), 100);
+
+size_t initial = pool.GetFreeBlockCount(); // 100
+
+void* blocks[10];
+for (int i = 0; i < 10; ++i) {
+    blocks[i] = pool.Allocate();
+}
+
+size_t after = pool.GetFreeBlockCount(); // 90
+
+for (int i = 0; i < 5; ++i) {
+    pool.Free(blocks[i]);
+}
+
+size_t final = pool.GetFreeBlockCount(); // 95
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/get-total-block-count.md

@@ -0,0 +1,34 @@
+# PoolAllocator::GetTotalBlockCount
+
+```cpp
+size_t GetTotalBlockCount() const;
+```
+
+返回内存池中的总块数。此值在构造时确定，之后保持不变。
+
+**参数：** 无
+
+**返回：** 内存池的总块数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int), 100);
+
+size_t total = pool.GetTotalBlockCount(); // 100
+size_t free = pool.GetFreeBlockCount();  // 100
+
+void* block = pool.Allocate();
+size_t freeAfter = pool.GetFreeBlockCount(); // 99
+
+pool.Free(block);
+size_t freeRestored = pool.GetFreeBlockCount(); // 100
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/pool-allocator.md

@@ -0,0 +1,73 @@
+# PoolAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 内存池分配器，预分配固定大小的内存块池。
+
+## 概述
+
+`PoolAllocator` 是一种高效固定块分配器，适合需要频繁分配和释放相同大小对象的场景，如对象池、粒子系统等。它预分配 `poolSize` 个大小为 `blockSize` 字节的内存块，通过空闲链表管理分配和回收。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `PoolAllocator` | 构造内存池分配器 |
+| `~PoolAllocator` | 析构函数，释放整个内存池 |
+| `Allocate` | 分配一个内存块 |
+| `Free` | 释放内存块回空闲链表 |
+| `Reallocate` | 不支持（始终返回 nullptr） |
+| `Contains` | 检查指针是否属于此池 |
+| `GetBlockSize` | 获取块大小 |
+| `GetFreeBlockCount` | 获取空闲块数量 |
+| `GetTotalBlockCount` | 获取总块数 |
+
+## 构造函数
+
+```cpp
+PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
+~PoolAllocator() override;
+```
+
+构造内存池分配器，预分配 `poolSize` 个大小为 `blockSize` 字节的内存块。内存块按 `alignment` 对齐（默认 8 字节）。内部维护一个空闲块链表来管理分配。析构函数释放整个内存池。
+
+**参数：**
+- `blockSize` - 每个内存块的大小（字节）
+- `poolSize` - 内存池中总块数
+- `alignment` - 对齐要求，默认为 8
+
+**返回：** 无
+
+**复杂度：** O(n)，需要预分配所有块
+
+**注意：** `Reallocate` 方法始终返回 `nullptr`，此分配器不支持重新分配。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+struct Particle {
+    float x, y, z;
+    float vx, vy, vz;
+    float life;
+};
+
+// 创建一个能容纳 1000 个 Particle 的内存池，16 字节对齐
+PoolAllocator pool(sizeof(Particle), 1000, alignof(Particle));
+
+size_t blockSize = pool.GetBlockSize();   // sizeof(Particle)
+size_t total = pool.GetTotalBlockCount(); // 1000
+size_t free = pool.GetFreeBlockCount();   // 1000
+
+// 分配和释放
+void* block = pool.Allocate();
+pool.Free(block);
+```
+
+## 相关文档
+
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口

docs/api/memory/pool-allocator/reallocate.md

@@ -0,0 +1,35 @@
+# PoolAllocator::Reallocate
+
+```cpp
+void* Reallocate(void* ptr, size_t newSize) override;
+```
+
+内存池分配器不支持重新分配。此方法始终返回 `nullptr`，原内存块保持不变。
+
+**参数：**
+- `ptr` - 不被使用
+- `newSize` - 不被使用
+
+**返回：** 始终返回 `nullptr`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+PoolAllocator pool(sizeof(int), 100);
+void* block = pool.Allocate();
+
+// Reallocate 不支持
+void* newBlock = pool.Reallocate(block, 256);
+if (!newBlock) {
+    // 内存池不支持重新分配
+    // 原 block 仍然有效
+}
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/pool-allocator/~pool-allocator.md

@@ -0,0 +1,31 @@
+# PoolAllocator::~PoolAllocator
+
+```cpp
+~PoolAllocator() override;
+```
+
+销毁内存池分配器，释放预分配的所有内存块。析构函数调用 `std::free` 释放整个内存池，不再需要单独释放每个块。
+
+**参数：** 无
+
+**返回：** 无
+
+**注意：** 析构函数释放整个内存池，包括所有已分配和空闲的块。调用析构函数后，池中所有已分配出去的块也随之失效，使用这些块指针将导致未定义行为。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/PoolAllocator.h>
+
+{
+    PoolAllocator pool(sizeof(int), 1000);
+    void* block = pool.Allocate();
+    // ... 使用内存块
+    
+    pool.Free(block); // 可选：显式释放（析构时会自动释放）
+} // 超出作用域时自动释放整个内存池
+```
+
+## 相关文档
+
+- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

docs/api/memory/proxy-allocator/allocate.md

@@ -0,0 +1,37 @@
+# ProxyAllocator::Allocate
+
+```cpp
+void* Allocate(size_t size, size_t alignment = 0) override;
+```
+
+分配内存并记录统计。调用转发到底层分配器，同时递增分配计数和总分配字节数，并更新峰值记录。
+
+**参数：**
+- `size` - 请求的字节数
+- `alignment` - 内存对齐要求
+
+**返回：** 分配成功返回指针，失败返回 `nullptr`
+
+**复杂度：** O(1)（底层分配器复杂度 + 统计更新）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
+
+void* p1 = proxy.Allocate(100);
+void* p2 = proxy.Allocate(200);
+void* p3 = proxy.Allocate(300, 16);
+
+const auto& stats = proxy.GetStats();
+printf("Total: %zu, Peak: %zu, Count: %zu\n",
+    stats.totalAllocated, stats.peakAllocated, stats.allocationCount);
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

docs/api/memory/proxy-allocator/free.md

@@ -0,0 +1,42 @@
+# ProxyAllocator::Free
+
+```cpp
+void Free(void* ptr) override;
+```
+
+释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前 `allocationCount`），并递减 `allocationCount`。
+
+**注意：** `totalFreed` 累加的是每次释放时的 `allocationCount`（分配计数）而非实际字节大小。这是一个简化的实现，用于追踪释放操作次数。
+
+**参数：**
+- `ptr` - 指向要释放的内存块
+
+**返回：** 无
+
+**复杂度：** O(1)（底层释放 + 统计更新）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
+
+void* p1 = proxy.Allocate(512);
+void* p2 = proxy.Allocate(256);
+
+proxy.Free(p1);
+proxy.Free(p2);
+
+const auto& stats = proxy.GetStats();
+// totalFreed 累加了每次释放时的 allocationCount（次数，非字节）
+// allocationCount 最终为 0
+printf("Total allocated: %zu bytes, Freed count: %zu, Current count: %zu\n",
+    stats.totalAllocated, stats.totalFreed, stats.allocationCount);
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

docs/api/memory/proxy-allocator/get-stats.md

@@ -0,0 +1,40 @@
+# ProxyAllocator::GetStats
+
+```cpp
+const Stats& GetStats() const;
+```
+
+返回详细的统计信息结构体引用。包含累计分配、累计释放、峰值分配、分配次数和额外开销。返回 const 引用，无锁开销（内部已有互斥保护）。
+
+**参数：** 无
+
+**返回：** Stats 结构体 const 引用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "FrameData");
+
+proxy.Allocate(1024);
+proxy.Allocate(512);
+proxy.Free(proxy.Allocate(256));
+
+const ProxyAllocator::Stats& stats = proxy.GetStats();
+printf("Total allocated: %zu bytes\n", stats.totalAllocated);
+printf("Total freed: %zu times\n", stats.totalFreed);
+printf("Peak allocated: %zu bytes\n", stats.peakAllocated);
+printf("Allocation count: %zu\n", stats.allocationCount);
+printf("Memory overhead: %zu bytes\n", stats.memoryOverhead);
+printf("Current in use: %zu bytes\n",
+    stats.totalAllocated - stats.allocationCount * sizeof(/* typical block */ size_t));
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

docs/api/memory/proxy-allocator/proxy-allocator.md

@@ -0,0 +1,61 @@
+# ProxyAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 代理分配器，用于统计和跟踪底层分配器的分配情况。
+
+## 概述
+
+`ProxyAllocator` 包装一个底层分配器，转发所有分配请求，同时记录详细的统计信息。它线程安全（使用互斥锁保护统计数据），适合需要监控内存使用的场景。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `ProxyAllocator` | 构造代理分配器 |
+| `~ProxyAllocator` | 析构函数 |
+| `Allocate` | 分配内存并记录统计 |
+| `Free` | 释放内存并记录统计 |
+| `Reallocate` | 转发到底层分配器 |
+| `GetStats` | 获取详细统计信息 |
+
+## 构造函数
+
+```cpp
+ProxyAllocator(IAllocator* underlying, const char* name);
+```
+
+构造一个代理分配器，包装底层分配器并记录分配统计。所有 `Allocate`、`Free`、`Reallocate` 调用都会被转发到底层分配器，同时记录统计信息。名称用于日志和报告。
+
+**参数：**
+- `underlying` - 被包装的底层分配器，不能为 `nullptr`
+- `name` - 代理分配器的名称字符串
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+MemoryManager::Get().Initialize();
+
+// 使用系统分配器作为底层
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "TempAllocations");
+
+// 通过代理分配
+void* ptr = proxy.Allocate(1024);
+proxy.Free(ptr);
+```
+
+## 相关文档
+
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口
+- [MemoryManager](../manager/manager.md) - 内存管理器

docs/api/memory/proxy-allocator/reallocate.md

@@ -0,0 +1,38 @@
+# ProxyAllocator::Reallocate
+
+```cpp
+void* Reallocate(void* ptr, size_t newSize) override;
+```
+
+重新分配内存。调用转发到底层分配器，不记录额外统计信息（底层分配器的返回值直接返回）。此方法线程安全，内部使用互斥锁保护。
+
+**参数：**
+- `ptr` - 现有内存块指针
+- `newSize` - 新的字节大小
+
+**返回：** 成功返回新指针，失败返回 `nullptr`（由底层分配器决定）
+
+**复杂度：** O(n)（底层分配器 + 数据复制）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
+
+void* p1 = proxy.Allocate(128);
+void* p2 = proxy.Reallocate(p1, 256);
+
+if (p2) {
+    // 重新分配成功
+} else {
+    // 失败，p1 仍然有效
+}
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

docs/api/memory/proxy-allocator/~proxy-allocator.md

@@ -0,0 +1,37 @@
+# ProxyAllocator::~ProxyAllocator
+
+```cpp
+~ProxyAllocator() override;
+```
+
+销毁代理分配器。此析构函数不释放底层分配器，只清理代理分配器自身的统计信息（互斥锁等）。底层分配器由创建者负责管理。
+
+**参数：** 无
+
+**返回：** 无
+
+**注意：** 析构函数不释放底层分配器。如果需要释放底层分配器，应先调用 `Shutdown` 或显式销毁底层分配器。
+
+**示例：**
+
+```cpp
+#include <XCEngine/Memory/MemoryManager.h>
+#include <XCEngine/Memory/ProxyAllocator.h>
+
+{
+    MemoryManager::Get().Initialize();
+    IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
+    
+    auto proxy = MemoryManager::Get().CreateProxyAllocator("TrackedAlloc");
+    proxy->Allocate(1024);
+    
+    // proxy 超出作用域时自动销毁
+    // 底层 sysAlloc 仍有效
+    
+    MemoryManager::Get().Shutdown();
+}
+```
+
+## 相关文档
+
+- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览