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

.trae/documents/fix_doc_link_matching_plan.md

@@ -0,0 +1,82 @@
+# 修复文档链接匹配逻辑计划
+
+## 1. 问题分析
+用户反馈点击 `rhi/buffer/d3d12/buffer.md` 中的 `[Initialize](initialize.md)` 链接时，错误跳转到了 `Logger::Initialize`（可能位于其他目录）。
+经过检查 `src/components/ApiDocViewer.tsx` 中的 `handleReferenceClick` 方法：
+
+```typescript
+  const handleReferenceClick = useCallback((href: string) => {
+    const ref = href.replace(/\.md$/, '')
+    const match = externalDocs.find(d => {
+      const docPath = d.relativePath.replace(/\.md$/, '')
+      return docPath === ref || docPath.endsWith('/' + ref.split('/').pop())
+    })
+    if (match) {
+      setSelectedPath(match.relativePath)
+      setCurrentContent(match.content)
+    }
+  }, [externalDocs])
+```
+
+当前的匹配逻辑非常危险：`docPath.endsWith('/' + ref.split('/').pop())` 这一行意味着只要文件名匹配（例如 `initialize.md`），不管它在哪个目录下，都可能被匹配到。这导致了跨目录的同名文件匹配错误。
+
+## 2. 修复方案
+
+### 修改文件: `src/components/ApiDocViewer.tsx`
+
+我们需要实现基于当前文档路径的相对路径解析逻辑。由于 `handleReferenceClick` 目前只接收 `href`，我们需要让它知道当前所在的文档路径（`selectedPath`），以便正确解析相对路径。
+
+1. **依赖当前路径**：确保 `handleReferenceClick` 能访问到 `selectedPath`。
+2. **实现相对路径解析**：
+   - 如果链接以 `/` 开头，视为基于文档根目录的绝对路径。
+   - 如果是相对路径（`./`、`../` 或直接文件名），则基于当前文档的目录进行解析。
+   - 解析出目标文件的完整 `relativePath` 后，再在 `externalDocs` 中查找精确匹配。
+
+**修改后的逻辑伪代码**：
+```typescript
+  const handleReferenceClick = useCallback((href: string) => {
+    // 1. 获取当前文档所在的目录
+    const currentDir = selectedPath ? selectedPath.split('/').slice(0, -1).join('/') : '';
+    
+    // 2. 解析目标路径
+    let targetPath = '';
+    if (href.startsWith('/')) {
+        // 绝对路径（相对于文档根目录）
+        targetPath = href.slice(1);
+    } else {
+        // 相对路径处理
+        const parts = currentDir ? currentDir.split('/') : [];
+        const hrefParts = href.split('/');
+        
+        for (const part of hrefParts) {
+            if (part === '.') continue;
+            if (part === '..') {
+                parts.pop();
+            } else {
+                parts.push(part);
+            }
+        }
+        targetPath = parts.join('/');
+    }
+    
+    // 3. 规范化目标路径（移除 .md 后缀以便对比，或者直接对比全名）
+    // 考虑到 externalDocs 中的 relativePath 包含 .md，我们也应该构造包含 .md 的路径
+    if (!targetPath.endsWith('.md')) {
+        targetPath += '.md';
+    }
+
+    // 4. 精确查找
+    const match = externalDocs.find(d => d.relativePath === targetPath);
+    
+    if (match) {
+      setSelectedPath(match.relativePath)
+      setCurrentContent(match.content)
+    } else {
+       console.warn(`Document not found: ${targetPath}`);
+    }
+  }, [externalDocs, selectedPath]) // 添加 selectedPath 依赖
+```
+
+## 3. 影响与验证
+- **影响**：修复了所有相对路径链接的跳转逻辑，不再会出现跨目录同名文件乱跳的情况。
+- **验证**：点击 `rhi/buffer/d3d12/buffer.md` 中的 `initialize.md`，应该正确跳转到同目录下的 `rhi/buffer/d3d12/initialize.md`。

.trae/documents/fix_link_color_plan.md

@@ -0,0 +1,68 @@
+# 修复文档内代码块中链接样式失效问题
+
+## 1. 问题分析
+用户反馈“有的是蓝色，有的没有颜色（普通文本）”。
+在 Markdown 文档（特别是 API 文档）中，链接经常出现在代码块或表格内。例如：
+`[`Initialize`](initialize.md)`
+
+在 `DocContent.tsx` 中，我们对 `code` 标签有自定义渲染逻辑：
+```typescript
+    code: ({ className, children, ...props }) => {
+      const match = /language-(\w+)/.exec(className || '')
+      if (match) {
+        // ... 代码高亮块 ...
+      }
+      // 行内代码
+      return (
+        <code className="text-zinc-300 font-mono text-lg" {...props}>
+          {children}
+        </code>
+      )
+    },
+```
+
+当 Markdown 解析器遇到 `[`Initialize`](initialize.md)` 时，它会生成：
+```html
+<a href="initialize.md"><code>Initialize</code></a>
+```
+或者（取决于解析器行为）
+```html
+<code><a href="initialize.md">Initialize</a></code>
+```
+但在 `react-markdown` 中，通常链接包裹内容。如果链接内部包含 `code` 标签，`code` 标签的样式（`text-zinc-300`）可能会覆盖外层 `a` 标签的颜色样式（`text-blue-500`）。
+CSS 中，子元素的 `color` 属性通常会覆盖父元素的 `color`。这里 `code` 组件显式设置了 `text-zinc-300`（灰色），导致包裹在链接里的代码块显示为灰色，看起来像没有颜色的普通文本。
+
+## 2. 修复方案
+
+### 修改文件: `src/components/DocContent.tsx`
+
+我们需要调整 `code` 组件的样式逻辑。如果 `code` 标签被包裹在 `a` 标签中，它应该继承父元素的颜色，而不是强制使用 `text-zinc-300`。
+但在 `react-markdown` 的组件渲染中，子组件很难直接知道父组件是谁。
+
+**替代方案**：利用 CSS 的 `inherit` 特性或移除显式的颜色类。
+更稳妥的方法是：修改 `code` 组件的 `className`，让它不强制设置颜色，或者仅在非链接环境下设置颜色。
+或者，我们可以给 `a` 标签内的内容强制应用蓝色。
+
+**最佳实践**：
+修改 `code` 组件的渲染，不再强制 `text-zinc-300`，而是使用一个默认颜色，但允许被父级覆盖。或者，我们在 `a` 组件中，给子元素强制颜色。
+
+鉴于 `react-markdown` 的结构，最简单有效的方法是在 `code` 组件中移除 `text-zinc-300`，改为使用 `bg-zinc-800` 等背景色来区分代码块，字体颜色让其继承或使用更弱的默认值。
+但为了保持非链接代码块的灰色外观，我们可以尝试在 CSS (Tailwind) 中使用 `group` 或直接在 `a` 标签样式中强制子元素颜色。
+
+**修改计划**：
+1. 修改 `a` 组件：添加 `group` 类。
+2. 修改 `code` 组件：添加 `group-hover:text-blue-400` (这可能不行，因为 code 不是 a 的直接子组件，react 渲染树中它们是分离的组件函数)。
+
+**更直接的方案**：
+在 `code` 组件中，移除 `text-zinc-300`，改为 `text-inherit` 或者不设置颜色类（让其继承），然后在全局或父级容器设置默认文本颜色。
+或者，简单粗暴地：在 `a` 标签的 `className` 中添加 `[&>code]:text-blue-500` (Tailwind 任意变体语法)，强制 `a` 标签下的 `code` 元素变成蓝色。
+
+```typescript
+// 在 a 标签组件中
+className="text-blue-500 hover:text-blue-400 transition-colors cursor-pointer [&>code]:text-blue-500 [&>code]:hover:text-blue-400"
+```
+这样可以确保链接内的代码块也显示为蓝色。
+
+## 3. 影响与验证
+- **影响**：所有被链接包裹的行内代码块（如 `[`Code`](link)`）都将变为蓝色，表明它们是可点击的链接。普通行内代码块保持原样（如果它们不在 a 标签内）。
+- **验证**：查看包含 `[`Initialize`](...)` 的文档，确认 "Initialize" 显示为蓝色且可点击。

.trae/documents/fix_link_navigation_plan.md

@@ -0,0 +1,57 @@
+# 修复文档内链接跳转白屏问题计划
+
+## 1. 问题分析
+用户反馈“点击链接直接白屏了”。这是因为在 Markdown 文档内容中，部分相对链接（例如 `[Some Doc](SomeDoc.md)`）没有以 `./` 或 `../` 开头。
+目前的 `DocContent.tsx` 组件在渲染 `<a>` 标签时，仅拦截了以 `./` 或 `../` 开头的链接。对于其他格式的本地链接，它会渲染为原生的 `<a href="SomeDoc.md">` 标签。
+在 Electron 或单页应用（SPA）中，点击原生链接会触发浏览器的默认导航行为，试图跳转到该文件路径，从而导致 React 应用被卸载（变成白屏或显示 404/纯文本）。
+
+以前用户可以通过左侧树直接点击叶子节点查看文档，但在我们隐藏了叶子节点后，用户必须依赖文档内的链接进行导航，导致这个原本就存在的链接跳转问题暴露了出来。
+
+## 2. 修改方案
+
+### 修改文件: `src/components/DocContent.tsx`
+调整 Markdown 中 `<a>` 标签的渲染逻辑，拦截所有本地链接，阻止默认的页面跳转行为，并将其交给内部的 `onReferenceClick` 处理：
+
+1. **识别内部链接**：
+   判断 `href` 是否存在，且**不以** `http://`、`https://`、`mailto:` 或 `#` 开头。满足此条件的都视为内部文档链接。
+   
+2. **阻止默认行为并触发内部跳转**：
+   对于内部链接，渲染为 `<a>` 标签，但在 `onClick` 事件中调用 `e.preventDefault()` 阻止白屏跳转，随后调用 `onReferenceClick(href)`。
+
+```typescript
+    a: ({ href, children }) => {
+      // 判断是否是内部链接：非 http/https，非邮箱，非页内锚点
+      const isInternal = href && !href.startsWith('http') && !href.startsWith('mailto:') && !href.startsWith('#');
+      
+      if (isInternal) {
+        return (
+          <a
+            href={href}
+            onClick={(e) => {
+              e.preventDefault();
+              onReferenceClick(href);
+            }}
+            className="text-blue-500 hover:text-blue-400 transition-colors cursor-pointer"
+          >
+            {children}
+          </a>
+        )
+      }
+      
+      // 外部链接保留默认行为，但新窗口打开更安全
+      return (
+        <a 
+          href={href} 
+          target="_blank" 
+          rel="noopener noreferrer" 
+          className="text-blue-500 hover:text-blue-400 transition-colors"
+        >
+          {children}
+        </a>
+      )
+    },
+```
+
+## 3. 影响与验证
+- **影响**：所有的内部 Markdown 链接现在都会通过 React 状态更新右侧内容，而不会触发导致白屏的浏览器原生导航。
+- **验证**：保存修改后，点击文档内部的普通文件名链接（如 `SomeDoc.md`），页面将平滑切换到目标文档内容，不再出现白屏崩溃现象。

.trae/documents/hide_leaf_nodes_plan.md

@@ -0,0 +1,39 @@
+# 隐藏层级树叶子节点实现计划
+
+## 1. 目标概述
+在 API 文档界面的左侧层级树（`DocTree` 组件）中，隐藏所有的叶子节点（即具体的 Markdown 文件），使目录树仅展示文件夹（目录）结构。
+
+## 2. 现状分析
+- 目前 `src/components/DocTree.tsx` 中的 `DocTree` 和 `TreeNode` 组件会无差别地渲染所有传入的节点（包含文件夹和文件）。
+- 树状图的连线UI（如 `├─` 和 `└─`）依赖于数组的索引和长度（`isLast` 属性）。如果仅在渲染时隐式返回 `null`，会导致连线计算错误。
+- 在当前的交互中，点击文件夹会默认打开与文件夹同名的 Markdown 索引文件（此时 `selectedPath` 是该 `.md` 文件的路径）。如果隐藏了文件节点，需要确保此时对应的文件夹能被正确高亮显示。
+
+## 3. 具体修改方案
+
+### 修改文件: `src/components/DocTree.tsx`
+
+**1. 过滤子节点并修复连线逻辑 (在 `TreeNode` 组件中)**
+- 在渲染子节点之前，先过滤出 `isDir === true` 的节点：
+  ```typescript
+  const visibleChildren = file.children?.filter(c => c.isDir)
+  const showChildren = isDir && isExpanded && visibleChildren && visibleChildren.length > 0
+  ```
+- 在 `visibleChildren.map` 中渲染子节点，并基于 `visibleChildren.length` 来计算 `isLast`，确保树状图的连线完美闭合。
+
+**2. 完善文件夹高亮逻辑 (在 `TreeNode` 组件中)**
+- 修改 `isSelected` 的判断，使得当子文件（与文件夹同名的索引文档）被选中时，该文件夹节点也能呈现高亮状态：
+  ```typescript
+  const isSelected = selectedPath === file.relativePath || 
+    (isDir && selectedPath === `${file.relativePath}/${file.name}.md`)
+  ```
+
+**3. 过滤根节点 (在 `DocTree` 组件中)**
+- 在渲染根层级前过滤出文件夹：
+  ```typescript
+  const visibleFiles = files.filter(f => f.isDir)
+  ```
+- 基于 `visibleFiles` 遍历并传递正确的 `isLast` 属性。
+
+## 4. 影响与验证
+- **影响**：所有的独立 `.md` 文件将不再出现在左侧树中，用户需要通过点击目录（加载索引页）和页面内的文档链接来进行页面导航。
+- **验证**：保存修改后，左侧目录树将只显示文件夹图标/层级；连线正常；点击文件夹后，当前文件夹名称会变为高亮蓝色（`text-blue-400`）。

