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/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) - 返回类总览

docs/api/debug/filelogsink/~filelogsink.md

@@ -0,0 +1,13 @@
+# FileLogSink::~FileLogSink
+
+```cpp
+~FileLogSink() override
+```
+
+析构函数。销毁 `FileLogSink` 实例，调用 `Flush()` 确保所有日志数据写入文件，然后关闭文件句柄。
+
+**复杂度：** O(1)
+
+## 相关文档
+
+- [FileLogSink 总览](filelogsink.md) - 返回类总览

docs/api/debug/ilogsink/flush.md

@@ -0,0 +1,32 @@
+# ILogSink::Flush
+
+```cpp
+virtual void Flush() = 0
+```
+
+刷新输出缓冲区，确保所有待写入的日志数据已实际写入目标介质。对于文件类 Sink，应调用底层文件系统的 flush；对于网络类 Sink，应发送缓冲区中的数据。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+class BufferedLogSink : public XCEngine::Debug::ILogSink {
+private:
+    std::string m_buffer;
+public:
+    void Log(const XCEngine::Debug::LogEntry& entry) override {
+        m_buffer += entry.message.CStr();
+        m_buffer += "\n";
+    }
+    void Flush() override {
+        // 将缓冲区数据写入目标
+        writeToDestination(m_buffer);
+        m_buffer.clear();
+    }
+};
+```
+
+## 相关文档
+
+- [ILogSink 总览](ilogsink.md) - 返回类总览

docs/api/debug/ilogsink/ilogsink.md

@@ -0,0 +1,45 @@
+# ILogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (abstract interface)
+
+**描述**: 日志输出槽抽象接口，定义日志输出的标准协议。
+
+## 概述
+
+`ILogSink` 是日志系统的输出抽象接口。用户可以实现此接口来创建自定义的日志输出方式，如网络输出、数据库存储等。`Logger` 通过多个 Sink 分发日志。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `virtual void Log(const LogEntry& entry) = 0` | [输出单条日志](log.md) |
+| `virtual void Flush() = 0` | [刷新缓冲区，确保日志写入](flush.md) |
+
+## 使用示例
+
+```cpp
+class CustomLogSink : public ILogSink {
+public:
+    void Log(const LogEntry& entry) override {
+        printf("[%s] %s: %s\n",
+               LogLevelToString(entry.level),
+               LogCategoryToString(entry.category),
+               entry.message.CStr());
+    }
+    
+    void Flush() override {
+        fflush(stdout);
+    }
+};
+
+Logger::Get().AddSink(std::make_unique<CustomLogSink>());
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器
+- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出
+- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出

docs/api/debug/ilogsink/log.md

@@ -0,0 +1,29 @@
+# ILogSink::Log
+
+```cpp
+virtual void Log(const LogEntry& entry) = 0
+```
+
+输出单条日志到目标介质。`Logger` 在每次日志记录时调用此方法，将包含完整日志信息的 `LogEntry` 传入。派生类需要实现具体的输出逻辑。
+
+**参数：**
+- `entry` - 日志条目，包含级别、分类、消息、时间戳、线程 ID 等完整信息
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+class NetworkLogSink : public XCEngine::Debug::ILogSink {
+public:
+    void Log(const XCEngine::Debug::LogEntry& entry) override {
+        // 将日志发送到远程服务器
+        sendToServer(entry.message.CStr());
+    }
+    void Flush() override { }
+};
+```
+
+## 相关文档
+
+- [ILogSink 总览](ilogsink.md) - 返回类总览

docs/api/debug/logcategory/logcategory.md

@@ -0,0 +1,44 @@
+# LogCategory
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `enum class`
+
+**描述**: 日志分类枚举，定义日志的来源模块。
+
+## 概述
+
+`LogCategory` 枚举定义了日志的分类，用于区分不同引擎模块的日志输出。
+
+## 枚举值
+
+| 值 | 说明 |
+|----|------|
+| `General` | 通用 |
+| `Rendering` | 渲染 |
+| `Physics` | 物理 |
+| `Audio` | 音频 |
+| `Scripting` | 脚本 |
+| `Network` | 网络 |
+| `Memory` | 内存 |
+| `Threading` | 线程 |
+| `FileSystem` | 文件系统 |
+| `Custom` | 自定义 |
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| `const char* LogCategoryToString(LogCategory category)` | [将日志分类转换为字符串](logcategorytostring.md) |
+
+## 使用示例
+
+```cpp
+Logger::Get().SetCategoryEnabled(LogCategory::Network, false);
+XE_LOG(LogCategory::Rendering, LogLevel::Info, "Draw call submitted");
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器

