docs: rebuild Debug API content

docs/api/XCEngine/Debug/Profiler/Profiler.md

@@ -6,34 +6,60 @@
 
 **头文件**: `XCEngine/Debug/Profiler.h`
 
-**描述**: 定义 `XCEngine/Debug` 子目录中的 `Profiler` public API。
+**描述**: 提供轻量级 CPU 埋点入口，用于记录成对的 profile 区段。
 
 ## 概述
 
-`Profiler.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`Profiler` 的 API 形状明显面向“开发期埋点”和“后续时间线导出”场景，但当前实现仍处于非常早期的阶段。它已经能够记录一组成对的 `BeginProfile` / `EndProfile` 调用时长，却还没有提供读取样本、可视化时间线或导出 Chrome Trace 的完整工作流。
 
-## 声明概览
+可以把它理解为：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `Profiler` | `class` | 头文件中的公开声明。 |
+- 设计方向上类似轻量版的引擎内 CPU 埋点器；
+- 但当前能力远不等同于 Unity Profiler 这类成熟的分析器。
 
-## 公共方法
+## 当前实现能力
 
-| 方法 | 描述 |
+- [BeginProfile](BeginProfile.md) / [EndProfile](EndProfile.md) 会把区段时长记录到内部样本数组。
+- [BeginFrame](BeginFrame.md) 只记录一帧开始时间。
+- [EndFrame](EndFrame.md) 当前会直接清空样本数组。
+- [MarkEvent](MarkEvent.md)、[SetMarker](SetMarker.md) 和 [ExportChromeTracing](ExportChromeTracing.md) 目前都是空实现。
+
+## 生命周期
+
+- [Get](Get.md) 返回进程级单例。
+- [Initialize](Initialize.md) 只设置初始化标志。
+- [Shutdown](Shutdown.md) 清空样本与栈状态。
+
+## 线程语义
+
+- 当前实现没有任何锁，也不是按线程分桶存储。
+- `m_profileStack` 是单个全局栈，因此 `BeginProfile` / `EndProfile` 只应在同一线程、同一调用栈上成对使用。
+- 如果多个线程并发使用同一个 `Profiler`，样本次序和栈配对都可能被破坏。
+
+## 宏
+
+- `XE_PROFILE_BEGIN(name)` 开始一个具名区段。
+- `XE_PROFILE_END()` 结束最近一次开始的区段。
+- `XE_PROFILE_FUNCTION()` 使用当前函数名作为区段名。
+
+这些宏是最适合当前实现的接入方式，因为它们几乎不引入额外样板代码。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [Get](Get.md) | 获取相关状态或对象。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [BeginProfile](BeginProfile.md) | 公开方法，详见头文件声明。 |
-| [EndProfile](EndProfile.md) | 公开方法，详见头文件声明。 |
-| [BeginFrame](BeginFrame.md) | 公开方法，详见头文件声明。 |
-| [EndFrame](EndFrame.md) | 公开方法，详见头文件声明。 |
-| [MarkEvent](MarkEvent.md) | 公开方法，详见头文件声明。 |
-| [SetMarker](SetMarker.md) | 设置相关状态或配置。 |
-| [ExportChromeTracing](ExportChromeTracing.md) | 公开方法，详见头文件声明。 |
+| [Get](Get.md) | 获取全局 `Profiler` 实例。 |
+| [Initialize](Initialize.md) | 初始化 profiler 状态。 |
+| [Shutdown](Shutdown.md) | 清空内部记录。 |
+| [BeginProfile](BeginProfile.md) | 开始一个 profile 区段。 |
+| [EndProfile](EndProfile.md) | 结束最近一个区段并记录时长。 |
+| [BeginFrame](BeginFrame.md) | 标记帧开始。 |
+| [EndFrame](EndFrame.md) | 结束当前帧并清空当前样本。 |
+| [MarkEvent](MarkEvent.md) | 预留的事件标记接口。 |
+| [SetMarker](SetMarker.md) | 预留的 marker 接口。 |
+| [ExportChromeTracing](ExportChromeTracing.md) | 预留的导出接口。 |
 
 ## 相关文档
 
-- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Debug.md)
+- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)