docs/api/containers/array/array.md

@@ -0,0 +1,67 @@
+# Array
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板动态数组容器，提供自动扩容的数组实现。
+
+## 概述
+
+`Array<T>` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `T*` | 迭代器类型 |
+| `ConstIterator` | `const T*` | 常量迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造数组实例 |
+| [Copy/Move Constructor](copy-move-constructor.md) | 拷贝或移动构造 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [operator[]](operator-subscript.md) | 下标访问 |
+| [Data](data.md) | 获取原始数据指针 |
+| [Front/Back](front-back.md) | 获取首/尾元素引用 |
+| [Size/Capacity/Empty](size.md) | 获取尺寸信息 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Reserve](reserve.md) | 预留容量 |
+| [Resize](resize.md) | 调整大小 |
+| [PushBack](pushback.md) | 尾部添加（拷贝/移动） |
+| [EmplaceBack](emplaceback.md) | 就地构造尾部添加 |
+| [PopBack](popback.md) | 尾部移除 |
+| [begin/end](iterator.md) | 获取迭代器 |
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/Array.h>
+
+// 基本用法
+XCEngine::Containers::Array<int> arr;
+arr.PushBack(1);
+arr.PushBack(2);
+arr.PushBack(3);
+
+// 使用 initializer_list
+XCEngine::Containers::Array<int> arr2 = {1, 2, 3, 4, 5};
+
+// 迭代
+for (auto& elem : arr) {
+    printf("%d\n", elem);
+}
+
+// 使用 EmplaceBack
+arr.EmplaceBack(4);
+```
+
+## 相关文档
+
+- [HashMap](../hashmap/hashmap.md) - 哈希表容器
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/array/clear.md

@@ -0,0 +1,36 @@
+# Array::Clear()
+
+```cpp
+void Clear();
+```
+
+清空数组中的所有元素。
+
+**行为：**
+- 调用所有元素的析构函数
+- 将 `Size()` 设为 0
+- **不释放底层内存**，`Capacity()` 保持不变
+
+**线程安全：** ❌ 清空期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3, 4, 5};
+
+arr.Size();      // 5
+arr.Capacity();  // 8（假设自动扩容到 8）
+
+arr.Clear();
+
+arr.Size();      // 0
+arr.Capacity();  // 8（内存未被释放）
+
+// 可继续添加元素，不会重新分配内存
+arr.PushBack(10);
+arr.PushBack(20);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/constructor.md

@@ -0,0 +1,44 @@
+# Array::Array()
+
+```cpp
+Array() = default;
+explicit Array(size_t capacity);
+Array(size_t count, const T& value);
+Array(std::initializer_list<T> init);
+```
+
+构造一个 `Array<T>` 实例。
+
+**默认构造**：构造空数组，不分配内存。
+
+**容量构造**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。
+
+**数量构造**：创建 `count` 个元素，每个元素都是 `value` 的拷贝。使用拷贝构造，不调用默认构造。
+
+**初始化列表构造**：使用 C++ initializer_list 语法创建数组。
+
+**参数：**
+- `capacity` - 预分配的容量大小
+- `count` - 元素数量
+- `value` - 每个元素的初始值
+- `init` - initializer_list 初始化列表
+
+**示例：**
+
+```cpp
+// 默认构造
+Containers::Array<int> arr1;
+
+// 预分配容量（不设置元素）
+Containers::Array<int> arr2(100);
+
+// 创建 10 个元素，初始值为 42
+Containers::Array<int> arr3(10, 42);
+
+// 使用 initializer_list
+Containers::Array<int> arr4 = {1, 2, 3, 4, 5};
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/copy-move-constructor.md

@@ -0,0 +1,44 @@
+# Array::Array() - 拷贝/移动构造
+
+```cpp
+Array(const Array& other);
+Array(Array&& other) noexcept;
+```
+
+拷贝或移动构造一个新数组。
+
+**拷贝构造：**
+- 分配与 `other` 相同容量的内存
+- 拷贝 `other` 中所有元素
+
+**移动构造：**
+- 接管 `other` 的所有资源（数据指针、容量、大小）
+- 将 `other` 置为空状态（`m_data = nullptr, m_size = 0, m_capacity = 0`）
+- 不拷贝、不移动任何元素数据，性能 O(1)
+
+**参数：**
+- `other` - 源数组
+
+**异常：**
+- 拷贝构造：元素拷贝可能抛出异常
+- 移动构造：`noexcept`，不抛出异常
+
+**线程安全：** ❌ 构造期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+
+// 拷贝构造
+Containers::Array<int> arr2(arr1);    // arr2 = {1, 2, 3}
+
+// 移动构造
+Containers::Array<int> arr3(std::move(arr1));
+// arr3 = {1, 2, 3}
+// arr1 现在为空，Size() == 0
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/data.md

@@ -0,0 +1,30 @@
+# Array::Data()
+
+```cpp
+T* Data();
+const T* Data() const;
+```
+
+获取指向底层数组数据的原始指针。
+
+**用途：** 用于与 C 风格 API 或需要直接访问内存的场景（如与 GPU 通信）。
+
+**返回：** 指向底层连续内存块的指针。如果数组为空，返回 `nullptr`。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<float> arr = {1.0f, 2.0f, 3.0f};
+
+float* raw = arr.Data();
+size_t count = arr.Size();
+
+// 可用于与 C API 交互
+// memcpy(dst, arr.Data(), arr.Size() * sizeof(float));
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/destructor.md

@@ -0,0 +1,28 @@
+# Array::~Array()
+
+```cpp
+~Array();
+```
+
+销毁数组，释放所有已分配的元素并释放内存。
+
+**行为：**
+- 调用所有元素的析构函数
+- 释放底层数据缓冲区内存
+
+**注意：** 使用 RAII 模式，无需手动调用析构。
+
+**线程安全：** ❌ 析构期间不可并发访问
+
+**示例：**
+
+```cpp
+{
+    Containers::Array<int> arr = {1, 2, 3};
+    // 使用 arr...
+} // arr 在此自动销毁，析构函数被调用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/emplaceback.md

@@ -0,0 +1,47 @@
+# Array::EmplaceBack()
+
+```cpp
+template<typename... Args>
+T& EmplaceBack(Args&&... args);
+```
+
+在数组末尾就地构造一个元素，直接在内存中构造，不产生临时对象。
+
+**优势：**
+- 避免拷贝或移动开销
+- 直接在底层缓冲区末尾构造元素
+- 参数完美转发，支持任意构造参数
+
+**参数：**
+- `args` - 转发给 `T` 构造函数的参数包
+
+**返回：** 新构造元素的引用
+
+**复杂度：** 均摊 O(1)
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+struct Vertex {
+    float x, y, z;
+    Vertex(float x_, float y_, float z_) : x(x_), y(y_), z(z_) {}
+};
+
+Containers::Array<Vertex> vertices;
+
+// EmplaceBack 直接构造，不产生临时 Vertex 对象
+vertices.EmplaceBack(1.0f, 2.0f, 3.0f);
+vertices.EmplaceBack(4.0f, 5.0f, 6.0f);
+
+// 对比 PushBack（需要先构造临时对象）
+Vertex v(7.0f, 8.0f, 9.0f);
+vertices.PushBack(v);  // 产生拷贝或移动
+
+// EmplaceBack 更高效，始终优先使用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/front-back.md

@@ -0,0 +1,38 @@
+# Array::Front() / Back()
+
+```cpp
+T& Front();
+const T& Front() const;
+T& Back();
+const T& Back() const;
+```
+
+获取数组首尾元素的引用。
+
+**Front()：** 返回第一个元素（`index == 0`）的引用。
+
+**Back()：** 返回最后一个元素（`index == Size() - 1`）的引用。
+
+**前置条件：** 数组必须非空，否则行为未定义。
+
+**返回：** 首/尾元素的引用
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问期间不可并发修改
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int& first = arr.Front();   // first == 10
+int& last = arr.Back();     // last == 30
+
+arr.Front() = 5;            // arr 现在是 {5, 20, 30}
+arr.Back() = 100;           // arr 现在是 {5, 20, 100}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/iterator.md

@@ -0,0 +1,45 @@
+# Array::begin() / end()
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取数组的迭代器，用于范围遍历。
+
+**begin()：** 返回指向第一个元素的迭代器。如果数组为空，返回值等于 `end()`。
+
+**end()：** 返回指向"最后一个元素之后"位置的迭代器（哨兵）。这是一个越界位置，不可解引用。
+
+**迭代器类型：** `Iterator = T*`（原始指针），因此支持指针算术运算。
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 迭代期间不可并发修改数组
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+// 范围 for 循环（推荐）
+for (int val : arr) {
+    printf("%d\n", val);
+}
+
+// 手动迭代器
+for (auto it = arr.begin(); it != arr.end(); ++it) {
+    printf("%d\n", *it);
+}
+
+// 指针算术（因为迭代器就是指针）
+int* ptr = arr.begin();
+ptr += 2;  // 指向第三个元素
+*ptr;       // 30
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/operator-assign.md

@@ -0,0 +1,44 @@
+# Array::operator=
+
+```cpp
+Array& operator=(const Array& other);
+Array& operator=(Array&& other) noexcept;
+```
+
+赋值运算符，用另一个数组的内容替换当前数组的内容。
+
+**拷贝赋值（`=`）：**
+- 先销毁当前所有元素
+- 分配与 `other` 相同大小的内存
+- 拷贝 `other` 中所有元素
+
+**移动赋值（`=`）：**
+- 先销毁当前所有元素
+- 接管 `other` 的所有资源（数据指针、容量）
+- 将 `other` 置为空状态
+
+**参数：**
+- `other` - 源数组
+
+**返回：** 引用自身（`*this`）
+
+**异常：**
+- 拷贝赋值：`other` 元素拷贝可能抛出异常
+
+**线程安全：** ❌ 赋值期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+Containers::Array<int> arr2;
+
+arr2 = arr1;      // 拷贝赋值，arr2 现在是 {1, 2, 3}
+
+Containers::Array<int> arr3 = {4, 5};
+arr2 = std::move(arr3); // 移动赋值，arr2 现在是 {4, 5}，arr3 为空
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/operator-subscript.md

@@ -0,0 +1,39 @@
+# Array::operator[]
+
+```cpp
+T& operator[](size_t index);
+const T& operator[](size_t index) const;
+```
+
+按下标访问数组元素，不进行边界检查。
+
+**行为：**
+- 返回指定索引处元素的引用
+- 不进行下标越界检查，性能最优
+- 可用于读取和修改元素（非常量版本）
+
+**参数：**
+- `index` - 元素下标，从 0 开始
+
+**返回：** 元素的引用（常量版本返回常量引用）
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问元素期间不可并发修改
+
+**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请使用 `At()` 方法（如果存在）或自行检查。
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int first = arr[0];     // first == 10
+int last = arr[2];       // last == 30
+
+arr[1] = 25;            // arr 现在是 {10, 25, 30}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/popback.md

@@ -0,0 +1,38 @@
+# Array::PopBack()
+
+```cpp
+void PopBack();
+```
+
+移除数组末尾的元素，并调用其析构函数。
+
+**前置条件：** 数组必须非空（`Size() > 0`）。如果数组为空，行为未定义。
+
+**行为：**
+- 将 `Size()` 减 1
+- 调用被移除元素的析构函数
+- **不释放底层内存**
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+arr.Size();  // 5
+
+arr.PopBack();  // 移除 50
+
+arr.Size();  // 4
+// arr = {10, 20, 30, 40}
+
+arr.PopBack();
+arr.PopBack();
+// arr = {10, 20}
+// Capacity() 仍为之前的值（如 8）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/pushback.md

@@ -0,0 +1,43 @@
+# Array::PushBack()
+
+```cpp
+void PushBack(const T& value);
+void PushBack(T&& value);
+```
+
+在数组末尾添加一个元素。
+
+**拷贝版本（`const T&`）：**
+- 如果容量不足（`Size() >= Capacity()`），先扩容（容量翻倍）
+- 在末尾位置拷贝构造 `value`
+
+**移动版本（`T&&`）：**
+- 行为同拷贝版本，但使用移动构造
+- 适用于临时对象或右值，避免拷贝开销
+
+**参数：**
+- `value` - 要添加的元素（拷贝或移动）
+
+**复杂度：** 均摊 O(1)。每次添加的摊销成本为常数，因为扩容是翻倍策略。
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<std::string> arr;
+
+// 拷贝添加
+std::string s = "hello";
+arr.PushBack(s);           // s 被拷贝
+
+// 移动添加（更高效）
+arr.PushBack(std::string("world"));  // 直接移动构造
+
+// 临时对象会被隐式移动
+arr.PushBack("temporary"); // 字符串字面量构造后移动
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/reserve.md

@@ -0,0 +1,39 @@
+# Array::Reserve()
+
+```cpp
+void Reserve(size_t capacity);
+```
+
+预分配底层内存容量，确保能容纳至少 `capacity` 个元素而不重新分配。
+
+**行为：**
+- 如果 `capacity > Capacity()`，分配新的内存（容量翻倍策略）
+- 如果 `capacity <= Capacity()`，什么都不做
+- 不改变 `Size()`
+
+**参数：**
+- `capacity` - 目标容量
+
+**用途：** 当已知大致元素数量时，提前分配可以避免多次重新分配带来的性能开销和迭代器失效。
+
+**复杂度：** O(n)，其中 n 为当前元素数量（需要拷贝现有元素到新内存）
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+// 预分配 1000 个元素的容量
+arr.Reserve(1000);
+
+// 之后添加 500 个元素不会触发重新分配
+for (int i = 0; i < 500; ++i) {
+    arr.PushBack(i);
+}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/resize.md

@@ -0,0 +1,46 @@
+# Array::Resize()
+
+```cpp
+void Resize(size_t newSize);
+void Resize(size_t newSize, const T& value);
+```
+
+调整数组大小。
+
+**Resize(newSize)：**
+- 如果 `newSize > Size()`：在末尾构造 `newSize - Size()` 个默认构造的元素
+- 如果 `newSize < Size()`：销毁末尾多出的元素
+- 如果 `newSize == Size()`：什么都不做
+
+**Resize(newSize, value)：**
+- 行为同上述，但扩展时使用 `value` 拷贝构造新元素，而非默认构造
+
+**参数：**
+- `newSize` - 新的元素数量
+- `value` - 扩展时用作填充值的元素
+
+**复杂度：** O(n)，涉及元素构造/析构和可能的内存重新分配
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3};
+
+// 扩展到 5 个元素，新元素默认构造为 0
+arr.Resize(5);
+// arr = {1, 2, 3, 0, 0}
+
+// 缩减到 2 个元素
+arr.Resize(2);
+// arr = {1, 2}
+
+// 扩展到 4 个，填充为 -1
+arr.Resize(4, -1);
+// arr = {1, 2, -1, -1}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/setallocator.md

@@ -0,0 +1,38 @@
+# Array::SetAllocator()
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置数组使用的内存分配器。
+
+**用途：** 允许自定义内存分配策略，如使用对象池、固定大小分配器或调试分配器。
+
+**参数：**
+- `allocator` - 指向 `Memory::IAllocator` 接口的指针。如果为 `nullptr`，使用默认 `::operator new/delete`。
+
+**注意：**
+- 如果数组已有元素，设置新的分配器后，**不会**迁移现有元素
+- 仅影响后续的内存分配操作
+- 通常在构造后立即调用，或在数组为空时调用
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+// 使用线性分配器（适合帧分配）
+auto* linear = new Memory::LinearAllocator(1024 * 1024);
+
+Containers::Array<int> arr;
+arr.SetAllocator(linear);
+
+// 使用对象池分配器
+auto* pool = new Memory::PoolAllocator(sizeof(MyObject), 100);
+Containers::Array<MyObject> objects;
+objects.SetAllocator(pool);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/size.md

@@ -0,0 +1,47 @@
+# Array::Size() / Capacity() / Empty()
+
+```cpp
+size_t Size() const;
+size_t Capacity() const;
+bool Empty() const;
+```
+
+获取数组的尺寸信息。
+
+**Size()：** 返回数组中的实际元素数量。
+
+**Capacity()：** 返回底层内存缓冲区能容纳的元素数量，不一定等于 `Size()`。
+
+**Empty()：** 返回数组是否为空（`Size() == 0`）。等价于 `Size() == 0`，但更语义化。
+
+**返回：**
+- `Size()` - 元素数量
+- `Capacity()` - 底层缓冲区容量
+- `Empty()` - 是否为空
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+arr.Size();      // 0
+arr.Capacity();  // 0
+arr.Empty();     // true
+
+arr.PushBack(1);
+arr.PushBack(2);
+
+arr.Size();      // 2
+arr.Capacity();  // 4（自动扩容）
+arr.Empty();     // false
+
+arr.Reserve(100);
+arr.Size();      // 2（元素数量不变）
+arr.Capacity();  // 100（容量增加）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/containers.md

@@ -0,0 +1,57 @@
+# Containers 容器模块概览
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `module`
+
+**描述**: XCEngine 的容器模块，提供常用的数据结构实现。
+
+## 概述
+
+Containers 模块提供了图形引擎常用的数据结构，包括动态数组、字符串和哈希表。这些容器都使用自定义内存分配器接口，支持内存跟踪和优化。
+
+## 模块内容
+
+### 容器类
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Array](array/array.md) | `Array.h` | 模板动态数组，支持自动扩容 |
+| [String](string/string.md) | `String.h` | 动态字符串类 |
+| [HashMap](hashmap/hashmap.md) | `HashMap.h` | 模板哈希表 |
+
+## 设计特点
+
+1. **自定义内存分配器支持** - 所有容器都支持通过 `IAllocator` 接口分配内存
+2. **迭代器支持** - Array 和 HashMap 都提供 STL 风格的迭代器
+3. **移动语义** - 完整支持 C++11 移动语义
+4. **异常安全** - 内存分配失败时提供良好的错误处理
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/Array.h>
+#include <XCEngine/Containers/String.h>
+#include <XCEngine/Containers/HashMap.h>
+
+// 使用 Array
+XCEngine::Containers::Array<int> arr;
+arr.PushBack(1);
+arr.PushBack(2);
+arr.PushBack(3);
+
+// 使用 String
+XCEngine::Containers::String str;
+str = "Hello, ";
+str += "World!";
+
+// 使用 HashMap
+XCEngine::Containers::HashMap<XCEngine::Containers::String, int> map;
+map.Insert("key1", 100);
+map.Insert("key2", 200);
+int* value = map.Find("key1");
+```
+
+## 相关文档
+
+- [Memory 模块](../memory/memory.md) - 内存分配器接口

