refactor: reorganize docs into plan/ and add skills/

2026-03-18 17:49:22 +08:00
parent fc7c8f6797
commit 9bad996ecf
143 changed files with 13263 additions and 0 deletions
--- a/docs/api/debug/debug-consolelogsink.md
+++ b/docs/api/debug/debug-consolelogsink.md
@@ -0,0 +1,52 @@
+# ConsoleLogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class`
+
+**描述**: 控制台日志输出槽，将日志输出到标准控制台，支持彩色输出。
+
+## 概述
+
+`ConsoleLogSink` 是 `ILogSink` 的控制台实现。它将日志输出到 stdout/stderr，支持按日志级别设置不同颜色。
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| `ConsoleLogSink()` | 默认构造函数 |
+| `~ConsoleLogSink()` | 析构函数 |
+
+### ILogSink 实现
+
+| 方法 | 描述 |
+|------|------|
+| `void Log(const LogEntry& entry) override` | 输出日志到控制台 |
+| `void Flush() override` | 刷新标准输出流 |
+
+### 配置
+
+| 方法 | 描述 |
+|------|------|
+| `void SetColorOutput(bool enable)` | 启用/禁用彩色输出 |
+| `void SetMinimumLevel(LogLevel level)` | 设置最小输出级别 |
+
+## 使用示例
+
+```cpp
+// 创建并配置
+auto sink = std::make_unique<ConsoleLogSink>();
+sink->SetColorOutput(true);
+sink->SetMinimumLevel(LogLevel::Debug);
+
+// 添加到 Logger
+Logger::Get().AddSink(std::move(sink));
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器
+- [ILogSink](./debug-ilogsink.md) - 日志输出接口
+- [FileLogSink](./debug-filelogsink.md) - 文件输出
--- a/docs/api/debug/debug-filelogsink.md
+++ b/docs/api/debug/debug-filelogsink.md
@@ -0,0 +1,47 @@
+# FileLogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class`
+
+**描述**: 文件日志输出槽，将日志持久化到磁盘文件。
+
+## 概述
+
+`FileLogSink` 是 `ILogSink` 的文件实现。它使用 `FileWriter` 将日志追加写入文件，支持自动换行和缓冲区刷新。
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| `FileLogSink(const Containers::String& filePath)` | 构造函数，指定文件路径 |
+| `~FileLogSink()` | 析构函数 |
+
+### ILogSink 实现
+
+| 方法 | 描述 |
+|------|------|
+| `void Log(const LogEntry& entry) override` | 将日志追加写入文件 |
+| `void Flush() override` | 刷新文件缓冲区 |
+
+## 使用示例
+
+```cpp
+// 创建文件日志输出
+auto fileSink = std::make_unique<FileLogSink>("logs/app.log");
+
+// 添加到 Logger
+Logger::Get().AddSink(std::move(fileSink));
+
+// 日志将自动写入文件
+XE_LOG(LogCategory::General, LogLevel::Info, "Game started");
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器
+- [ILogSink](./debug-ilogsink.md) - 日志输出接口
+- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
+- [Core/FileWriter](../core/core-filewriter.md) - 文件写入工具
--- a/docs/api/debug/debug-ilogsink.md
+++ b/docs/api/debug/debug-ilogsink.md
@@ -0,0 +1,47 @@
+# ILogSink
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (abstract interface)
+
+**描述**: 日志输出槽抽象接口，定义日志输出的标准协议。
+
+## 概述
+
+`ILogSink` 是日志系统的输出抽象接口。用户可以实现此接口来创建自定义的日志输出方式，如网络输出、数据库存储等。`Logger` 通过多个 Sink 分发日志。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `virtual void Log(const LogEntry& entry) = 0` | 输出单条日志 |
+| `virtual void Flush() = 0` | 刷新缓冲区，确保日志写入 |
+
+## 使用示例
+
+```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);
+    }
+};
+
+// 注册自定义 Sink
+Logger::Get().AddSink(std::make_unique<CustomLogSink>());
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器
+- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
+- [FileLogSink](./debug-filelogsink.md) - 文件输出
--- a/docs/api/debug/debug-logcategory.md
+++ b/docs/api/debug/debug-logcategory.md
@@ -0,0 +1,46 @@
+# LogCategory
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `enum class`
+
+**描述**: 日志分类枚举，定义日志的来源模块。
+
+## 概述
+
+`LogCategory` 枚举定义了日志的分类，用于区分不同引擎模块的日志输出。
+
+## 枚举值
+
+| 值 | 说明 |
+|----|------|
+| `General` | 通用 |
+| `Rendering` | 渲染 |
+| `Physics` | 物理 |
+| `Audio` | 音频 |
+| `Scripting` | 脚本 |
+| `Network` | 网络 |
+| `Memory` | 内存 |
+| `Threading` | 线程 |
+| `FileSystem` | 文件系统 |
+| `Custom` | 自定义 |
+
+## 辅助函数
+
+| 函数 | 描述 |
+|------|------|
+| `const char* LogCategoryToString(LogCategory category)` | 将日志分类转换为字符串 |
+
+## 使用示例
+
+```cpp
+// 禁用网络日志
+Logger::Get().SetCategoryEnabled(LogCategory::Network, false);
+
+// 输出分类日志
+XE_LOG(LogCategory::Rendering, LogLevel::Info, "Draw call submitted");
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器
--- a/docs/api/debug/debug-logentry.md
+++ b/docs/api/debug/debug-logentry.md
@@ -0,0 +1,48 @@
+# 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` | 时间戳（毫秒） |
+| `threadId` | `uint32_t` | 线程 ID |
+
+## 使用示例
+
+```cpp
+// 实现自定义 Sink 时访问 LogEntry
+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 { }
+};
+```
+
+## 相关文档
+
+- [ILogSink](./debug-ilogsink.md) - 日志输出接口
+- [Logger](./debug-logger.md) - 日志记录器
--- a/docs/api/debug/debug-logger.md
+++ b/docs/api/debug/debug-logger.md
@@ -0,0 +1,108 @@
+# Logger
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (singleton)
+
+**头文件**: `XCEngine/Debug/Logger.h`
+
+**描述**: 全局日志记录器单例，提供多级别、多分类的日志输出。
+
+## 概述
+
+`Logger` 是 XCEngine 的核心日志系统单例。它支持多个日志输出目标（Sink）、日志级别过滤、分类开关，并提供宏方便使用。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static Logger& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | 初始化日志系统 |
+| `void Shutdown()` | 关闭日志系统 |
+
+### Sink 管理
+
+| 方法 | 描述 |
+|------|------|
+| `void AddSink(std::unique_ptr<ILogSink> sink)` | 添加日志输出目标 |
+| `void RemoveSink(ILogSink* sink)` | 移除日志输出目标 |
+
+### 日志记录
+
+| 方法 | 描述 |
+|------|------|
+| `void Log(LogLevel level, LogCategory category, const Containers::String& message, const char* file = nullptr, int32_t line = 0, const char* function = nullptr)` | 通用日志记录 |
+| `void Verbose(LogCategory category, const Containers::String& message)` | Verbose 级别日志 |
+| `void Debug(LogCategory category, const Containers::String& message)` | Debug 级别日志 |
+| `void Info(LogCategory category, const Containers::String& message)` | Info 级别日志 |
+| `void Warning(LogCategory category, const Containers::String& message)` | Warning 级别日志 |
+| `void Error(LogCategory category, const Containers::String& message)` | Error 级别日志 |
+| `void Fatal(LogCategory category, const Containers::String& message)` | Fatal 级别日志 |
+
+### 配置
+
+| 方法 | 描述 |
+|------|------|
+| `void SetMinimumLevel(LogLevel level)` | 设置最小日志级别 |
+| `void SetCategoryEnabled(LogCategory category, bool enabled)` | 开启/关闭指定分类 |
+
+## 宏定义
+
+### 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");
+```
+
+## 相关文档
+
+- [ILogSink](./debug-ilogsink.md) - 日志输出接口
+- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
+- [FileLogSink](./debug-filelogsink.md) - 文件输出
+- [LogLevel](./debug-loglevel.md) - 日志级别枚举
--- a/docs/api/debug/debug-loglevel.md
+++ b/docs/api/debug/debug-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)` | 将日志级别转换为字符串 |
+
+## 使用示例
+
+```cpp
+// 设置最小日志级别
+Logger::Get().SetMinimumLevel(LogLevel::Warning);
+// 只有 Warning、Error、Fatal 级别的日志会被输出
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器
--- a/docs/api/debug/debug-overview.md
+++ b/docs/api/debug/debug-overview.md
@@ -0,0 +1,83 @@
+# Debug 模块概览
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `module`
+
+**描述**: XCEngine 的调试和日志模块，提供日志记录和性能分析功能。
+
+## 概述
+
+Debug 模块提供了一套完整的调试工具，包括日志系统和性能分析器。
+
+## 模块内容
+
+### 日志系统
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Logger](./debug-logger.md) | `Logger.h` | 日志记录器 |
+| [ILogSink](./debug-ilogsink.md) | `ILogSink.h` | 日志输出接口 |
+| [ConsoleLogSink](./debug-consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
+| [FileLogSink](./debug-filelogsink.md) | `FileLogSink.h` | 文件输出 |
+| [LogLevel](./debug-loglevel.md) | `LogLevel.h` | 日志级别枚举 |
+| [LogCategory](./debug-logcategory.md) | `LogCategory.h` | 日志分类枚举 |
+| [LogEntry](./debug-logentry.md) | `LogEntry.h` | 日志条目结构 |
+
+### 性能分析
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Profiler](./debug-profiler.md) | `Profiler.h` | 性能分析器 |
+
+## 日志级别
+
+| 级别 | 描述 |
+|------|------|
+| `Verbose` | 详细调试信息 |
+| `Debug` | 调试信息 |
+| `Info` | 一般信息 |
+| `Warning` | 警告信息 |
+| `Error` | 错误信息 |
+| `Fatal` | 致命错误 |
+
+## 日志分类
+
+| 分类 | 描述 |
+|------|------|
+| `General` | 通用 |
+| `Rendering` | 渲染 |
+| `Physics` | 物理 |
+| `Audio` | 音频 |
+| `Scripting` | 脚本 |
+| `Network` | 网络 |
+| `Memory` | 内存 |
+| `Threading` | 线程 |
+| `FileSystem` | 文件系统 |
+| `Custom` | 自定义 |
+
+## 使用示例
+
+```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);
+
+// 记录日志
+XE_LOG(LogCategory::Rendering, LogLevel::Info, "Render started");
+
+// 使用宏记录日志
+if (condition) {
+    XE_LOG(LogCategory::General, LogLevel::Error, "Something went wrong");
+}
+```
+
+## 相关文档
+
+- [Profiler](./debug-profiler.md) - 性能分析器
--- a/docs/api/debug/debug-profiler.md
+++ b/docs/api/debug/debug-profiler.md
@@ -0,0 +1,117 @@
+# Profiler
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (singleton)
+
+**描述**: 性能分析器单例，用于测量代码块执行时间并支持 Chrome Tracing 格式导出。
+
+## 概述
+
+`Profiler` 是 XCEngine 的性能分析工具。它通过栈式记录和采样方式跟踪函数执行时间，支持导出为 Chrome Tracing 格式（可通过 Chrome 的 `chrome://tracing` 查看）。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static Profiler& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | 初始化性能分析器 |
+| `void Shutdown()` | 关闭性能分析器 |
+
+### 性能测量
+
+| 方法 | 描述 |
+|------|------|
+| `void BeginProfile(const char* name)` | 开始一个性能分析块 |
+| `void EndProfile()` | 结束当前性能分析块 |
+
+### 帧管理
+
+| 方法 | 描述 |
+|------|------|
+| `void BeginFrame()` | 开始一帧的分析 |
+| `void EndFrame()` | 结束一帧的分析 |
+
+### 事件标记
+
+| 方法 | 描述 |
+|------|------|
+| `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)` | 导出为 Chrome Tracing JSON 格式 |
+
+## 宏定义
+
+### 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__)
+```
+
+自动使用当前函数名进行分析。
+
+## 使用示例
+
+```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();
+
+// 导出 Chrome Tracing 格式
+Profiler::Get().ExportChromeTracing("profile.json");
+
+Profiler::Get().Shutdown();
+```
+
+## 相关文档
+
+- [Logger](./debug-logger.md) - 日志记录器