docs/api/debug/logcategory/logcategorytostring.md

@@ -0,0 +1,28 @@
+# LogCategoryToString
+
+```cpp
+const char* LogCategoryToString(LogCategory category)
+```
+
+将 `LogCategory` 枚举值转换为可读字符串。
+
+**参数：**
+- `category` - 日志分类
+
+**返回：** 对应分类的字符串（"General", "Rendering", "Physics" 等）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/LogCategory.h>
+
+XCEngine::Debug::LogCategory cat = XCEngine::Debug::LogCategory::Rendering;
+const char* str = XCEngine::Debug::LogCategoryToString(cat);
+// str == "Rendering"
+```
+
+## 相关文档
+
+- [LogCategory 总览](logcategory.md) - 返回类总览

docs/api/debug/logentry/logentry.md

@@ -0,0 +1,47 @@
+# LogEntry
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `struct`
+
+**描述**: 日志条目结构体，包含单条日志的所有信息。
+
+## 概述
+
+`LogEntry` 是日志系统的核心数据结构，每次日志记录都生成一个 `LogEntry` 并分发给所有注册的 Sink。
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `level` | `LogLevel` | 日志级别 |
+| `category` | `LogCategory` | 日志分类 |
+| `message` | `Containers::String` | 日志消息内容 |
+| `file` | `Containers::String` | 源代码文件路径 |
+| `line` | `int32_t` | 源代码行号 |
+| `function` | `Containers::String` | 函数名称 |
+| `timestamp` | `uint64_t` | 时间戳（秒，Unix 时间戳） |
+| `threadId` | `uint32_t` | 线程 ID |
+
+## 使用示例
+
+```cpp
+class MySink : public ILogSink {
+public:
+    void Log(const LogEntry& entry) override {
+        printf("[%llu][%u] %s::%s: %s\n",
+            (unsigned long long)entry.timestamp,
+            (unsigned)entry.threadId,
+            LogCategoryToString(entry.category),
+            LogLevelToString(entry.level),
+            entry.message.CStr());
+    }
+    void Flush() override { }
+};
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
+- [Logger](../logger/logger.md) - 日志记录器

docs/api/debug/logger/addsink.md

@@ -0,0 +1,27 @@
+# Logger::AddSink
+
+```cpp
+void AddSink(std::unique_ptr<ILogSink> sink)
+```
+
+向日志系统添加一个输出目标（Sink）。Logger 持有 Sink 的所有权，传入的 `unique_ptr` 被移动到内部容器中。每次日志记录时，所有已注册的 Sink 的 `Log` 方法都会被调用。
+
+**参数：**
+- `sink` - 要添加的日志输出目标，使用 `std::unique_ptr` 包装
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Initialize();
+XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
+XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::FileLogSink>("app.log"));
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

docs/api/debug/logger/debug.md