docs/api/containers/hashmap/clear.md

@@ -0,0 +1,34 @@
+# HashMap::Clear
+
+```cpp
+void Clear();
+```
+
+清空哈希表中的所有元素，将元素数量置为 0。桶的数量保持不变。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(m_bucketCount)，需要清空所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+std::cout << "Size before clear: " << map.Size() << std::endl; // 输出 3
+
+map.Clear();
+
+std::cout << "Size after clear: " << map.Size() << std::endl; // 输出 0
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Erase](erase.md) - 删除单个元素

docs/api/containers/hashmap/constructor.md

@@ -0,0 +1,31 @@
+# HashMap::HashMap
+
+```cpp
+HashMap();
+explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr);
+```
+
+构造哈希表实例。
+
+**参数：**
+- `bucketCount` - 初始桶的数量，默认为 16。若传入 0，则自动调整为 16。
+- `allocator` - 内存分配器指针，默认为 `nullptr`（使用默认分配器）。
+
+**返回：** 无
+
+**复杂度：** O(bucketCount)，需要初始化所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+
+XCEngine::Containers::HashMap<int, const char*> map2(32);
+
+auto customAllocator = XCEngine::Memory::GetDefaultAllocator();
+XCEngine::Containers::HashMap<int, const char*> map3(64, customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/contains.md

@@ -0,0 +1,35 @@
+# HashMap::Contains
+
+```cpp
+bool Contains(const Key& key) const;
+```
+
+检查哈希表中是否包含指定的键。
+
+**参数：**
+- `key` - 要检查的键
+
+**返回：** 如果键存在返回 `true`，否则返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+if (map.Contains(1)) {
+    std::cout << "Key 1 exists" << std::endl; // 输出 "Key 1 exists"
+}
+
+if (!map.Contains(99)) {
+    std::cout << "Key 99 does not exist" << std::endl; // 输出 "Key 99 does not exist"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值

docs/api/containers/hashmap/copy-move.md

@@ -0,0 +1,34 @@
+# HashMap::Copy/Move 构造
+
+```cpp
+HashMap(const HashMap& other);
+HashMap(HashMap&& other) noexcept;
+```
+
+拷贝构造和移动构造。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 无（构造函数）
+
+**复杂度：**
+- 拷贝构造：O(m_bucketCount + other.m_size)
+- 移动构造：O(m_bucketCount)，移动构造需要遍历所有桶以重新建立桶的指针关系
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map1;
+map1.Insert(1, "hello");
+map1.Insert(2, "world");
+
+XCEngine::Containers::HashMap<int, std::string> map2(map1); // 拷贝构造
+
+XCEngine::Containers::HashMap<int, std::string> map3(std::move(map1)); // 移动构造，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator=](operator-assign.md) - 赋值运算符

docs/api/containers/hashmap/destructor.md

@@ -0,0 +1,27 @@
+# HashMap::~HashMap
+
+```cpp
+~HashMap();
+```
+
+析构函数，清空所有元素并释放资源。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)，需要清空所有桶中的元素
+
+**示例：**
+
+```cpp
+{
+    XCEngine::Containers::HashMap<int, std::string> map;
+    map.Insert(1, "hello");
+    map.Insert(2, "world");
+} // map 在此自动析构，所有资源被正确释放
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/erase.md

@@ -0,0 +1,37 @@
+# HashMap::Erase
+
+```cpp
+bool Erase(const Key& key);
+```
+
+删除指定键对应的元素。
+
+**参数：**
+- `key` - 要删除的键
+
+**返回：** 如果元素被删除返回 `true`，如果键不存在返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+bool erased = map.Erase(2); // 返回 true
+
+if (!map.Contains(2)) {
+    std::cout << "Key 2 removed" << std::endl; // 输出 "Key 2 removed"
+}
+
+bool notErased = map.Erase(99); // 返回 false，键不存在
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Insert](insert.md) - 插入键值对
+- [Clear](clear.md) - 清空所有元素

docs/api/containers/hashmap/find.md

@@ -0,0 +1,39 @@
+# HashMap::Find
+
+```cpp
+Value* Find(const Key& key);
+const Value* Find(const Key& key) const;
+```
+
+根据键查找对应的值指针。
+
+**参数：**
+- `key` - 要查找的键
+
+**返回：** 如果找到，返回指向值的指针；否则返回 `nullptr`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+const char* value1 = map.Find(1);
+if (value1) {
+    std::cout << "Found: " << value1 << std::endl; // 输出 "Found: one"
+}
+
+const char* value2 = map.Find(99);
+if (!value2) {
+    std::cout << "Not found" << std::endl; // 输出 "Not found"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Contains](contains.md) - 检查是否包含键
+- [operator[]](./operator-subscript.md) - 下标访问

docs/api/containers/hashmap/hashmap.md

@@ -0,0 +1,80 @@
+# HashMap
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板哈希表容器，提供键值对存储和快速查找。
+
+## 概述
+
+`HashMap<Key, Value>` 是一个模板哈希表容器，使用动态数组作为桶来解决哈希冲突，支持键值对的插入、查找和删除操作。
+
+## 公共类型
+
+### Pair
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `first` | `Key` | 键 |
+| `second` | `Value` | 值 |
+
+### 迭代器
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `typename Array<Pair>::Iterator` | 迭代器类型 |
+| `ConstIterator` | `typename Array<Pair>::ConstIterator` | 常量迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造哈希表实例 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [Copy/Move](copy-move.md) | 拷贝/移动构造 |
+| [operator[]](operator-subscript.md) | 下标访问（不存在时插入） |
+| [Find](find.md) | 查找键对应的值指针 |
+| [Contains](contains.md) | 检查是否包含键 |
+| [Insert](insert.md) | 插入键值对 |
+| [Erase](erase.md) | 删除键对应的元素 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Size/Empty](size.md) | 获取元素数量 |
+| [begin/end](iterator.md) | 获取迭代器 |
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/HashMap.h>
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::HashMap<int, const char*> map;
+
+    map.Insert(1, "one");
+    map.Insert(2, "two");
+    map.Insert(3, "three");
+
+    if (const char* value = map.Find(1)) {
+        std::cout << "Key 1: " << value << std::endl;
+    }
+
+    std::cout << "Size: " << map.Size() << std::endl;
+
+    for (auto it = map.begin(); it != map.end(); ++it) {
+        std::cout << it->first << " -> " << it->second << std::endl;
+    }
+
+    map.Erase(2);
+    std::cout << "Contains 2: " << (map.Contains(2) ? "yes" : "no") << std::endl;
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Array](../array/array.md) - 动态数组
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/hashmap/insert.md

@@ -0,0 +1,38 @@
+# HashMap::Insert
+
+```cpp
+bool Insert(const Key& key, const Value& value);
+bool Insert(const Key& key, Value&& value);
+bool Insert(Pair&& pair);
+```
+
+插入键值对。如果键已存在，则更新其值并返回 `false`；否则插入新元素并返回 `true`。
+
+**参数：**
+- `key` - 要插入的键
+- `value` - 要插入的值（const 版本为拷贝，&& 版本为移动）
+- `pair` - 包含键值对的 `Pair` 结构（右值）
+
+**返回：** 如果插入成功（键不存在）返回 `true`，如果键已存在（更新值）返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（包括可能的 rehash）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+bool inserted1 = map.Insert(1, "one");   // 返回 true
+bool inserted2 = map.Insert(1, "ONE");   // 返回 false，更新现有值
+
+bool inserted3 = map.Insert(2, std::string("two")); // 移动语义版本
+
+XCEngine::Containers::HashMap<int, std::string>::Pair p{3, "three"};
+bool inserted4 = map.Insert(std::move(p)); // Pair 移动版本
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator[]](./operator-subscript.md) - 下标访问（总是插入）
+- [Erase](erase.md) - 删除键对应的元素

docs/api/containers/hashmap/iterator.md

@@ -0,0 +1,34 @@
+# HashMap::begin / end
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取哈希表的迭代器。迭代器遍历所有桶中的元素。
+
+**参数：** 无
+
+**返回：** 返回指向第一个元素和末尾（最后一个元素之后）位置的迭代器。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+for (auto it = map.begin(); it != map.end(); ++it) {
+    std::cout << it->first << " -> " << it->second << std::endl;
+}
+// 输出顺序不确定，取决于哈希桶的内部布局
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/operator-assign.md

@@ -0,0 +1,36 @@
+# HashMap::operator=
+
+```cpp
+HashMap& operator=(const HashMap& other);
+HashMap& operator=(HashMap&& other) noexcept;
+```
+
+赋值运算符，用另一个 HashMap 的内容替换当前内容。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 对当前对象的引用 (`*this`)
+
+**复杂度：**
+- 拷贝赋值：O(m_bucketCount + other.m_size)
+- 移动赋值：O(m_size)，需要先清空当前内容
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+map1.Insert(1, "one");
+map1.Insert(2, "two");
+
+XCEngine::Containers::HashMap<int, const char*> map2;
+map2 = map1; // 拷贝赋值
+
+XCEngine::Containers::HashMap<int, const char*> map3;
+map3 = std::move(map1); // 移动赋值，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Copy/Move](copy-move.md) - 拷贝/移动构造

docs/api/containers/hashmap/operator-subscript.md

@@ -0,0 +1,33 @@
+# HashMap::operator[]
+
+```cpp
+Value& operator[](const Key& key);
+```
+
+按下标访问键对应的值。如果键不存在，则插入一个默认构造的值并返回引用。
+
+**参数：**
+- `key` - 要访问的键
+
+**返回：** 对应值的引用。如果键不存在，则返回一个默认构造的 `Value` 的引用。
+
+**复杂度：** O(1) 平均，最坏 O(n)（发生 rehash 时）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+map[1] = "one";          // 插入键 1，值 "one"
+map[2] = "two";          // 插入键 2，值 "two"
+
+std::string& value = map[1]; // 获取键 1 对应的值，结果为 "one"
+
+map[3];                  // 插入键 3，值为 std::string 的默认构造值
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值（不插入）
+- [Insert](insert.md) - 插入键值对（不覆盖已存在的键）

docs/api/containers/hashmap/setallocator.md

@@ -0,0 +1,28 @@
+# HashMap::SetAllocator
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置哈希表的内存分配器。
+
+**参数：**
+- `allocator` - 内存分配器指针，可以为 `nullptr`（使用默认分配器）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+// 设置自定义分配器（如果使用内存分配器接口）
+// map.SetAllocator(customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/hashmap/size.md

@@ -0,0 +1,35 @@
+# HashMap::Size / Empty
+
+```cpp
+size_t Size() const;
+bool Empty() const;
+```
+
+获取哈希表的元素数量或判断是否为空。
+
+**参数：** 无
+
+**返回：**
+- `Size()` - 返回元素数量
+- `Empty()` - 容器为空返回 `true`，否则返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 0
+
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "no"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 2
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/string/clear.md

@@ -0,0 +1,39 @@
+# String::Clear
+
+```cpp
+void Clear();
+```
+
+清空字符串内容，将长度设为 0，但不释放已分配的内存。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+    std::cout << "Before clear - Length: " << s.Length()
+              << ", Capacity: " << s.Capacity() << std::endl;
+    // 输出: Before clear - Length: 11, Capacity: 12
+
+    s.Clear();
+    std::cout << "After clear - Length: " << s.Length()
+              << ", Capacity: " << s.Capacity() << std::endl;
+    // 输出: After clear - Length: 0, Capacity: 12
+    std::cout << "Empty: " << s.Empty() << std::endl;  // 输出: Empty: 1
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Reserve / Resize](reserve-resize.md) - 内存管理

docs/api/containers/string/constructor.md

@@ -0,0 +1,48 @@
+# String::String
+
+```cpp
+String();
+String(const char* str);
+String(const char* str, SizeType len);
+String(const String& other);
+String(String&& other) noexcept;
+```
+
+构造 String 对象。提供多种构造方式以适应不同的使用场景。
+
+**参数：**
+- `str` - 以 null 结尾的 C 字符串
+- `len` - 要复制的字符数量
+- `other` - 另一个 String 对象（用于拷贝构造或移动构造）
+
+**返回：** 无
+
+**复杂度：**
+- 默认构造：O(1)
+- 从 `const char*` 构造：O(n)，其中 n 为字符串长度
+- 拷贝构造：O(n)
+- 移动构造：O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;                          // 默认构造
+    XCEngine::Containers::String s2("hello");                 // 从 C 字符串构造
+    XCEngine::Containers::String s3("world", 3);             // 从 C 字符串前 n 个字符构造
+    XCEngine::Containers::String s4(s2);                      // 拷贝构造
+    XCEngine::Containers::String s5(std::move(s4));           // 移动构造
+
+    std::cout << s2.CStr() << std::endl;  // 输出: hello
+    std::cout << s3.CStr() << std::endl;  // 输出: wor
+    std::cout << s4.CStr() << std::endl;  // 输出: hello
+    std::cout << s5.CStr() << std::endl;  // 输出: hello
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/cstr.md

@@ -0,0 +1,36 @@
+# String::CStr
+
+```cpp
+const char* CStr() const;
+```
+
+返回指向以 null 结尾的 C 字符串的指针。
+
+**参数：** 无
+
+**返回：** 指向内部字符数组的指针，以 null 结尾
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+#include <cstring>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    const char* cstr = s.CStr();
+    std::cout << cstr << std::endl;  // 输出: Hello World
+
+    std::cout << "Length: " << std::strlen(cstr) << std::endl;  // 输出: Length: 11
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length](size.md) - 获取长度

docs/api/containers/string/destructor.md

@@ -0,0 +1,31 @@
+# String::~String
+
+```cpp
+~String();
+```
+
+销毁 String 对象，释放所有动态分配的内存。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+
+int main() {
+    {
+        XCEngine::Containers::String s("hello");
+        // s 在作用域结束时自动销毁
+    }
+    // 内存已释放
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/ends-with.md

@@ -0,0 +1,39 @@
+# String::EndsWith
+
+```cpp
+bool EndsWith(const String& suffix) const;
+bool EndsWith(const char* suffix) const;
+```
+
+检查字符串是否以指定的后缀结尾。
+
+**参数：**
+- `suffix` - 要检查的后缀（String 或 const char*）
+
+**返回：** 如果字符串以指定后缀结尾则返回 `true`，否则返回 `false`
+
+**复杂度：** O(n)，其中 n 为后缀长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    std::cout << std::boolalpha;
+    std::cout << s.EndsWith("World") << std::endl;                     // 输出: true
+    std::cout << s.EndsWith(XCEngine::Containers::String("World")) << std::endl;  // 输出: true
+    std::cout << s.EndsWith("Hello") << std::endl;                      // 输出: false
+    std::cout << s.EndsWith("") << std::endl;                            // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [StartsWith](starts-with.md) - 检查前缀
+- [Find](find.md) - 查找子串

docs/api/containers/string/find.md

@@ -0,0 +1,47 @@
+# String::Find
+
+```cpp
+SizeType Find(const char* str, SizeType pos = 0) const;
+```
+
+在字符串中查找子串 `str`，从位置 `pos` 开始搜索。
+
+**参数：**
+- `str` - 要查找的以 null 结尾的 C 字符串
+- `pos` - 开始搜索的位置，默认为 0
+
+**返回：** 子串首次出现的起始位置；如果未找到，返回 `String::npos`
+
+**复杂度：** O(n * m)，其中 n 为原字符串长度，m 为要查找的字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World, Hello Universe");
+
+    XCEngine::Containers::String::SizeType pos1 = s.Find("World");
+    std::cout << "Found at: " << pos1 << std::endl;  // 输出: Found at: 6
+
+    XCEngine::Containers::String::SizeType pos2 = s.Find("Hello", 0);
+    std::cout << "First 'Hello' at: " << pos2 << std::endl;  // 输出: First 'Hello' at: 0
+
+    XCEngine::Containers::String::SizeType pos3 = s.Find("Hello", 7);
+    std::cout << "Second 'Hello' at: " << pos3 << std::endl;  // 输出: Second 'Hello' at: 13
+
+    XCEngine::Containers::String::SizeType pos4 = s.Find("NotFound");
+    if (pos4 == XCEngine::Containers::String::npos) {
+        std::cout << "Not found" << std::endl;  // 输出: Not found
+    }
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [StartsWith](starts-with.md) - 检查前缀
+- [EndsWith](ends-with.md) - 检查后缀

docs/api/containers/string/operator-assign.md

@@ -0,0 +1,47 @@
+# String::operator=
+
+```cpp
+String& operator=(const String& other);
+String& operator=(String&& other) noexcept;
+String& operator=(const char* str);
+```
+
+将新的值赋给 String 对象，替换原有的内容。
+
+**参数：**
+- `other` - 另一个 String 对象（拷贝赋值或移动赋值）
+- `str` - 以 null 结尾的 C 字符串
+
+**返回：** `*this`，支持链式调用
+
+**复杂度：**
+- 拷贝赋值：O(n)，n 为 other 的长度
+- 移动赋值：O(1)
+- 从 `const char*` 赋值：O(n)，n 为 str 的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;
+    XCEngine::Containers::String s2("hello");
+
+    s1 = s2;               // 拷贝赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: hello
+
+    s1 = "world";          // 从 const char* 赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: world
+
+    XCEngine::Containers::String s3("moved");
+    s1 = std::move(s3);    // 移动赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: moved
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/operator-equal.md

@@ -0,0 +1,43 @@
+# operator== / operator!=
+
+```cpp
+inline bool operator==(const String& lhs, const String& rhs);
+inline bool operator!=(const String& lhs, const String& rhs);
+```
+
+判断两个字符串是否相等或不相等。
+
+**operator==：** 比较两个字符串的长度是否相等，以及内容是否相同。
+
+**operator!=：** 相当于 `!(lhs == rhs)`。
+
+**参数：**
+- `lhs` - 左侧字符串
+- `rhs` - 右侧字符串
+
+**返回：** 布尔值，表示比较结果
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1("Hello");
+    XCEngine::Containers::String s2("Hello");
+    XCEngine::Containers::String s3("World");
+
+    std::cout << std::boolalpha;
+    std::cout << (s1 == s2) << std::endl;  // 输出: true
+    std::cout << (s1 == s3) << std::endl;  // 输出: false
+    std::cout << (s1 != s3) << std::endl;  // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/operator-plus-assign.md

@@ -0,0 +1,43 @@
+# String::operator+=
+
+```cpp
+String& operator+=(const String& other);
+String& operator+=(const char* str);
+String& operator+=(char c);
+```
+
+将指定的内容追加到当前 String 的末尾。
+
+**参数：**
+- `other` - 要追加的 String 对象
+- `str` - 要追加的以 null 结尾的 C 字符串
+- `c` - 要追加的单个字符
+
+**返回：** `*this`，支持链式调用
+
+**复杂度：** O(n)，其中 n 为被追加内容的长度。可能会触发重新分配，但均摊复杂度为 O(1)。
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello");
+
+    s += XCEngine::Containers::String(" World");  // 追加 String
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World
+
+    s += "!";                                     // 追加 const char*
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World!
+
+    s += '?';                                     // 追加 char
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World!?
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/operator-plus.md

@@ -0,0 +1,39 @@
+# operator+
+
+```cpp
+inline String operator+(const String& lhs, const String& rhs);
+```
+
+将两个 String 对象连接，返回一个新的 String 对象。
+
+**参数：**
+- `lhs` - 左侧的 String 对象
+- `rhs` - 右侧的 String 对象
+
+**返回：** 新的 String 对象，内容为 lhs 和 rhs 的拼接
+
+**复杂度：** O(n + m)，其中 n 和 m 分别为 lhs 和 rhs 的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1("Hello");
+    XCEngine::Containers::String s2(" World");
+    XCEngine::Containers::String s3 = s1 + s2;
+
+    std::cout << s3.CStr() << std::endl;  // 输出: Hello World
+
+    XCEngine::Containers::String s4 = XCEngine::Containers::String("Foo") + "Bar";
+    std::cout << s4.CStr() << std::endl;  // 输出: FooBar
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [operator+=](operator-plus-assign.md) - 追加操作

docs/api/containers/string/operator-subscript.md

@@ -0,0 +1,51 @@
+# String::operator[]
+
+```cpp
+char& operator[](SizeType index);
+const char& operator[](SizeType index) const;
+```
+
+通过索引访问字符串中的字符。
+
+**参数：**
+- `index` - 要访问的字符位置（从 0 开始）
+
+**返回：** 位置 `index` 处字符的引用（可写或只读）
+
+**复杂度：** O(1)
+
+**注意：** 不进行边界检查。调用者需确保 `index < Length()`。
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello");
+
+    // 只读访问
+    for (XCEngine::Containers::String::SizeType i = 0; i < s.Length(); ++i) {
+        std::cout << s[i];
+    }
+    std::cout << std::endl;  // 输出: Hello
+
+    // 可写访问
+    s[0] = 'J';
+    s[1] = 'a';
+    s[4] = '!';
+    std::cout << s.CStr() << std::endl;  // 输出: Jallo!
+
+    // const 版本
+    const XCEngine::Containers::String& cs = s;
+    char first = cs[0];
+    std::cout << "First char: " << first << std::endl;  // 输出: First char: J
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length](size.md) - 获取长度

docs/api/containers/string/reserve-resize.md

@@ -0,0 +1,51 @@
+# String::Reserve / Resize
+
+```cpp
+void Reserve(SizeType capacity);
+void Resize(SizeType newSize);
+void Resize(SizeType newSize, char fillChar);
+```
+
+管理字符串的内存和大小。
+
+**参数：**
+- `capacity` - 要预留的最小容量
+- `newSize` - 新的字符串长度
+- `fillChar` - 当扩展字符串时用于填充新增位置的字符，默认为 '\0'
+
+**返回：** 无
+
+**复杂度：**
+- `Reserve`：最坏 O(n)，仅在需要扩展容量时复制数据
+- `Resize`：O(n)，当 newSize > Length 时可能需要扩展
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hi");
+
+    // Reserve - 预分配内存
+    s.Reserve(100);
+    std::cout << "After Reserve(100), Capacity: " << s.Capacity() << std::endl;
+    // 输出: After Reserve(100), Capacity: 100
+
+    // Resize - 缩短字符串
+    s.Resize(1);
+    std::cout << "After Resize(1): " << s.CStr() << std::endl;  // 输出: H
+
+    // Resize - 扩展字符串，用 'X' 填充
+    s.Resize(5, 'X');
+    std::cout << "After Resize(5, 'X'): " << s.CStr() << std::endl;  // 输出: HXXXX
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length / Capacity](size.md) - 获取长度和容量
+- [Clear](clear.md) - 清空字符串

docs/api/containers/string/size.md

@@ -0,0 +1,44 @@
+# String::Length / Capacity / Empty
+
+```cpp
+SizeType Length() const;
+SizeType Capacity() const;
+bool Empty() const;
+```
+
+获取字符串的长度、容量和判空状态。
+
+**参数：** 无
+
+**返回：**
+- `Length()` - 返回字符串的字符数（不包括终止 null 字符）
+- `Capacity()` - 返回已分配的存储容量
+- `Empty()` - 如果字符串为空则返回 `true`
+
+**复杂度：** 均为 O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;
+    std::cout << "Empty: " << s1.Empty() << std::endl;  // 输出: Empty: 1
+
+    XCEngine::Containers::String s2("Hello");
+    std::cout << "Length: " << s2.Length() << std::endl;      // 输出: Length: 5
+    std::cout << "Capacity: " << s2.Capacity() << std::endl;  // 输出: Capacity: 6 或更大
+
+    s2.Reserve(100);
+    std::cout << "After Reserve(100), Capacity: " << s2.Capacity() << std::endl;  // 输出: 100
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [CStr](cstr.md) - 获取 C 字符串
+- [Reserve / Resize](reserve-resize.md) - 内存管理

docs/api/containers/string/starts-with.md

@@ -0,0 +1,39 @@
+# String::StartsWith
+
+```cpp
+bool StartsWith(const String& prefix) const;
+bool StartsWith(const char* prefix) const;
+```
+
+检查字符串是否以指定的前缀开头。
+
+**参数：**
+- `prefix` - 要检查的前缀（String 或 const char*）
+
+**返回：** 如果字符串以指定前缀开头则返回 `true`，否则返回 `false`
+
+**复杂度：** O(n)，其中 n 为前缀长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    std::cout << std::boolalpha;
+    std::cout << s.StartsWith("Hello") << std::endl;                     // 输出: true
+    std::cout << s.StartsWith(XCEngine::Containers::String("Hello")) << std::endl;  // 输出: true
+    std::cout << s.StartsWith("World") << std::endl;                      // 输出: false
+    std::cout << s.StartsWith("") << std::endl;                            // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [EndsWith](ends-with.md) - 检查后缀
+- [Find](find.md) - 查找子串

docs/api/containers/string/string.md

@@ -0,0 +1,105 @@
+# String
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class`
+
+**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。
+
+## 概述
+
+`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `SizeType` | `size_t` | 大小类型 |
+
+## 常量
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| `static constexpr SizeType npos` | `static_cast<SizeType>(-1)` | 无效位置标识 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造字符串实例 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [operator+=](operator-plus-assign.md) | 追加字符串/字符 |
+| [operator+](../string/operator-plus.md) | 字符串连接 |
+| [operator==](../string/operator-equal.md) | 判断两个字符串是否相等 |
+| [operator!=](../string/operator-equal.md) | 判断两个字符串是否不相等 |
+| [Substring](substring.md) | 获取子串 |
+| [Trim](trim.md) | 去除首尾空白 |
+| [ToLower/ToUpper](to-lower-upper.md) | 大小写转换 |
+| [Find](find.md) | 查找子串位置 |
+| [StartsWith](starts-with.md) | 检查前缀 |
+| [EndsWith](ends-with.md) | 检查后缀 |
+| [CStr](cstr.md) | 获取 C 字符串指针 |
+| [Length/Capacity/Empty](size.md) | 获取尺寸信息 |
+| [operator[]](operator-subscript.md) | 下标访问 |
+| [Clear](clear.md) | 清空字符串 |
+| [Reserve/Resize](reserve-resize.md) | 预留/调整容量 |
+
+## std::hash 特化
+
+```cpp
+namespace std {
+    template<>
+    struct hash<XCEngine::Containers::String> {
+        size_t operator()(const XCEngine::Containers::String& str) const noexcept;
+    };
+}
+```
+
+提供了 `std::hash<String>` 特化，使 `String` 可以作为 unordered_map 或 unordered_set 的键使用。
+
+**实现算法：** DJB hash (Daniel J. Bernstein hash)
+
+**算法细节：**
+- 初始值：5381
+- 对每个字符：`hash = hash * 33 + c`（等价于 `(hash << 5) + hash + c`）
+
+**示例：**
+```cpp
+#include <XCEngine/Containers/String.h>
+#include <unordered_map>
+
+int main() {
+    std::unordered_map<XCEngine::Containers::String, int> map;
+    map["key1"] = 100;
+    map["key2"] = 200;
+    return 0;
+}
+```
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/String.h>
+
+// 基本用法
+Containers::String str = "Hello";
+str += ", World!";
+
+// 字符串操作
+Containers::String sub = str.Substring(0, 5);  // "Hello"
+bool hasPrefix = str.StartsWith("Hello");
+bool hasSuffix = str.EndsWith("!");
+
+// 查找
+SizeType pos = str.Find("World");  // 返回 7
+
+// 转换
+Containers::String upper = str.ToUpper();
+Containers::String lower = str.ToLower();
+```
+
+## 相关文档
+
+- [Array](../array/array.md) - 动态数组
+- [HashMap](../hashmap/hashmap.md) - 哈希表

docs/api/containers/string/substring.md

@@ -0,0 +1,43 @@
+# String::Substring
+
+```cpp
+String Substring(SizeType pos, SizeType len = npos) const;
+```
+
+返回从位置 `pos` 开始、长度为 `len` 的子字符串。如果 `len` 省略或为 `npos`，则返回从 `pos` 到字符串末尾的所有字符。
+
+**参数：**
+- `pos` - 子字符串的起始位置（从 0 开始）
+- `len` - 子字符串的长度，默认为 `npos`（即到字符串末尾）
+
+**返回：** 新的 String 对象，包含指定的子字符串
+
+**复杂度：** O(n)，其中 n 为子字符串的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    XCEngine::Containers::String sub1 = s.Substring(6);        // 从位置6到末尾
+    std::cout << sub1.CStr() << std::endl;  // 输出: World
+
+    XCEngine::Containers::String sub2 = s.Substring(6, 5);      // 从位置6开始，长度5
+    std::cout << sub2.CStr() << std::endl;  // 输出: World
+
+    XCEngine::Containers::String sub3 = s.Substring(0, 5);      // 从位置0开始，长度5
+    std::cout << sub3.CStr() << std::endl;  // 输出: Hello
+
+    XCEngine::Containers::String sub4 = s.Substring(6, 100);    // len超过剩余长度，自动截断
+    std::cout << sub4.CStr() << std::endl;  // 输出: World
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/to-lower-upper.md

@@ -0,0 +1,36 @@
+# String::ToLower / ToUpper
+
+```cpp
+String ToLower() const;
+String ToUpper() const;
+```
+
+将字符串转换为小写/大写形式，返回一个新的 String 对象，原字符串不变。
+
+**参数：** 无
+
+**返回：** 转换后的新 String 对象
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World 123");
+
+    XCEngine::Containers::String lower = s.ToLower();
+    std::cout << lower.CStr() << std::endl;  // 输出: hello world 123
+
+    XCEngine::Containers::String upper = s.ToUpper();
+    std::cout << upper.CStr() << std::endl;  // 输出: HELLO WORLD 123
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/containers/string/trim.md

@@ -0,0 +1,35 @@
+# String::Trim
+
+```cpp
+String Trim() const;
+```
+
+移除字符串两端的空白字符（空格、制表符、换行符、回车符），返回一个新的 String 对象，原字符串不变。
+
+**参数：** 无
+
+**返回：** 去除两端空白后的新 String 对象
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("   Hello World   ");
+
+    XCEngine::Containers::String trimmed = s.Trim();
+    std::cout << "\"" << trimmed.CStr() << "\"" << std::endl;  // 输出: "Hello World"
+
+    XCEngine::Containers::String s2("\t\n  test  \t\n");
+    std::cout << "\"" << s2.Trim().CStr() << "\"" << std::endl;  // 输出: "test" (空格、制表符、换行、回车被移除)
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览

docs/api/core/core.md

@@ -0,0 +1,97 @@
+# Core 模块概览
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `module`
+
+**描述**: XCEngine 的核心基础模块，提供类型别名、智能指针、事件系统等基础功能。
+
+## 概述
+
+Core 模块包含了引擎所需的基础类型和工具，是其他所有模块的依赖基础。
+
+## 模块内容
+
+### 类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Types](types/types.md) | `Types.h` | 类型别名定义 |
+
+### 智能指针
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [SmartPtr](smartptr/smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 |
+| [RefCounted](refcounted/refcounted.md) | `RefCounted.h` | 引用计数基类 |
+
+### 事件系统
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Event](event/event.md) | `Event.h` | 事件系统模板 |
+
+### 文件操作
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [FileWriter](filewriter/filewriter.md) | `FileWriter.h` | 文件写入工具 |
+
+## 类型别名
+
+```cpp
+using int8 = int8_t;
+using int16 = int16_t;
+using int32 = int32_t;
+using int64 = int64_t;
+using uint8 = uint8_t;
+using uint16 = uint16_t;
+using uint32 = uint32_t;
+using uint64 = uint64_t;
+using byte = uint8_t;
+```
+
+## 智能指针别名
+
+```cpp
+template<typename T>
+using Ref = std::shared_ptr<T>;
+
+template<typename T>
+using UniqueRef = std::unique_ptr<T>;
+
+template<typename T, typename... Args>
+Ref<T> MakeRef(Args&&... args);
+
+template<typename T, typename... Args>
+UniqueRef<T> MakeUnique(Args&&... args);
+```
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Core.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+// 使用类型别名
+uint32 value = 100;
+byte data[4];
+
+// 使用智能指针
+auto ref = MakeRef<MyClass>();
+auto unique = MakeUnique<MyClass>();
+
+// 使用事件系统
+Event<int, float> myEvent;
+myEvent.Subscribe([](int a, float b) {
+    printf("Event: %d, %f\n", a, b);
+});
+myEvent.Invoke(42, 3.14f);
+```
+
+## 相关文档
+
+- [Containers 模块](../containers/containers.md) - 容器类型
+- [Memory 模块](../memory/memory.md) - 内存管理

docs/api/core/event/Clear.md

@@ -0,0 +1,39 @@
+# Event::Clear
+
+```cpp
+void Clear();
+```
+
+清空所有订阅。
+
+**描述**
+
+移除所有已订阅的回调，清空事件。线程安全。
+
+**复杂度：** O(n) 其中 n 为订阅数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+
+// 订阅多个回调
+event.Subscribe([](int v) { });
+event.Subscribe([](int v) { });
+event.Subscribe([](int v) { });
+
+// 清空所有订阅
+event.Clear();
+
+// 触发（无回调被执行）
+event.Invoke(42);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订单个事件

docs/api/core/event/Invoke.md

@@ -0,0 +1,45 @@
+# Event::Invoke
+
+```cpp
+void Invoke(Args... args);
+```
+
+调用所有订阅的回调。
+
+**描述**
+
+依次调用所有已订阅的回调函数。在调用前会自动处理待退订的回调。回调是在锁外执行的，因此可以在回调中安全地进行订阅/退订操作。线程安全。
+
+**参数：**
+- `args` - 传递给回调的参数
+
+**复杂度：** O(n) 其中 n 为订阅数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 无参数事件
+Event<> frameEndEvent;
+frameEndEvent.Subscribe([]() {
+    printf("Frame ended\n");
+});
+
+// 带参数事件
+Event<int, const char*> playerDiedEvent;
+playerDiedEvent.Subscribe([](int playerId, const char* reason) {
+    printf("Player %d died: %s\n", playerId, reason);
+});
+
+// 触发事件
+frameEndEvent.Invoke();
+playerDiedEvent.Invoke(1, "fell off a cliff");
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Subscribe](Subscribe.md) - 订阅事件

docs/api/core/event/ProcessUnsubscribes.md

@@ -0,0 +1,39 @@
+# Event::ProcessUnsubscribes
+
+```cpp
+void ProcessUnsubscribes();
+```
+
+处理积压的退订请求。
+
+**描述**
+
+手动处理待退订的回调，将其从订阅列表中移除。通常不需要手动调用，`Invoke` 会自动处理退订。但在某些场景下可能需要主动调用。
+
+**复杂度：** O(n) 其中 n 为待退订数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+
+// 订阅
+uint64_t id = event.Subscribe([](int value) { });
+
+// 退订请求入队
+event.Unsubscribe(id);
+
+// 主动处理退订
+event.ProcessUnsubscribes();
+
+// 此时事件列表中已无该回调
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订事件

docs/api/core/event/Subscribe.md

@@ -0,0 +1,50 @@
+# Event::Subscribe
+
+```cpp
+uint64_t Subscribe(Callback callback);
+```
+
+订阅事件回调。
+
+**描述**
+
+将回调函数添加到事件订阅列表中，并返回一个唯一的订阅 ID。该 ID 可用于后续退订。线程安全，可在任意线程调用。
+
+**参数：**
+- `callback` - 要订阅的回调函数，类型为 `std::function<void(Args...)>`
+
+**返回：** `uint64_t` - 订阅 ID，用于退订
+
+**复杂度：** O(1) amortized
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 定义事件
+Event<int, float> damageEvent;
+
+// 订阅多个回调
+uint64_t id1 = damageEvent.Subscribe([](int damage, float time) {
+    printf("Damage taken: %d at time %f\n", damage, time);
+});
+
+uint64_t id2 = damageEvent.Subscribe([](int damage, float time) {
+    // 记录伤害日志
+});
+
+// 使用 lambda 表达式
+auto callback = [](int damage, float time) {
+    // 处理伤害
+};
+uint64_t id3 = damageEvent.Subscribe(callback);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订事件
+- [Invoke](Invoke.md) - 触发事件

docs/api/core/event/Unsubscribe.md

@@ -0,0 +1,43 @@
+# Event::Unsubscribe
+
+```cpp
+void Unsubscribe(uint64_t id);
+```
+
+退订事件。
+
+**描述**
+
+将指定 ID 的回调从订阅列表中移除。退订是延迟生效的，在调用 `Invoke` 时会一并处理待退订的回调。线程安全，可在任意线程调用。
+
+**参数：**
+- `id` - 订阅时返回的 ID
+
+**复杂度：** O(n) 在 Invoke 时处理
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> someEvent;
+
+// 订阅
+uint64_t id = someEvent.Subscribe([](int value) {
+    printf("Value: %d\n", value);
+});
+
+// 退订
+someEvent.Unsubscribe(id);
+
+// 触发（已退订的回调不会被调用）
+someEvent.Invoke(42);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Subscribe](Subscribe.md) - 订阅事件
+- [ProcessUnsubscribes](ProcessUnsubscribes.md) - 手动处理退订

docs/api/core/event/begin.md

@@ -0,0 +1,37 @@
+# Event::begin
+
+```cpp
+Iterator begin();
+```
+
+获取开始迭代器。
+
+**描述**
+
+返回订阅列表的开始迭代器，用于范围for循环遍历所有订阅的回调。
+
+**返回：** `Iterator` - 指向第一个监听器的迭代器（等价于 `std::vector<Listener>::iterator`）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+event.Subscribe([](int v) { printf("Callback 1: %d\n", v); });
+event.Subscribe([](int v) { printf("Callback 2: %d\n", v); });
+
+// 遍历所有订阅
+for (auto& [id, callback] : event) {
+    callback(100);
+}
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [end](end.md) - 获取结束迭代器

docs/api/core/event/end.md

@@ -0,0 +1,36 @@
+# Event::end
+
+```cpp
+Iterator end();
+```
+
+获取结束迭代器。
+
+**描述**
+
+返回订阅列表的结束迭代器，用于范围for循环遍历所有订阅的回调。
+
+**返回：** `Iterator` - 指向末尾的迭代器（等价于 `std::vector<Listener>::iterator`）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+event.Subscribe([](int v) { printf("Callback: %d\n", v); });
+
+// 遍历所有订阅
+for (auto& [id, callback] : event) {
+    callback(42);
+}
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [begin](begin.md) - 获取开始迭代器

docs/api/core/event/event.md

@@ -0,0 +1,69 @@
+# Event
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class` (template)
+
+**描述**: 事件系统模板类，提供类型安全的多订阅者事件/委托系统。
+
+## 概述
+
+`Event<Args...>` 是一个类型安全的事件发布-订阅系统。它支持多个回调订阅、退订和线程安全的调用。非常适合用于游戏引擎中的事件驱动通信。
+
+## 模板参数
+
+| 参数 | 描述 |
+|------|------|
+| `Args...` | 事件回调的参数类型 |
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Callback` | `std::function<void(Args...)>` | 回调函数类型 |
+| `Listener` | `std::pair<uint64_t, Callback>` | 监听器条目 |
+| `Iterator` | `std::vector<Listener>::iterator` | 迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Subscribe`](Subscribe.md) | 订阅事件回调，返回订阅 ID |
+| [`Unsubscribe`](Unsubscribe.md) | 退订事件（延迟生效） |
+| [`ProcessUnsubscribes`](ProcessUnsubscribes.md) | 处理积压的退订请求 |
+| [`Clear`](Clear.md) | 清空所有订阅 |
+| [`Invoke`](Invoke.md) | 调用所有订阅的回调 |
+| [`begin`](begin.md) | 获取开始迭代器 |
+| [`end`](end.md) | 获取结束迭代器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 定义事件（无参数）
+Event<> frameStartEvent;
+
+// 定义事件（带参数）
+Event<int, float> damageEvent;
+
+// 订阅
+uint64_t id = damageEvent.Subscribe([](int damage, float time) {
+    printf("Damage: %d at time %f\n", damage, time);
+});
+
+// 触发事件
+damageEvent.Invoke(100, 3.14f);
+
+// 退订
+damageEvent.Unsubscribe(id);
+
+// 清空
+frameStartEvent.Clear();
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览

