docs: rebuild Debug API content

docs/api/XCEngine/Debug/Debug.md

@@ -4,24 +4,47 @@
 
 **类型**: `module`
 
-**描述**: 日志、Profiler 与调试集成接口。
+**描述**: 提供日志分发、轻量级 CPU 埋点以及 RenderDoc 捕获集成。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Debug` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine::Debug` 是引擎运行时调试能力的入口模块。它把三个需求放在同一层中统一管理：
+
+- 运行日志：通过 `Logger` 将消息分发到控制台、文件或自定义 sink。
+- CPU 埋点：通过 `Profiler` 记录函数段或作用域的耗时。
+- GPU 抓帧：通过 `RenderDocCapture` 在图形测试和工具程序中触发 RenderDoc。
+
+当前版本的成熟度并不一致：
+
+- `Logger` 与日志 sink 已经可以直接用于编辑器、测试和后端调试。
+- `Profiler` 的接口已经成形，但导出、标记和事件功能目前仍是占位实现。
+- `RenderDocCapture` 是 Windows 平台上的轻量封装，依赖可用的 `renderdoc.dll`。
+
+## 设计要点
+
+- 统一入口比散落的 `printf` 或后端专用日志更利于跨模块排查问题。
+- sink 模式允许同时输出到多个目标，而不会把输出策略写死在业务代码里。
+- `Profiler` 和 `RenderDocCapture` 都采用单例，目的是让工具、测试和引擎运行时共享一套调试入口。
+- 该模块偏开发期工具能力，不追求零侵入；一些 API 会主动写日志、刷新文件或拉起窗口焦点。
 
 ## 头文件
 
-- [ConsoleLogSink](ConsoleLogSink/ConsoleLogSink.md) - `ConsoleLogSink.h`
-- [Debug](Debug/Debug.md) - `Debug.h`
-- [FileLogSink](FileLogSink/FileLogSink.md) - `FileLogSink.h`
-- [ILogSink](ILogSink/ILogSink.md) - `ILogSink.h`
-- [LogCategory](LogCategory/LogCategory.md) - `LogCategory.h`
-- [LogEntry](LogEntry/LogEntry.md) - `LogEntry.h`
-- [Logger](Logger/Logger.md) - `Logger.h`
-- [LogLevel](LogLevel/LogLevel.md) - `LogLevel.h`
-- [Profiler](Profiler/Profiler.md) - `Profiler.h`
-- [RenderDocCapture](RenderDocCapture/RenderDocCapture.md) - `RenderDocCapture.h`
+- [ConsoleLogSink](ConsoleLogSink/ConsoleLogSink.md) - `ConsoleLogSink.h`，面向 `stdout` 的日志输出 sink。
+- [Debug](Debug/Debug.md) - `Debug.h`，聚合调试模块所有 public header 的便利入口。
+- [FileLogSink](FileLogSink/FileLogSink.md) - `FileLogSink.h`，将日志追加写入文件。
+- [ILogSink](ILogSink/ILogSink.md) - `ILogSink.h`，日志输出目标接口。
+- [LogCategory](LogCategory/LogCategory.md) - `LogCategory.h`，日志功能分类枚举。
+- [LogEntry](LogEntry/LogEntry.md) - `LogEntry.h`，日志记录载体。
+- [Logger](Logger/Logger.md) - `Logger.h`，全局日志分发中心。
+- [LogLevel](LogLevel/LogLevel.md) - `LogLevel.h`，日志严重级别枚举。
+- [Profiler](Profiler/Profiler.md) - `Profiler.h`，轻量级 CPU 埋点入口。
+- [RenderDocCapture](RenderDocCapture/RenderDocCapture.md) - `RenderDocCapture.h`，RenderDoc 封装。
+
+## 相关指南
+
+- [Logging Architecture](../../_guides/Debug/Logging-Architecture.md) - 日志系统的角色划分、推荐接线方式和与 Unity 的概念对照。
+- [Profiler Workflow](../../_guides/Debug/Profiler-Workflow.md) - 当前埋点能力的适用边界、典型流程与限制。
+- [RenderDoc Capture Workflow](../../_guides/Debug/RenderDoc-Capture-Workflow.md) - 在图形测试中接入 RenderDoc 的推荐步骤。
 
 ## 相关文档