@@ -0,0 +1,30 @@
+# Logger::Debug
+
+```cpp
+void Debug(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Debug（1 级）日志。Debug 级别用于一般调试信息，比 Verbose 简洁但比 Info 详细。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Debug(
+    XCEngine::Debug::LogCategory::Rendering,
+    "Draw call batch size: 512"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/error.md

@@ -0,0 +1,30 @@
+# Logger::Error
+
+```cpp
+void Error(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Error（4 级）日志。Error 级别用于表示程序执行中发生的错误，如文件读取失败、网络连接中断等。程序通常可以继续运行但功能可能受限。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Error(
+    XCEngine::Debug::LogCategory::Network,
+    "Failed to connect to game server"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/fatal.md

@@ -0,0 +1,30 @@
+# Logger::Fatal
+
+```cpp
+void Fatal(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Fatal（5 级）日志。Fatal 级别用于表示不可恢复的严重错误，通常意味着程序即将终止。此方法可能在记录日志后触发程序中断。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Fatal(
+    XCEngine::Debug::LogCategory::General,
+    "Out of memory - cannot continue"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/get.md

@@ -0,0 +1,22 @@
+# Logger::Get
+
+```cpp
+static Logger& Get()
+```
+
+获取 `Logger` 单例实例。Logger 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。
+
+**返回：** `Logger&` - 全局日志记录器实例的引用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Debug::Logger& logger = XCEngine::Debug::Logger::Get();
+logger.Initialize();
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/info.md

@@ -0,0 +1,30 @@
+# Logger::Info
+
+```cpp
+void Info(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Info（2 级）日志。Info 级别用于一般性信息，如启动提示、配置加载等用户可见的正常运行消息。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Info(
+    XCEngine::Debug::LogCategory::General,
+    "Application initialized successfully"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/initialize.md

@@ -0,0 +1,28 @@
+# Logger::Initialize
+
+```cpp
+void Initialize()
+```
+
+初始化日志系统。在首次使用日志功能前必须调用。初始化内部状态标志，确保日志系统已准备好工作。
+
+**注意：** 默认最小日志级别为 `Verbose`，所有日志分类默认启用，这些是类成员变量的默认值，不需要在此方法中设置。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+int main() {
+    XCEngine::Debug::Logger::Get().Initialize();
+    XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
+    XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Application started");
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/log.md

@@ -0,0 +1,45 @@
+# Logger::Log
+
+```cpp
+void Log(LogLevel level, LogCategory category,
+         const Containers::String& message, const char* file = nullptr,
+         int32_t line = 0, const char* function = nullptr)
+```
+
+通用日志记录方法。根据设置的最小日志级别和分类开关决定是否输出，然后将日志分发给所有已注册的 Sink。如果日志级别低于最小级别或分类被禁用，则不输出。
+
+**参数：**
+- `level` - 日志级别（Verbose, Debug, Info, Warning, Error, Fatal）
+- `category` - 日志分类（General, Rendering, Physics 等）
+- `message` - 日志消息内容
+- `file` - 源代码文件路径（可选，默认 nullptr）
+- `line` - 源代码行号（可选，默认 0）
+- `function` - 函数名称（可选，默认 nullptr）
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Log(
+    XCEngine::Debug::LogLevel::Error,
+    XCEngine::Debug::LogCategory::FileSystem,
+    "Failed to open config file",
+    __FILE__,
+    __LINE__,
+    __FUNCTION__
+);
+
+// 推荐使用 XE_LOG 宏自动填充位置信息
+XE_LOG(XCEngine::Debug::LogCategory::General, XCEngine::Debug::LogLevel::Info, "Initialized");
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举
+- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举

docs/api/debug/logger/logger.md

@@ -0,0 +1,92 @@
+# Logger
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (singleton)
+
+**头文件**: `XCEngine/Debug/Logger.h`
+
+**描述**: 全局日志记录器单例，提供多级别、多分类的日志输出。
+
+## 概述
+
+`Logger` 是 XCEngine 的核心日志系统单例。它支持多个日志输出目标（Sink）、日志级别过滤、分类开关，并提供宏方便使用。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static Logger& Get()` | 获取单例实例 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | [初始化日志系统](initialize.md) |
+| `void Shutdown()` | [关闭日志系统](shutdown.md) |
+| `void AddSink(std::unique_ptr<ILogSink> sink)` | [添加日志输出目标](addsink.md) |
+| `void RemoveSink(ILogSink* sink)` | [移除日志输出目标](removesink.md) |
+| `void Log(...)` | [通用日志记录](log.md) |
+| `void Verbose(...)` | [Verbose 级别日志](verbose.md) |
+| `void Debug(...)` | [Debug 级别日志](debug.md) |
+| `void Info(...)` | [Info 级别日志](info.md) |
+| `void Warning(...)` | [Warning 级别日志](warning.md) |
+| `void Error(...)` | [Error 级别日志](error.md) |
+| `void Fatal(...)` | [Fatal 级别日志](fatal.md) |
+| `void SetMinimumLevel(...)` | [设置最小日志级别](setminimumlevel.md) |
+| `void SetCategoryEnabled(...)` | [开启/关闭指定分类](setcategoryenabled.md) |
+
+## 宏定义
+
+### XE_LOG
+
+```cpp
+#define XE_LOG(category, level, message) \
+    XCEngine::Debug::Logger::Get().Log(level, category, message, __FILE__, __LINE__, __FUNCTION__)
+```
+
+通用日志宏，自动填充文件名、行号和函数名。
+
+### XE_ASSERT
+
+```cpp
+#define XE_ASSERT(condition, message) \
+    if (!(condition)) { \
+        XCEngine::Debug::Logger::Get().Fatal(XCEngine::Debug::LogCategory::General, message); \
+    }
+```
+
+断言宏，条件失败时记录 Fatal 日志。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/Logger.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);
+
+// 使用便捷方法
+Logger::Get().Info(LogCategory::Rendering, "Render started");
+Logger::Get().Warning(LogCategory::Memory, "High memory usage");
+Logger::Get().Error(LogCategory::FileSystem, "Failed to load file");
+
+// 使用宏（自动带位置信息）
+XE_LOG(LogCategory::General, LogLevel::Info, "Application initialized");
+
+// 使用断言
+XE_ASSERT(ptr != nullptr, "Pointer must not be null");
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
+- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出
+- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举

docs/api/debug/logger/removesink.md

@@ -0,0 +1,29 @@
+# Logger::RemoveSink
+
+```cpp
+void RemoveSink(ILogSink* sink)
+```
+
+从日志系统移除指定的输出目标。通过指针查找并移除对应的 Sink，Logger 不再向该目标发送日志。
+
+**参数：**
+- `sink` - 要移除的日志输出目标指针
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("app.log");
+XCEngine::Debug::FileLogSink* rawPtr = fileSink.get();
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+// 稍后移除
+XCEngine::Debug::Logger::Get().RemoveSink(rawPtr);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

docs/api/debug/logger/setcategoryenabled.md

@@ -0,0 +1,36 @@
+# Logger::SetCategoryEnabled
+
+```cpp
+void SetCategoryEnabled(LogCategory category, bool enabled)
+```
+
+启用或禁用指定分类的日志输出。当分类被禁用时，该分类的所有日志都不会分发给 Sink，但级别过滤仍然适用。
+
+**参数：**
+- `category` - 要设置的日志分类
+- `enabled` - true 表示启用，false 表示禁用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+// 禁用网络模块日志（减少日志噪音）
+XCEngine::Debug::Logger::Get().SetCategoryEnabled(
+    XCEngine::Debug::LogCategory::Network,
+    false
+);
+
+// 稍后重新启用
+XCEngine::Debug::Logger::Get().SetCategoryEnabled(
+    XCEngine::Debug::LogCategory::Network,
+    true
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举

docs/api/debug/logger/setminimumlevel.md

@@ -0,0 +1,30 @@
+# Logger::SetMinimumLevel
+
+```cpp
+void SetMinimumLevel(LogLevel level)
+```
+
+设置日志系统的最小输出级别。所有低于该级别的日志将被过滤，不会分发给任何 Sink。
+
+**参数：**
+- `level` - 最小日志级别
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+// 只输出 Warning 及以上级别的日志
+XCEngine::Debug::Logger::Get().SetMinimumLevel(XCEngine::Debug::LogLevel::Warning);
+
+// Verbose 和 Debug 级别的日志将被过滤
+XCEngine::Debug::Logger::Get().Verbose(XCEngine::Debug::LogCategory::General, "This will not be logged");
+XCEngine::Debug::Logger::Get().Warning(XCEngine::Debug::LogCategory::General, "This will be logged");
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举

docs/api/debug/logger/shutdown.md

@@ -0,0 +1,26 @@
+# Logger::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭日志系统。移除所有注册的 Sink，刷新缓冲区并重置内部状态。在程序退出前调用，确保所有日志数据已写入输出目标。
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+int main() {
+    XCEngine::Debug::Logger::Get().Initialize();
+    // ... 应用逻辑 ...
+    XCEngine::Debug::Logger::Get().Shutdown();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/verbose.md

@@ -0,0 +1,30 @@
+# Logger::Verbose
+
+```cpp
+void Verbose(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Verbose（0 级）日志。Verbose 是最详细的日志级别，用于输出大量调试细节。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Verbose(
+    XCEngine::Debug::LogCategory::Memory,
+    "Memory pool fragmentation: 12.5%"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/logger/warning.md

@@ -0,0 +1,30 @@
+# Logger::Warning
+
+```cpp
+void Warning(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Warning（3 级）日志。Warning 级别用于指示潜在问题但程序仍可继续运行的情况，如资源即将耗尽、配置值超出建议范围等。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Warning(
+    XCEngine::Debug::LogCategory::Memory,
+    "Memory usage exceeds 80% of available heap"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览

docs/api/debug/loglevel/loglevel.md

@@ -0,0 +1,40 @@
+# LogLevel
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `enum class`
+
+**描述**: 日志级别枚举，定义日志的严重程度。
+
+## 概述
+
+`LogLevel` 枚举定义了从最详细到最严重的日志级别。`Logger` 根据设置的最小级别过滤日志。
+
+## 枚举值
+
+| 值 | 说明 | 数值 |
+|----|------|------|
+| `Verbose` | 详细调试信息 | 0 |
+| `Debug` | 调试信息 | 1 |
+| `Info` | 一般信息 | 2 |
+| `Warning` | 警告信息 | 3 |
+| `Error` | 错误信息 | 4 |
+| `Fatal` | 致命错误 | 5 |
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| `const char* LogLevelToString(LogLevel level)` | [将日志级别转换为字符串](logleveltostring.md) |
+
+## 使用示例
+
+```cpp
+Logger::Get().SetMinimumLevel(LogLevel::Warning);
+// 只有 Warning、Error、Fatal 级别的日志会被输出
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器

docs/api/debug/loglevel/logleveltostring.md

@@ -0,0 +1,28 @@
+# LogLevelToString
+
+```cpp
+const char* LogLevelToString(LogLevel level)
+```
+
+将 `LogLevel` 枚举值转换为可读字符串。
+
+**参数：**
+- `level` - 日志级别
+
+**返回：** 对应级别的字符串（"VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR", "FATAL"）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/LogLevel.h>
+
+XCEngine::Debug::LogLevel level = XCEngine::Debug::LogLevel::Error;
+const char* str = XCEngine::Debug::LogLevelToString(level);
+// str == "ERROR"
+```
+
+## 相关文档
+
+- [LogLevel 总览](loglevel.md) - 返回类总览

docs/api/debug/profiler/beginframe.md

@@ -0,0 +1,26 @@
+# Profiler::BeginFrame
+
+```cpp
+void BeginFrame()
+```
+
+开始一帧的性能分析。记录当前帧的起始时间戳，用于计算帧级别的性能指标。应在每帧渲染开始时调用。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+void GameLoop() {
+    XCEngine::Debug::Profiler::Get().BeginFrame();
+    Update();
+    Render();
+    XCEngine::Debug::Profiler::Get().EndFrame();
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/beginprofile.md

@@ -0,0 +1,36 @@
+# Profiler::BeginProfile
+
+```cpp
+void BeginProfile(const char* name)
+```
+
+开始一个性能分析块。将分析节点压入栈中并记录开始时间。每次调用 `BeginProfile` 应与一次 `EndProfile` 配对使用。
+
+**参数：**
+- `name` - 分析块的名称，用于在导出结果中标识
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+void ProcessMesh() {
+    XCEngine::Debug::Profiler::Get().BeginProfile("ProcessMesh");
+    
+    XCEngine::Debug::Profiler::Get().BeginProfile("ComputeVertices");
+    ComputeVertices();
+    XCEngine::Debug::Profiler::Get().EndProfile();
+    
+    XCEngine::Debug::Profiler::Get().BeginProfile("ComputeIndices");
+    ComputeIndices();
+    XCEngine::Debug::Profiler::Get().EndProfile();
+    
+    XCEngine::Debug::Profiler::Get().EndProfile();
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/endframe.md

@@ -0,0 +1,26 @@
+# Profiler::EndFrame
+
+```cpp
+void EndFrame()
+```
+
+结束一帧的性能分析。记录当前帧的结束时间，计算帧耗时并可用于帧率统计。应在每帧渲染结束时调用。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+void GameLoop() {
+    XCEngine::Debug::Profiler::Get().BeginFrame();
+    Update();
+    Render();
+    XCEngine::Debug::Profiler::Get().EndFrame();
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/endprofile.md

@@ -0,0 +1,25 @@
+# Profiler::EndProfile
+
+```cpp
+void EndProfile()
+```
+
+结束当前性能分析块。从栈顶弹出分析节点并计算持续时间（endTime - startTime），将结果保存到样本列表中。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+void RenderPipeline() {
+    XCEngine::Debug::Profiler::Get().BeginProfile("RenderPipeline");
+    // ... 渲染逻辑 ...
+    XCEngine::Debug::Profiler::Get().EndProfile();
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/exportchrometracing.md

@@ -0,0 +1,45 @@
+# Profiler::ExportChromeTracing
+
+```cpp
+void ExportChromeTracing(const Containers::String& filePath)
+```
+
+**状态：** 此方法目前为空实现，暂未功能。
+
+将收集的性能数据导出为 Chrome Tracing JSON 格式。导出的文件可通过 Chrome 浏览器打开（地址栏输入 `chrome://tracing` 并加载文件）进行可视化分析。
+
+**参数：**
+- `filePath` - 输出文件路径
+
+**复杂度：** O(n)，n 为记录的样本数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+XCEngine::Debug::Profiler::Get().Initialize();
+
+void RenderFrame() {
+    XCEngine::Debug::Profiler::Get().BeginFrame();
+    XE_PROFILE_FUNCTION();
+    
+    XE_PROFILE_BEGIN("UpdateScene");
+    UpdateScene();
+    XE_PROFILE_END();
+    
+    XE_PROFILE_BEGIN("DrawScene");
+    DrawScene();
+    XE_PROFILE_END();
+    
+    XCEngine::Debug::Profiler::Get().EndFrame();
+}
+
+// 运行一段时间后导出
+XCEngine::Debug::Profiler::Get().ExportChromeTracing("trace.json");
+XCEngine::Debug::Profiler::Get().Shutdown();
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/get.md

@@ -0,0 +1,22 @@
+# Profiler::Get
+
+```cpp
+static Profiler& Get()
+```
+
+获取 `Profiler` 单例实例。Profiler 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。
+
+**返回：** `Profiler&` - 全局性能分析器实例的引用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Debug::Profiler& profiler = XCEngine::Debug::Profiler::Get();
+profiler.Initialize();
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/initialize.md

@@ -0,0 +1,30 @@
+# Profiler::Initialize
+
+```cpp
+void Initialize()
+```
+
+初始化性能分析器。在首次使用性能分析功能前必须调用。初始化内部状态标志，确保分析器已准备好工作。
+
+**注意：** 帧计时器等数据结构在首次 BeginFrame 时自动初始化。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+int main() {
+    XCEngine::Debug::Profiler::Get().Initialize();
+    XCEngine::Debug::Profiler::Get().BeginFrame();
+    // ... 性能测量 ...
+    XCEngine::Debug::Profiler::Get().EndFrame();
+    XCEngine::Debug::Profiler::Get().Shutdown();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/markevent.md

@@ -0,0 +1,36 @@
+# Profiler::MarkEvent
+
+```cpp
+void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)
+```
+
+**状态：** 此方法目前为空实现，暂未功能。
+
+在指定时间点标记一个事件。用于记录离散的瞬时事件，如 GPU 命令提交、状态切换等，通常用于多线程性能分析。
+
+**参数：**
+- `name` - 事件名称
+- `timestamp` - 事件发生的时间戳（微秒）
+- `threadId` - 事件所属的线程 ID
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+// 在多线程场景中标记事件
+void WorkerThread() {
+    uint32_t tid = GetCurrentThreadId();
+    uint64_t ts = GetTickCount();
+    
+    XCEngine::Debug::Profiler::Get().MarkEvent("TaskStarted", ts, tid);
+    DoWork();
+    XCEngine::Debug::Profiler::Get().MarkEvent("TaskCompleted", GetTickCount(), tid);
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/profiler.md

@@ -0,0 +1,136 @@
+# Profiler
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (singleton)
+
+**描述**: 性能分析器单例，用于测量代码块执行时间并支持 Chrome Tracing 格式导出。
+
+## 概述
+
+`Profiler` 是 XCEngine 的性能分析工具。它通过栈式记录和采样方式跟踪函数执行时间，支持导出为 Chrome Tracing 格式（可通过 Chrome 的 `chrome://tracing` 查看）。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static Profiler& Get()` | 获取单例实例 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | [初始化性能分析器](initialize.md) |
+| `void Shutdown()` | [关闭性能分析器](shutdown.md) |
+| `void BeginProfile(const char* name)` | [开始一个性能分析块](beginprofile.md) |
+| `void EndProfile()` | [结束当前性能分析块](endprofile.md) |
+| `void BeginFrame()` | [开始一帧的分析](beginframe.md) |
+| `void EndFrame()` | [结束一帧的分析](endframe.md) |
+| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | [标记一个事件点](markevent.md) |
+| `void SetMarker(const char* name, uint32_t color)` | [设置帧标记](setmarker.md) |
+| `void ExportChromeTracing(const Containers::String& filePath)` | [导出为 Chrome Tracing JSON 格式](exportchrometracing.md) |
+
+## 宏定义
+
+### XE_PROFILE_BEGIN
+
+```cpp
+#define XE_PROFILE_BEGIN(name) XCEngine::Debug::Profiler::Get().BeginProfile(name)
+```
+
+开始分析指定名称的代码块。
+
+### XE_PROFILE_END
+
+```cpp
+#define XE_PROFILE_END() XCEngine::Debug::Profiler::Get().EndProfile()
+```
+
+结束当前分析块。
+
+### XE_PROFILE_FUNCTION
+
+```cpp
+#define XE_PROFILE_FUNCTION() XE_PROFILE_BEGIN(__FUNCTION__)
+```
+
+自动使用当前函数名进行分析。
+
+## 私有成员
+
+### ProfileNode
+
+```cpp
+struct ProfileNode {
+    const char* name;
+    uint64_t startTime;
+    uint64_t endTime;
+    uint32_t threadId;
+};
+```
+
+内部使用的性能分析节点结构，用于在栈上跟踪嵌套的分析块。
+
+### ProfileSample
+
+```cpp
+struct ProfileSample {
+    const char* name;
+    uint64_t duration;
+    uint32_t threadId;
+};
+```
+
+记录单个性能样本的结构，包含名称、持续时间和线程 ID。
+
+## 成员变量
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `m_profileStack` | `std::vector<ProfileNode>` | 分析块栈，用于跟踪嵌套调用 |
+| `m_samples` | `std::vector<ProfileSample>` | 样本列表，记录完成的性能数据 |
+| `m_frameStartTime` | `uint64_t` | 当前帧开始时间戳（微秒） |
+| `m_initialized` | `bool` | 初始化标志 |
+
+## 实现状态
+
+以下方法目前为存根（stub）实现，尚未完成功能：
+
+| 方法 | 状态 |
+|------|------|
+| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | 存根 |
+| `void SetMarker(const char* name, uint32_t color)` | 存根 |
+| `void ExportChromeTracing(const Containers::String& filePath)` | 存根 |
+
+## 使用示例
+
+```cpp
+Profiler::Get().Initialize();
+
+void RenderFrame() {
+    XE_PROFILE_FUNCTION();
+    
+    {
+        XE_PROFILE_BEGIN("UpdateGeometry");
+        UpdateGeometry();
+        XE_PROFILE_END();
+    }
+    
+    {
+        XE_PROFILE_BEGIN("DrawCalls");
+        DrawCalls();
+        XE_PROFILE_END();
+    }
+}
+
+Profiler::Get().BeginFrame();
+// ... 渲染帧 ...
+Profiler::Get().EndFrame();
+Profiler::Get().ExportChromeTracing("profile.json");
+Profiler::Get().Shutdown();
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [Logger](../logger/logger.md) - 日志记录器

docs/api/debug/profiler/setmarker.md

@@ -0,0 +1,33 @@
+# Profiler::SetMarker
+
+```cpp
+void SetMarker(const char* name, uint32_t color)
+```
+
+**状态：** 此方法目前为空实现，暂未功能。
+
+在 Chrome Tracing 时间线上设置一个标记点，用于标记特定位置或状态。标记会显示为一条垂直线，便于在性能图中定位关键事件。
+
+**参数：**
+- `name` - 标记名称
+- `color` - 标记颜色（ABGR 格式）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Profiler.h>
+
+void OnVBlank() {
+    XCEngine::Debug::Profiler::Get().SetMarker("VBlank", 0xFF00FF00); // 绿色
+}
+
+void OnRenderComplete() {
+    XCEngine::Debug::Profiler::Get().SetMarker("FrameRendered", 0xFFFF0000); // 红色
+}
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览

docs/api/debug/profiler/shutdown.md

@@ -0,0 +1,22 @@
+# Profiler::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭性能分析器。清理内部数据结构，停止所有活动分析块，重置状态。在程序退出前调用。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Debug::Profiler::Get().Initialize();
+// ... 使用 Profiler ...
+XCEngine::Debug::Profiler::Get().ExportChromeTracing("profile.json");
+XCEngine::Debug::Profiler::Get().Shutdown();
+```
+
+## 相关文档
+
+- [Profiler 总览](profiler.md) - 返回类总览