docs/api/core/filewriter/Close.md

@@ -0,0 +1,40 @@
+# FileWriter::Close
+
+```cpp
+void Close();
+```
+
+关闭文件。
+
+**描述**
+
+关闭当前打开的文件。如果文件未打开，则什么都不做。析构函数会自动调用此方法。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer;
+
+if (writer.Open("data.txt")) {
+    writer.Write("Some data\n");
+    writer.Flush();
+    writer.Close();
+}
+
+// 文件已关闭，可再次打开其他文件
+if (writer.Open("other.txt")) {
+    writer.Write("New content\n");
+}
+// 析构时自动关闭
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Open](Open.md) - 打开文件

docs/api/core/filewriter/Flush.md

@@ -0,0 +1,45 @@
+# FileWriter::Flush
+
+```cpp
+bool Flush();
+```
+
+刷新缓冲区。
+
+**描述**
+
+将缓冲区中的数据强制写入磁盘，确保数据持久化。在写入大量数据后应调用此方法以确保数据已保存。
+
+**返回：** `bool` - 是否刷新成功
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <string>
+
+using namespace XCEngine::Core;
+
+FileWriter writer("output.txt");
+if (writer.IsOpen()) {
+    // 写入大量数据
+    for (int i = 0; i < 1000; i++) {
+        writer.Write("Line ");
+        writer.Write(std::to_string(i).c_str());
+        writer.Write("\n");
+    }
+    
+    // 刷新确保数据写入磁盘
+    writer.Flush();
+    
+    // 数据已安全保存
+    writer.Close();
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Write](Write.md) - 写入数据

docs/api/core/filewriter/IsOpen.md

@@ -0,0 +1,43 @@
+# FileWriter::IsOpen
+
+```cpp
+bool IsOpen() const;
+```
+
+检查文件是否已打开。
+
+**描述**
+
+返回文件是否已成功打开并可用于写入。
+
+**返回：** `bool` - 文件是否已打开
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer1;
+if (writer1.IsOpen()) {
+    // 不会执行
+    writer1.Write("test");
+}
+
+// 打开文件
+FileWriter writer2("output.txt");
+if (writer2.IsOpen()) {
+    printf("File opened successfully\n");
+    writer2.Write("Content");
+} else {
+    printf("Failed to open file\n");
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Open](Open.md) - 打开文件

docs/api/core/filewriter/Open.md

@@ -0,0 +1,53 @@
+# FileWriter::Open
+
+```cpp
+bool Open(const char* filePath, bool append = false);
+```
+
+打开文件。
+
+**描述**
+
+打开指定路径的文件，准备写入。如果之前已打开文件，会先关闭。返回是否成功打开文件。
+
+**参数：**
+- `filePath` - 要打开的文件路径
+- `append` - 是否以追加模式打开，默认为覆盖模式
+
+**返回：** `bool` - 是否成功打开
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer;
+
+// 打开文件（覆盖模式）
+if (writer.Open("output.txt")) {
+    writer.Write("Hello\n");
+    writer.Close();
+}
+
+// 打开文件（追加模式）
+if (writer.Open("log.txt", true)) {
+    writer.Write("Another line\n");
+    writer.Flush();
+}
+
+// 检查是否成功
+FileWriter writer2;
+if (!writer2.Open("/invalid/path/file.txt")) {
+    printf("Failed to open file\n");
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Close](Close.md) - 关闭文件
+- [IsOpen](IsOpen.md) - 检查文件状态

docs/api/core/filewriter/Write.md

@@ -0,0 +1,48 @@
+# FileWriter::Write
+
+```cpp
+bool Write(const char* data, size_t length);
+bool Write(const Containers::String& str);
+```
+
+写入数据到文件。
+
+**描述**
+
+将数据写入文件。如果文件未打开，操作会失败。
+
+**参数：**
+- `data` - 要写入的字符数据
+- `length` - 要写入的字节数
+- `str` - 要写入的 String 对象
+
+**返回：** `bool` - 是否写入成功
+
+**复杂度：** O(n) 其中 n 为写入的字节数
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer("output.txt");
+if (writer.IsOpen()) {
+    // 写入原始字符数组
+    writer.Write("Hello, World!", 13);
+    writer.Write("\n", 1);
+    
+    // 写入 String
+    Containers::String message = "This is a test string";
+    writer.Write(message);
+    
+    writer.Flush();
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Flush](Flush.md) - 刷新缓冲区

docs/api/core/filewriter/filewriter.md

@@ -0,0 +1,66 @@
+# FileWriter
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class`
+
+**描述**: 文件写入工具类，提供简单的文件写入操作封装。
+
+## 概述
+
+`FileWriter` 是一个轻量级的文件写入工具，封装了 `FILE*` 接口，提供便捷的字符串和二进制数据写入功能。它支持追加模式和自动资源管理（RAII）。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `FileWriter()` | 默认构造（不打开文件） |
+| `FileWriter(const char* filePath, bool append = false)` | 构造并打开文件 |
+| `~FileWriter()` | 析构函数，自动关闭文件 |
+| [`Open`](Open.md) | 打开文件，append=true 时为追加模式 |
+| [`Close`](Close.md) | 关闭文件 |
+| [`IsOpen`](IsOpen.md) | 检查文件是否已打开 |
+| [`Write`](Write.md) | 写入数据 |
+| [`Flush`](Flush.md) | 刷新缓冲区 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+// 方式1：构造时打开
+FileWriter writer("output.txt", false);
+if (writer.IsOpen()) {
+    writer.Write("Hello, World!\n");
+    writer.Write("Line 2\n");
+    writer.Flush();
+}
+
+// 方式2：先构造再打开
+FileWriter writer2;
+if (writer2.Open("log.txt")) {
+    writer2.Write("Application started\n");
+    writer2.Close();
+}
+
+// 追加模式
+FileWriter appendWriter("log.txt", true);
+if (appendWriter.IsOpen()) {
+    appendWriter.Write("Another log entry\n");
+    appendWriter.Flush();
+}
+
+// 使用 String 写入
+Containers::String content = "Content written from String";
+FileWriter writer3("data.txt");
+writer3.Write(content);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [Logger](../../debug/logger/logger.md) - 日志系统
+- [FileLogSink](../../debug/filelogsink/filelogsink.md) - 文件日志输出

docs/api/core/refcounted/AddRef.md

@@ -0,0 +1,40 @@
+# RefCounted::AddRef
+
+```cpp
+void AddRef();
+```
+
+增加引用计数。
+
+**描述**
+
+原子地增加引用计数。在复制 `RefCounted` 指针或传递引用时调用此方法。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+// 创建对象（构造时 refCount = 1）
+MyObject* obj = new MyObject();
+
+// 手动增加引用
+obj->AddRef();  // refCount = 2
+obj->AddRef();  // refCount = 3
+
+// 需要释放额外的引用
+obj->Release();  // refCount = 2
+obj->Release();  // refCount = 1
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [Release](Release.md) - 减少引用计数

docs/api/core/refcounted/GetRefCount.md

@@ -0,0 +1,43 @@
+# RefCounted::GetRefCount
+
+```cpp
+uint32_t GetRefCount() const;
+```
+
+获取当前引用计数。
+
+**描述**
+
+返回当前的引用计数值。由于使用 `std::atomic` 实现，因此是线程安全的。
+
+**返回：** `uint32_t` - 当前引用计数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void Debug() {
+        printf("RefCount: %u\n", GetRefCount());
+    }
+};
+
+MyObject* obj = new MyObject();
+printf("After create: %u\n", obj->GetRefCount());  // 1
+
+obj->AddRef();
+printf("After AddRef: %u\n", obj->GetRefCount());  // 2
+
+obj->Release();
+printf("After Release: %u\n", obj->GetRefCount()); // 1
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [AddRef](AddRef.md) - 增加引用计数
+- [Release](Release.md) - 减少引用计数

docs/api/core/refcounted/Release.md

@@ -0,0 +1,39 @@
+# RefCounted::Release
+
+```cpp
+void Release();
+```
+
+减少引用计数。
+
+**描述**
+
+原子地减少引用计数。当引用计数归零时，对象会自动 `delete this`。这是实现自动内存管理的关键方法。
+
+**复杂度：** O(1)（归零时为 O(n)，n 为对象大小）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+// 创建对象（构造时 refCount = 1）
+MyObject* obj = new MyObject();
+
+// 手动增加引用
+obj->AddRef();  // refCount = 2
+
+// 释放引用
+obj->Release();  // refCount = 1
+obj->Release();  // refCount = 0, 对象被自动 delete
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [AddRef](AddRef.md) - 增加引用计数

docs/api/core/refcounted/refcounted.md

@@ -0,0 +1,44 @@
+# RefCounted
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class`
+
+**描述**: 引用计数基类，提供线程安全的引用计数生命周期管理。
+
+## 概述
+
+`RefCounted` 是一个简单的引用计数基类。当引用计数归零时，对象会自动删除。它提供了 `AddRef` 和 `Release` 方法，线程安全地管理引用计数。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `RefCounted()` | 构造函数，初始引用计数为 1 |
+| `virtual ~RefCounted()` | 虚析构函数 |
+| [`AddRef`](AddRef.md) | 增加引用计数 |
+| [`Release`](Release.md) | 减少引用计数（归零时自动 delete this） |
+| [`GetRefCount`](GetRefCount.md) | 获取当前引用计数 |
+
+## 使用示例
+
+```cpp
+class MyObject : public RefCounted {
+public:
+    MyObject() { /* ... */ }
+    ~MyObject() { /* ... */ }
+    
+    void DoSomething() { /* ... */ }
+};
+
+// 使用
+MyObject* obj = new MyObject();  // refCount = 1
+obj->AddRef();                   // refCount = 2
+obj->Release();                   // refCount = 1
+obj->Release();                   // refCount = 0, 自动 delete
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [SmartPtr](../smartptr/smartptr.md) - 智能指针

docs/api/core/smartptr/MakeRef.md

@@ -0,0 +1,51 @@
+# SmartPtr::MakeRef
+
+```cpp
+template<typename T, typename... Args>
+Ref<T> MakeRef(Args&&... args);
+```
+
+创建共享指针的工厂函数。
+
+**描述**
+
+`MakeRef` 是创建 `Ref<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_shared`，代码更简洁。
+
+**模板参数：**
+- `T` - 被创建对象的类型
+- `Args` - 构造函数的参数类型
+
+**参数：**
+- `args` - 转发给 T 构造函数的参数
+
+**返回：** `Ref<T>` - 新创建的共享指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    MyClass(int a, int b) : m_a(a), m_b(b) {}
+    int GetSum() const { return m_a + m_b; }
+private:
+    int m_a, m_b;
+};
+
+// 创建共享指针
+Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(10, 20);
+printf("Sum: %d\n", ref->GetSum());
+
+// 使用 lambda
+Core::Ref<std::function<void()>> callback = Core::MakeRef<std::function<void()>>([]() {
+    printf("Callback invoked!\n");
+});
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [Ref](Ref.md) - Ref 类型说明

docs/api/core/smartptr/MakeUnique.md

@@ -0,0 +1,49 @@
+# SmartPtr::MakeUnique
+
+```cpp
+template<typename T, typename... Args>
+UniqueRef<T> MakeUnique(Args&&... args);
+```
+
+创建独占指针的工厂函数。
+
+**描述**
+
+`MakeUnique` 是创建 `UniqueRef<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_unique`，代码更简洁。
+
+**模板参数：**
+- `T` - 被创建对象的类型
+- `Args` - 构造函数的参数类型
+
+**参数：**
+- `args` - 转发给 T 构造函数的参数
+
+**返回：** `UniqueRef<T>` - 新创建的独占指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    MyClass(int value) : m_value(value) {}
+    int GetValue() const { return m_value; }
+private:
+    int m_value;
+};
+
+// 创建独占指针
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>(42);
+printf("Value: %d\n", unique->GetValue());
+
+// 转移所有权
+Core::UniqueRef<MyClass> moved = Core::MakeUnique<MyClass>(100);
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [UniqueRef](UniqueRef.md) - UniqueRef 类型说明

docs/api/core/smartptr/Ref.md

@@ -0,0 +1,40 @@
+# SmartPtr::Ref
+
+```cpp
+template<typename T>
+using Ref = std::shared_ptr<T>;
+```
+
+共享引用智能指针类型别名。
+
+**描述**
+
+`Ref<T>` 是 `std::shared_ptr<T>` 的类型别名，提供共享所有权的智能指针。多个 `Ref` 可以指向同一个对象，通过引用计数管理生命周期。当最后一个 `Ref` 被销毁时，对象会被自动删除。
+
+**模板参数：**
+- `T` - 被托管对象的类型
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+Core::Ref<MyClass> ref1 = Core::MakeRef<MyClass>();
+Core::Ref<MyClass> ref2 = ref1;  // 共享所有权
+
+if (ref1) {
+    ref1->DoSomething();
+}
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [MakeRef](MakeRef.md) - 创建 Ref 的工厂函数

docs/api/core/smartptr/UniqueRef.md

@@ -0,0 +1,46 @@
+# SmartPtr::UniqueRef
+
+```cpp
+template<typename T>
+using UniqueRef = std::unique_ptr<T>;
+```
+
+独占所有权的智能指针类型别名。
+
+**描述**
+
+`UniqueRef<T>` 是 `std::unique_ptr<T>` 的类型别名，提供独占所有权的智能指针。每个对象只能有一个 `UniqueRef` 持有，当 `UniqueRef` 被销毁时，对象会被自动删除。不能复制，只能移动。
+
+**模板参数：**
+- `T` - 被托管对象的类型
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
+
+if (unique) {
+    unique->DoSomething();
+}
+
+// 自定义删除器
+Core::UniqueRef<FILE, decltype(&fclose)> 
+    file(fopen("test.txt", "r"), &fclose);
+
+// 转移所有权
+Core::UniqueRef<MyClass> moved = std::move(unique);
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [MakeUnique](MakeUnique.md) - 创建 UniqueRef 的工厂函数

docs/api/core/smartptr/smartptr.md

@@ -0,0 +1,64 @@
+# SmartPtr
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `header-only`
+
+**描述**: 智能指针类型别名和工厂函数，提供 `std::shared_ptr` 和 `std::unique_ptr` 的简化接口。
+
+## 概述
+
+`Core::SmartPtr` 提供了 `std::shared_ptr` 和 `std::unique_ptr` 的类型别名和工厂函数，使智能指针的使用更加简洁。
+
+## 类型别名
+
+| 别名 | 底层类型 | 描述 |
+|------|----------|------|
+| `Core::Ref<T>` | `std::shared_ptr<T>` | 共享引用智能指针 |
+| `Core::UniqueRef<T>` | `std::unique_ptr<T>` | 独占所有权的智能指针 |
+
+## 工厂函数
+
+| 函数 | 返回值 | 描述 |
+|------|--------|------|
+| `Core::MakeRef<T>(Args&&... args)` | `Ref<T>` | 创建共享指针 |
+| `Core::MakeUnique<T>(Args&&... args)` | `UniqueRef<T>` | 创建独占指针 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Ref`](Ref.md) | `std::shared_ptr<T>` 类型别名 |
+| [`UniqueRef`](UniqueRef.md) | `std::unique_ptr<T>` 类型别名 |
+| [`MakeRef`](MakeRef.md) | 创建共享指针的工厂函数 |
+| [`MakeUnique`](MakeUnique.md) | 创建独占指针的工厂函数 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Core.h>
+
+// 使用 Ref（共享指针）
+Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(arg1, arg2);
+
+// 使用 UniqueRef（独占指针）
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
+
+// 传递所有权
+Core::Ref<MyClass> ref2 = ref;  // 引用计数 +1
+
+// 检查有效性
+if (ref) {
+    ref->DoSomething();
+}
+
+// 自定义删除器
+Core::UniqueRef<FILE, decltype(&fclose)> 
+    file(fopen("test.txt", "r"), &fclose);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [RefCounted](../refcounted/refcounted.md) - 引用计数基类
+- [Types](../types/types.md) - 类型别名

docs/api/core/types/byte.md

@@ -0,0 +1,30 @@
+# Types::byte
+
+```cpp
+using byte = uint8_t;
+```
+
+字节类型别名，对应 `uint8_t` 类型。
+
+**描述**
+
+`byte` 是 1 字节无符号整数类型，专门用于表示原始字节数据。语义上比 `uint8` 更清晰，适用于二进制数据、内存缓冲区等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::byte header[4] = {0x00, 0x01, 0x02, 0x03};
+Core::byte flags = 0b11001010;
+
+// 内存缓冲区
+Core::byte* buffer = new Core::byte[1024];
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint8](uint8.md) - 底层类型

docs/api/core/types/int16.md

@@ -0,0 +1,27 @@
+# Types::int16
+
+```cpp
+using int16 = int16_t;
+```
+
+16位有符号整数类型别名，对应 C++ 标准库的 `int16_t` 类型。
+
+**描述**
+
+`int16` 是 16 位（2 字节）有符号整数类型，范围为 -32,768 到 32,767。该类型别名确保跨平台一致性。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int16 shortValue = -10000;
+Core::int16 maxValue = 32767;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint16](uint16.md) - 对应的无符号类型

docs/api/core/types/int32.md

@@ -0,0 +1,30 @@
+# Types::int32
+
+```cpp
+using int32 = int32_t;
+```
+
+32位有符号整数类型别名，对应 C++ 标准库的 `int32_t` 类型。
+
+**描述**
+
+`int32` 是 32 位（4 字节）有符号整数类型，范围为 -2,147,483,648 到 2,147,483,647。该类型别名确保跨平台一致性，是最常用的整数类型。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int32 score = 1000000;
+Core::int32 negative = -500000;
+
+// 函数参数类型
+void SetHealth(Core::int32 health);
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint32](uint32.md) - 对应的无符号类型

docs/api/core/types/int64.md

@@ -0,0 +1,30 @@
+# Types::int64
+
+```cpp
+using int64 = int64_t;
+```
+
+64位有符号整数类型别名，对应 C++ 标准库的 `int64_t` 类型。
+
+**描述**
+
+`int64` 是 64 位（8 字节）有符号整数类型，范围为 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。该类型别名用于需要大范围整数的场景，如时间戳、大文件大小等。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int64 largeNumber = 9223372036854775807LL;
+Core::int64 fileSize = 1099511627776LL;  // 1TB
+
+// 时间戳（毫秒）
+Core::int64 timestamp = 1700000000000LL;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint64](uint64.md) - 对应的无符号类型

docs/api/core/types/int8.md

@@ -0,0 +1,28 @@
+# Types::int8
+
+```cpp
+using int8 = int8_t;
+```
+
+8位有符号整数类型别名，对应 C++ 标准库的 `int8_t` 类型。
+
+**描述**
+
+`int8` 是 8 位（1 字节）有符号整数类型，范围为 -128 到 127。该类型别名确保跨平台一致性。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int8 signedByte = -50;
+Core::int8 maxValue = 127;
+Core::int8 minValue = -128;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint8](uint8.md) - 对应的无符号类型

docs/api/core/types/types.md

@@ -0,0 +1,63 @@
+# Types
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `header` (type aliases)
+
+**头文件**: `XCEngine/Core/Types.h`
+
+**描述**: 基础类型别名定义，提供跨平台一致的基础类型名称。
+
+## 概述
+
+`Types.h` 定义了一组类型别名，简化了标准库类型的使用，并提供跨平台一致性。
+
+## 类型别名
+
+| 别名 | 实际类型 | 描述 |
+|------|----------|------|
+| `int8` | `int8_t` | 8位有符号整数 |
+| `int16` | `int16_t` | 16位有符号整数 |
+| `int32` | `int32_t` | 32位有符号整数 |
+| `int64` | `int64_t` | 64位有符号整数 |
+| `uint8` | `uint8_t` | 8位无符号整数 |
+| `uint16` | `uint16_t` | 16位无符号整数 |
+| `uint32` | `uint32_t` | 32位无符号整数 |
+| `uint64` | `uint64_t` | 64位无符号整数 |
+| `byte` | `uint8_t` | 字节类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`int8`](int8.md) | 8位有符号整数类型别名 |
+| [`int16`](int16.md) | 16位有符号整数类型别名 |
+| [`int32`](int32.md) | 32位有符号整数类型别名 |
+| [`int64`](int64.md) | 64位有符号整数类型别名 |
+| [`uint8`](uint8.md) | 8位无符号整数类型别名 |
+| [`uint16`](uint16.md) | 16位无符号整数类型别名 |
+| [`uint32`](uint32.md) | 32位无符号整数类型别名 |
+| [`uint64`](uint64.md) | 64位无符号整数类型别名 |
+| [`byte`](byte.md) | 字节类型别名 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+// 使用类型别名
+Core::int32 count = 100;
+Core::uint64 id = 1234567890;
+Core::byte flags = 0xFF;
+
+// 数组定义
+Core::uint8 buffer[1024];
+
+// 函数参数
+void ProcessData(Core::uint32 size, const Core::int8* data);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [SmartPtr](../smartptr/smartptr.md) - 智能指针

docs/api/core/types/uint16.md

@@ -0,0 +1,30 @@
+# Types::uint16
+
+```cpp
+using uint16 = uint16_t;
+```
+
+16位无符号整数类型别名，对应 C++ 标准库的 `uint16_t` 类型。
+
+**描述**
+
+`uint16` 是 16 位（2 字节）无符号整数类型，范围为 0 到 65,535。常用于 Unicode 字符、端口号等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint16 port = 8080;
+Core::uint16 maxConnections = 65535;
+
+// Unicode 字符
+Core::uint16 unicodeChar = 0x4E2D;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int16](int16.md) - 对应的有符号类型

docs/api/core/types/uint32.md

@@ -0,0 +1,30 @@
+# Types::uint32
+
+```cpp
+using uint32 = uint32_t;
+```
+
+32位无符号整数类型别名，对应 C++ 标准库的 `uint32_t` 类型。
+
+**描述**
+
+`uint32` 是 32 位（4 字节）无符号整数类型，范围为 0 到 4,294,967,295。常用于 ID、计数、大小等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint32 entityId = 1000000;
+Core::uint32 maxItems = 4294967295U;
+
+// 数组大小
+Core::uint32 arraySize = 1000;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int32](int32.md) - 对应的有符号类型

docs/api/core/types/uint64.md

@@ -0,0 +1,30 @@
+# Types::uint64
+
+```cpp
+using uint64 = uint64_t;
+```
+
+64位无符号整数类型别名，对应 C++ 标准库的 `uint64_t` 类型。
+
+**描述**
+
+`uint64` 是 64 位（8 字节）无符号整数类型，范围为 0 到 18,446,744,073,709,551,615。用于需要极大整数范围的场景，如大文件大小、精确时间等。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint64 largeFileSize = 1099511627776ULL;  // 1TB
+Core::uint64 maxValue = 18446744073709551615ULL;
+
+// 高精度时间戳（微秒）
+Core::uint64 microseconds = 1700000000000000ULL;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int64](int64.md) - 对应的有符号类型

docs/api/core/types/uint8.md

@@ -0,0 +1,30 @@
+# Types::uint8
+
+```cpp
+using uint8 = uint8_t;
+```
+
+8位无符号整数类型别名，对应 C++ 标准库的 `uint8_t` 类型。
+
+**描述**
+
+`uint8` 是 8 位（1 字节）无符号整数类型，范围为 0 到 255。常用于字节数据、颜色分量（RGB）等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint8 flags = 0xFF;
+Core::uint8 red = 255;
+
+// 字节数组
+Core::uint8 buffer[256];
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int8](int8.md) - 对应的有符号类型

docs/api/debug/consolelogsink/consolelogsink.md

@@ -0,0 +1,21 @@
+# ConsoleLogSink::ConsoleLogSink
+
+```cpp
+ConsoleLogSink()
+```
+
+默认构造函数。创建一个 `ConsoleLogSink` 实例，默认启用彩色输出，最小日志级别为 `Verbose`。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+```
+
+## 相关文档
+
+- [ConsoleLogSink 总览](overview.md) - 返回类总览
+- [Debug 模块总览](../debug.md) - 返回模块总览

docs/api/debug/consolelogsink/flush.md

@@ -0,0 +1,22 @@
+# ConsoleLogSink::Flush
+
+```cpp
+void Flush() override
+```
+
+刷新标准输出流（stdout），调用 `fflush(stdout)` 确保所有待输出的日志内容立即显示在控制台上。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+// 在程序异常退出前确保日志已输出
+XCEngine::Debug::Logger::Get().Flush();
+```
+
+## 相关文档
+
+- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

docs/api/debug/consolelogsink/log.md

@@ -0,0 +1,25 @@
+# ConsoleLogSink::Log
+
+```cpp
+void Log(const LogEntry& entry) override
+```
+
+将日志输出到控制台。根据 `LogEntry` 的级别和分类格式化输出内容，并根据 `m_colorOutput` 设置决定是否使用 Windows 控制台颜色 API。如果日志级别低于设置的最小级别，则不输出。
+
+**参数：**
+- `entry` - 日志条目
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+// Log 方法由 Logger 在内部调用，用户无需直接调用
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Hello console");
+```
+
+## 相关文档
+
+- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

docs/api/debug/consolelogsink/overview.md

@@ -0,0 +1,41 @@
+# ConsoleLogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Debug/ConsoleLogSink.h`
+
+**描述**: 控制台日志输出目标，将日志输出到标准输出流。
+
+## 概述
+
+`ConsoleLogSink` 是日志系统的控制台输出实现。它将日志条目输出到标准输出流（stdout），支持彩色输出和日志级别过滤。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `ConsoleLogSink()` | [构造函数](consolelogsink.md) |
+| `~ConsoleLogSink()` | [析构函数](~consolelogsink.md) |
+| `void Log(const LogEntry& entry)` | [输出日志到控制台](log.md) |
+| `void Flush()` | [刷新输出流](flush.md) |
+| `void SetColorOutput(bool enable)` | [设置彩色输出](setcoloroutput.md) |
+| `void SetMinimumLevel(LogLevel level)` | [设置最小日志级别](setminimumlevel.md) |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/ConsoleLogSink.h>
+
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+sink->SetColorOutput(true);
+sink->SetMinimumLevel(XCEngine::Debug::LogLevel::Warning);
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

docs/api/debug/consolelogsink/setcoloroutput.md

@@ -0,0 +1,24 @@
+# ConsoleLogSink::SetColorOutput
+
+```cpp
+void SetColorOutput(bool enable)
+```
+
+启用或禁用控制台彩色输出。启用后，不同日志级别使用 Windows 控制台颜色 API 输出，便于快速区分日志类型。
+
+**参数：**
+- `enable` - true 启用彩色输出，false 禁用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+sink->SetColorOutput(false); // 禁用颜色（适合日志文件或 CI 环境）
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+```
+
+## 相关文档
+
+- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

docs/api/debug/consolelogsink/setminimumlevel.md

@@ -0,0 +1,24 @@
+# ConsoleLogSink::SetMinimumLevel
+
+```cpp
+void SetMinimumLevel(LogLevel level)
+```
+
+设置该 Sink 的最小输出级别。此设置仅影响当前 Sink，不会影响 Logger 的全局级别过滤。
+
+**参数：**
+- `level` - 最小日志级别
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
+sink->SetMinimumLevel(XCEngine::Debug::LogLevel::Warning); // 控制台只显示警告及以上
+XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
+```
+
+## 相关文档
+
+- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

docs/api/debug/consolelogsink/~consolelogsink.md

@@ -0,0 +1,13 @@
+# ConsoleLogSink::~ConsoleLogSink
+
+```cpp
+~ConsoleLogSink() override
+```
+
+析构函数。销毁 `ConsoleLogSink` 实例，释放相关资源。
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

docs/api/debug/debug.md

@@ -0,0 +1,86 @@
+# Debug 模块概览
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `module`
+
+**描述**: XCEngine 的调试和日志模块，提供日志记录和性能分析功能。
+
+## 概述
+
+Debug 模块提供了一套完整的调试工具，包括日志系统和性能分析器。
+
+## 模块内容
+
+### 日志系统
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Logger](logger/logger.md) | `Logger.h` | 日志记录器 |
+| [ILogSink](ilogsink/ilogsink.md) | `ILogSink.h` | 日志输出接口 |
+| [ConsoleLogSink](consolelogsink/consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
+| [FileLogSink](filelogsink/filelogsink.md) | `FileLogSink.h` | 文件输出 |
+| [LogLevel](loglevel/loglevel.md) | `LogLevel.h` | 日志级别枚举 |
+| [LogCategory](logcategory/logcategory.md) | `LogCategory.h` | 日志分类枚举 |
+| [LogEntry](logentry/logentry.md) | `LogEntry.h` | 日志条目结构 |
+
+### 性能分析
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Profiler](profiler/profiler.md) | `Profiler.h` | 性能分析器 |
+
+## 日志级别
+
+| 级别 | 描述 |
+|------|------|
+| `Verbose` | 详细调试信息 |
+| `Debug` | 调试信息 |
+| `Info` | 一般信息 |
+| `Warning` | 警告信息 |
+| `Error` | 错误信息 |
+| `Fatal` | 致命错误 |
+
+## 日志分类
+
+| 分类 | 描述 |
+|------|------|
+| `General` | 通用 |
+| `Rendering` | 渲染 |
+| `Physics` | 物理 |
+| `Audio` | 音频 |
+| `Scripting` | 脚本 |
+| `Network` | 网络 |
+| `Memory` | 内存 |
+| `Threading` | 线程 |
+| `FileSystem` | 文件系统 |
+| `Custom` | 自定义 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/Debug.h>
+
+// 初始化日志系统
+Logger::Get().Initialize();
+Logger::Get().AddSink(std::make_unique<ConsoleLogSink>());
+Logger::Get().AddSink(std::make_unique<FileLogSink>("app.log"));
+
+// 设置日志级别
+Logger::Get().SetMinimumLevel(LogLevel::Debug);
+
+// 记录日志
+XE_LOG(LogCategory::Rendering, LogLevel::Info, "Render started");
+
+// 使用宏记录日志
+if (condition) {
+    XE_LOG(LogCategory::General, LogLevel::Error, "Something went wrong");
+}
+
+// 使用断言
+XE_ASSERT(ptr != nullptr, "Pointer must not be null");
+```
+
+## 相关文档
+
+- [Profiler](profiler/profiler.md) - 性能分析器

docs/api/debug/filelogsink/construct.md

@@ -0,0 +1,24 @@
+# FileLogSink::FileLogSink
+
+```cpp
+FileLogSink(const Containers::String& filePath)
+```
+
+构造函数，打开指定路径的文件用于日志写入。如果文件已存在，则追加写入；如果不存在，则创建新文件。
+
+**参数：**
+- `filePath` - 日志文件路径
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/engine.log");
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+```
+
+## 相关文档
+
+- [FileLogSink 总览](filelogsink.md) - 返回类总览
+- [Debug 模块总览](../debug.md) - 返回模块总览

docs/api/debug/filelogsink/filelogsink.md

@@ -0,0 +1,37 @@
+# FileLogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Debug/FileLogSink.h`
+
+**描述**: 文件日志输出目标，将日志写入到指定文件。
+
+## 概述
+
+`FileLogSink` 是日志系统的文件输出实现。它将日志条目写入到指定的文件，支持追加写入模式。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `FileLogSink(const Containers::String& filePath)` | [构造函数](construct.md) |
+| `~FileLogSink()` | [析构函数](~filelogsink.md) |
+| `void Log(const LogEntry& entry)` | [输出日志到文件](log.md) |
+| `void Flush()` | [刷新缓冲区](flush.md) |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/FileLogSink.h>
+
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

docs/api/debug/filelogsink/flush.md

@@ -0,0 +1,24 @@
+# FileLogSink::Flush
+
+```cpp
+void Flush() override
+```
+
+刷新文件缓冲区，调用底层 `FileWriter` 的 flush 方法确保所有待写入的日志数据已实际写入磁盘。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+// 关键操作后立即刷新
+XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Checkpoint saved");
+// 确保写入磁盘
+XCEngine::Debug::Logger::Get().Flush();
+```
+
+## 相关文档
+
+- [FileLogSink 总览](filelogsink.md) - 返回类总览

docs/api/debug/filelogsink/log.md

@@ -0,0 +1,25 @@
+# FileLogSink::Log
+
+```cpp
+void Log(const LogEntry& entry) override
+```
+
+将日志条目追加写入文件。根据 `LogEntry` 的各字段格式化日志行，包括时间戳、级别、分类、消息，并追加到文件末尾。
+
+**参数：**
+- `entry` - 日志条目
+
+**复杂度：** O(m)，m 为消息长度
+
+**示例：**
+
+```cpp
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+// Log 方法由 Logger 在内部调用
+XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::FileSystem, "File not found");
+```
+
+## 相关文档
+
+- [FileLogSink 总览](filelogsink.md) - 返回类总览