From 6bde199393c5a1e54f72905cf4c374d7baf1365a Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Sat, 28 Mar 2026 00:40:56 +0800
Subject: [PATCH] docs(api): deepen D3D12 query heap and shader docs

---
 .../RHI/D3D12/D3D12QueryHeap/Constructor.md   |  26 ++--
 .../D3D12/D3D12QueryHeap/D3D12QueryHeap.md    |  86 ++++++++++---
 .../RHI/D3D12/D3D12QueryHeap/Destructor.md    |  26 ++--
 .../RHI/D3D12/D3D12QueryHeap/GetCount.md      |  25 ++--
 .../D3D12/D3D12QueryHeap/GetNativeHandle.md   |  25 ++--
 .../RHI/D3D12/D3D12QueryHeap/GetQueryHeap.md  |  29 ++---
 .../RHI/D3D12/D3D12QueryHeap/GetType.md       |  25 ++--
 .../RHI/D3D12/D3D12QueryHeap/Initialize.md    |  51 +++++---
 .../RHI/D3D12/D3D12QueryHeap/Shutdown.md      |  26 ++--
 .../XCEngine/RHI/D3D12/D3D12Shader/Compile.md |  44 ++++---
 .../RHI/D3D12/D3D12Shader/CompileFromFile.md  |  49 +++++---
 .../RHI/D3D12/D3D12Shader/Constructor.md      |  27 ++--
 .../RHI/D3D12/D3D12Shader/D3D12Shader.md      | 116 ++++++++++++++----
 .../RHI/D3D12/D3D12Shader/Destructor.md       |  26 ++--
 .../RHI/D3D12/D3D12Shader/GetBytecode.md      |  25 ++--
 .../RHI/D3D12/D3D12Shader/GetBytecodeSize.md  |  25 ++--
 .../RHI/D3D12/D3D12Shader/GetD3D12Bytecode.md |  32 ++---
 .../RHI/D3D12/D3D12Shader/GetInputLayout.md   |  30 +++--
 .../RHI/D3D12/D3D12Shader/GetNativeHandle.md  |  25 ++--
 .../XCEngine/RHI/D3D12/D3D12Shader/GetType.md |  27 ++--
 .../RHI/D3D12/D3D12Shader/GetUniformInfo.md   |  29 ++---
 .../RHI/D3D12/D3D12Shader/GetUniformInfos.md  |  44 ++++---
 .../XCEngine/RHI/D3D12/D3D12Shader/IsValid.md |  28 ++---
 .../RHI/D3D12/D3D12Shader/Shutdown.md         |  36 +++---
 docs/api/_meta/rebuild-status.md              |   2 +-
 25 files changed, 464 insertions(+), 420 deletions(-)

diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Constructor.md
index 75be8c32..1b88ecc1 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Constructor.md
@@ -1,28 +1,20 @@
-# D3D12QueryHeap::D3D12QueryHeap()
-
-构造对象。
+# D3D12QueryHeap::D3D12QueryHeap
 
 ```cpp
 D3D12QueryHeap();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 query heap 包装对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-}
-```
+- `m_type` 初始化为 `QueryType::Timestamp`
+- `m_count` 初始化为 `0`
+- `m_queryHeap` 为空
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12QueryHeap](D3D12QueryHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/D3D12QueryHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/D3D12QueryHeap.md
index 426df0e8..3e88c52c 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/D3D12QueryHeap.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/D3D12QueryHeap.md
@@ -6,32 +6,78 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12QueryHeap.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12QueryHeap` public API。
+**描述**: D3D12 后端的 query heap 包装，负责创建并保存 `ID3D12QueryHeap`，供命令列表执行 `BeginQuery`、`EndQuery` 和 `ResolveQueryData`。
 
-## 概述
+## 概览
 
-`D3D12QueryHeap.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12QueryHeap` 是当前后端里比较薄的一层资源包装。
 
-## 声明概览
+它主要做三件事：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12QueryHeap` | `class` | 头文件中的公开声明。 |
+- 根据 [QueryType](../../RHITypes/RHITypes.md) 创建一个 `ID3D12QueryHeap`
+- 记录 query 类型和数量
+- 把原生 query heap 暴露给 [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 这类低层调用方
 
-## 公共方法
+它当前不负责这些事情：
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12QueryHeap()](Constructor.md) | 构造对象。 |
-| [~D3D12QueryHeap()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetQueryHeap](GetQueryHeap.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetType](GetType.md) | 获取相关状态或对象。 |
-| [GetCount](GetCount.md) | 获取相关状态或对象。 |
+- 不分配结果缓冲区
+- 不封装 `ResolveQueryData(...)` 的结果读取
+- 不维护 query 槽位分配策略
+- 不做 query 生命周期调度
+
+## 设计定位
+
+这类对象在商业级引擎里通常只是 query 系统的一小部分。完整方案往往还会包含：
+
+- 结果缓冲与 readback 管理
+- 时间戳校准与频率换算
+- query 池复用
+- frame graph / profiler 集成
+
+当前 XCEngine 处于更早期、更基础的阶段，因此 `D3D12QueryHeap` 只先承担“创建原生 heap 并把它暴露出来”的职责。
+
+## 生命周期
+
+- 构造后默认类型为 `QueryType::Timestamp`，数量为 `0`
+- [Initialize](Initialize.md) 成功后持有一个 `ID3D12QueryHeap`
+- [Shutdown](Shutdown.md) 释放 COM 对象并把类型、数量复位
+- 析构时自动调用 [Shutdown](Shutdown.md)
+
+## 当前实现的真实行为
+
+- `Initialize()` 根据 `QueryType` 选择 `D3D12_QUERY_HEAP_DESC::Type`
+- `desc.NodeMask` 当前固定写成 `0`
+- [Initialize](Initialize.md) 不读取 [QueryHeapDesc](../../RHITypes/RHITypes.md) 里的 `nodeMask`
+- 不对 `device == nullptr` 或 `count == 0` 做前置保护，完全依赖 `CreateQueryHeap(...)` 的返回结果
+- [GetNativeHandle](GetNativeHandle.md) 和 [GetQueryHeap](GetQueryHeap.md) 返回的是同一个原生指针
+
+## 使用方式
+
+当前典型调用链大致如下：
+
+1. [D3D12Device](../D3D12Device/D3D12Device.md) 通过 `CreateQueryHeap(desc)` 创建对象
+2. 调用方取出原生 `ID3D12QueryHeap*`
+3. [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md) 调用 `BeginQuery(...)`、`EndQuery(...)`、`ResolveQueryData(...)`
+4. 结果写入单独的 buffer，再由上层自己处理读回
+
+## 当前限制
+
+- 只封装 heap，不封装 query 结果读取链路
+- 不支持 node mask 透传
+- 没有 query index 分配器
+- 没有线程安全保证
+- 当前工程里几乎没有直接针对它的单元测试覆盖
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [GetQueryHeap](GetQueryHeap.md)
+- [GetType](GetType.md)
+- [GetCount](GetCount.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
+- [D3D12Device](../D3D12Device/D3D12Device.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Destructor.md
index 36e812e8..56d7e434 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Destructor.md
@@ -1,29 +1,19 @@
-# D3D12QueryHeap::~D3D12QueryHeap()
-
-销毁对象并释放相关资源。
+# D3D12QueryHeap::~D3D12QueryHeap
 
 ```cpp
 ~D3D12QueryHeap();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 query heap 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部直接调用 [Shutdown](Shutdown.md)
+- 会释放持有的 `ID3D12QueryHeap`
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [D3D12QueryHeap](D3D12QueryHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetCount.md
index 459fa03d..d3b1101d 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetCount.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetCount.md
@@ -1,30 +1,19 @@
 # D3D12QueryHeap::GetCount
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetCount() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 query heap 可容纳的 query 槽位数量。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::GetCount(...)。
-    (void)object;
-}
-```
+- 成功初始化后返回最后一次 [Initialize](Initialize.md) 传入的 `count`
+- [Shutdown](Shutdown.md) 之后返回 `0`
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetNativeHandle.md
index 68bd7f16..9831dd24 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetNativeHandle.md
@@ -1,30 +1,19 @@
 # D3D12QueryHeap::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 query heap 的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_queryHeap.Get()`
+- 与 [GetQueryHeap](GetQueryHeap.md) 返回的是同一个底层对象，只是类型被擦成了 `void*`
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetQueryHeap](GetQueryHeap.md)
+- [D3D12QueryHeap](D3D12QueryHeap.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetQueryHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetQueryHeap.md
index 82ad1fe8..86b394cf 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetQueryHeap.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetQueryHeap.md
@@ -1,30 +1,27 @@
 # D3D12QueryHeap::GetQueryHeap
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12QueryHeap* GetQueryHeap() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回原生 `ID3D12QueryHeap*`。
 
-**返回：** `ID3D12QueryHeap*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_queryHeap.Get()`
+- 不做空指针保护
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::GetQueryHeap(...)。
-    (void)object;
-}
-```
+这是给低层 D3D12 调用方用的接口，例如命令列表需要它来执行：
+
+- `BeginQuery(...)`
+- `EndQuery(...)`
+- `ResolveQueryData(...)`
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [D3D12CommandList](../D3D12CommandList/D3D12CommandList.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetType.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetType.md
index 6d3dccf4..ddca3e36 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/GetType.md
@@ -1,30 +1,19 @@
 # D3D12QueryHeap::GetType
 
-获取相关状态或对象。
-
 ```cpp
 QueryType GetType() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 query heap 记录的 query 类型。
 
-**返回：** `QueryType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
-
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::GetType(...)。
-    (void)object;
-}
-```
+- 成功初始化后返回最后一次 [Initialize](Initialize.md) 传入的类型
+- [Shutdown](Shutdown.md) 之后恢复为 `QueryType::Timestamp`
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [GetCount](GetCount.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Initialize.md
index 10b8256a..14008fbc 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Initialize.md
@@ -1,33 +1,46 @@
 # D3D12QueryHeap::Initialize
 
-初始化内部状态。
-
 ```cpp
 bool Initialize(ID3D12Device* device, QueryType type, uint32_t count);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `type` - 参数语义详见头文件声明。
-- `count` - 参数语义详见头文件声明。
+创建原生 `ID3D12QueryHeap`。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 构造一个 `D3D12_QUERY_HEAP_DESC`
+- `desc.Count = count`
+- `desc.NodeMask = 0`
+- 根据 `type` 选择：
+  - `QueryType::Timestamp` -> `D3D12_QUERY_HEAP_TYPE_TIMESTAMP`
+  - `QueryType::Occlusion` -> `D3D12_QUERY_HEAP_TYPE_OCCLUSION`
+  - `QueryType::PipelineStatistics` -> `D3D12_QUERY_HEAP_TYPE_PIPELINE_STATISTICS`
+- 调用 `device->CreateQueryHeap(...)`
+- 成功后缓存 `m_type` 和 `m_count`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
+## 重要说明
 
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::Initialize(...)。
-    (void)object;
-}
-```
+这里虽然在设备层有 [QueryHeapDesc](../../RHITypes/RHITypes.md) 抽象，但当前真正落到实现时，只使用了：
+
+- `queryType`
+- `count`
+
+`nodeMask` 当前没有被透传。
+
+## 当前限制
+
+- 不检查 `device` 是否为空
+- 不检查 `count` 是否为 `0`
+- 不支持多节点配置
+
+## 使用建议
+
+如果你正在设计 profiler 或 occlusion 系统，应该把它理解成“原生 query heap 句柄创建器”，而不是完整的 query 子系统入口。
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [GetQueryHeap](GetQueryHeap.md)
+- [GetType](GetType.md)
+- [GetCount](GetCount.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Shutdown.md
index c6c6d7b7..07f0e365 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12QueryHeap/Shutdown.md
@@ -1,30 +1,24 @@
 # D3D12QueryHeap::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12QueryHeap.h`，当前页面用于固定 `D3D12QueryHeap` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放原生 query heap 并复位本地状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `m_queryHeap.Reset()`
+- `m_type = QueryType::Timestamp`
+- `m_count = 0`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12QueryHeap.h>
+## 设计说明
 
-void Example() {
-    XCEngine::RHI::D3D12QueryHeap object;
-    // 根据上下文补齐参数后调用 D3D12QueryHeap::Shutdown(...)。
-    (void)object;
-}
-```
+当前类只持有一个 COM 对象，因此清理逻辑比较直接。它不会处理任何与 query 结果 buffer 相关的清理，因为那部分不属于这个类。
 
 ## 相关文档
 
-- [返回类总览](D3D12QueryHeap.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Compile.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Compile.md
index 3ba2a3ac..69cb8171 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Compile.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Compile.md
@@ -1,34 +1,38 @@
 # D3D12Shader::Compile
 
-公开方法，详见头文件声明。
-
 ```cpp
 bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `sourceData` - 参数语义详见头文件声明。
-- `sourceSize` - 参数语义详见头文件声明。
-- `entryPoint` - 参数语义详见头文件声明。
-- `target` - 参数语义详见头文件声明。
+从内存中的 HLSL 源码编译 shader。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 调用 `D3DCompile(...)`
+- 编译标志同样固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
+- 不提供文件名、宏或 include handler
+- 失败时如果 `m_error` 非空，只调用 `OutputDebugStringA(errorMsg)`，不会像 [CompileFromFile](CompileFromFile.md) 一样写到 `stderr`
+- 成功后按 `target` 推断类型
+- 把 `m_uniformsCached` 设为 `false`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::Compile(...)。
-    (void)object;
-}
-```
+这个重载主要服务于：
+
+- [D3D12Device](../D3D12Device/D3D12Device.md) 的内存源码编译路径
+- 单元测试里的内嵌 HLSL 字符串
+- 运行时生成 shader 文本的实验性场景
+
+## 当前限制
+
+- 仍然是 FXC 路径
+- 没有源码来源名，编译报错定位体验弱于文件编译
+- 类型推断依赖 `target` 字符串，而不是字节码内容
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [CompileFromFile](CompileFromFile.md)
+- [GetBytecode](GetBytecode.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/CompileFromFile.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/CompileFromFile.md
index 7a665998..6352fb82 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/CompileFromFile.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/CompileFromFile.md
@@ -1,33 +1,44 @@
 # D3D12Shader::CompileFromFile
 
-公开方法，详见头文件声明。
-
 ```cpp
 bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `filePath` - 参数语义详见头文件声明。
-- `entryPoint` - 参数语义详见头文件声明。
-- `target` - 参数语义详见头文件声明。
+从 HLSL 文件编译 shader。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 调用 `D3DCompileFromFile(...)`
+- 编译标志固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
+- 不传入自定义宏、include handler 或效果框架参数
+- 如果失败且 `m_error` 非空：
+  - 调用 `OutputDebugStringA(errorMsg)`
+  - 调用 `fprintf(stderr, "[SHADER ERROR] %s\n", errorMsg)`
+- 如果成功，则根据 `target` 推断 shader 类型
+- 最后把 `m_uniformsCached` 设为 `false`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 类型推断规则
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::CompileFromFile(...)。
-    (void)object;
-}
-```
+- `target` 包含 `vs_` -> `ShaderType::Vertex`
+- `target` 包含 `ps_` -> `ShaderType::Fragment`
+- `target` 包含 `gs_` -> `ShaderType::Geometry`
+- `target` 包含 `cs_` -> `ShaderType::Compute`
+
+## 当前限制
+
+- 不支持 DXC
+- 不支持 include 搜索策略定制
+- 不支持宏变体
+- 如果 `target` 不匹配已知前缀，类型不会进入“未知”，而是保留旧值
+
+## 使用建议
+
+这是当前 D3D12 后端最常见的编译入口。测试和集成样例大量通过它把 `.hlsl` 文件转成可直接用于 PSO 的字节码。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [Compile](Compile.md)
+- [GetD3D12Bytecode](GetD3D12Bytecode.md)
+- [GetType](GetType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Constructor.md
index 96208723..7a8ce755 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Constructor.md
@@ -1,28 +1,25 @@
-# D3D12Shader::D3D12Shader()
-
-构造对象。
+# D3D12Shader::D3D12Shader
 
 ```cpp
 D3D12Shader();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 shader 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `m_type` 初始化为 `ShaderType::Vertex`
+- `m_uniformsCached` 初始化为 `false`
+- 字节码和错误 blob 为空
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-}
-```
+默认类型是 `Vertex` 只是一个初始值，不代表对象已经包含可用的顶点着色器字节码。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [CompileFromFile](CompileFromFile.md)
+- [Compile](Compile.md)
+- [D3D12Shader](D3D12Shader.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/D3D12Shader.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/D3D12Shader.md
index 2911c6fe..878da887 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/D3D12Shader.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/D3D12Shader.md
@@ -6,38 +6,102 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12Shader.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Shader` public API。
+**描述**: D3D12 后端的 HLSL 编译结果包装，负责保存 FXC 生成的字节码，并提供轻量级的 shader 反射信息访问。
 
-## 概述
+## 概览
 
-`D3D12Shader.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12Shader` 是当前 D3D12 后端里最核心的“编译期资源”之一。
 
-## 声明概览
+它承担的职责包括：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12Shader` | `class` | 继承自 `RHIShader` 的公开声明。 |
+- 通过 `D3DCompileFromFile(...)` 或 `D3DCompile(...)` 编译 HLSL
+- 保存编译得到的 `ID3DBlob`
+- 根据 profile 推断 shader 类型
+- 在需要时用 `D3DReflect(...)` 延迟反射出一组简化后的 `UniformInfo`
 
-## 公共方法
+它当前不承担这些职责：
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12Shader()](Constructor.md) | 构造对象。 |
-| [~D3D12Shader()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [CompileFromFile](CompileFromFile.md) | 公开方法，详见头文件声明。 |
-| [Compile](Compile.md) | 公开方法，详见头文件声明。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetD3D12Bytecode](GetD3D12Bytecode.md) | 获取相关状态或对象。 |
-| [GetBytecode](GetBytecode.md) | 获取相关状态或对象。 |
-| [GetBytecodeSize](GetBytecodeSize.md) | 获取相关状态或对象。 |
-| [GetType](GetType.md) | 获取相关状态或对象。 |
-| [GetInputLayout](GetInputLayout.md) | 获取相关状态或对象。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [IsValid](IsValid.md) | 查询当前状态。 |
-| [GetUniformInfos](GetUniformInfos.md) | 获取相关状态或对象。 |
-| [GetUniformInfo](GetUniformInfo.md) | 获取相关状态或对象。 |
+- 不使用 DXC / DXIL 编译链
+- 不管理 root signature
+- 不自动生成输入布局
+- 不暴露完整反射结果对象
+- 不缓存编译宏、include handler 或编译配置对象
+
+## 设计定位
+
+从商业级引擎角度看，shader 系统通常会拆成三层：
+
+- 源文件与变体管理
+- 编译产物缓存
+- 运行时反射和资源绑定元数据
+
+当前 `D3D12Shader` 主要覆盖了中间这一层，并且只提供了一个相对轻量的反射侧出口。它的目标是先让测试、示例和 PSO 创建链路跑通，而不是一步到位做成完整的 shader pipeline。
+
+## 生命周期
+
+- 构造后默认 `m_type = ShaderType::Vertex`
+- [CompileFromFile](CompileFromFile.md) 或 [Compile](Compile.md) 成功后持有编译字节码
+- [GetUniformInfos](GetUniformInfos.md) / [GetUniformInfo](GetUniformInfo.md) 会在首次访问时触发延迟反射
+- [Shutdown](Shutdown.md) 释放字节码和错误 blob，并清空缓存的 uniform 信息
+- 析构时自动调用 [Shutdown](Shutdown.md)
+
+## 当前实现的真实行为
+
+- 编译后端使用的是 `D3DCompile*`，也就是 FXC 路径，而不是 DXC
+- 编译标志固定为 `D3DCOMPILE_DEBUG | D3DCOMPILE_SKIP_OPTIMIZATION`
+- 类型判断完全依赖 `target` 字符串里是否包含 `vs_`、`ps_`、`gs_`、`cs_`
+- 如果 `target` 不匹配上述前缀，`m_type` 会保持之前的值
+- [GetNativeHandle](GetNativeHandle.md) 返回的是 `ID3DBlob*`
+- [GetD3D12Bytecode](GetD3D12Bytecode.md) 返回的 `D3D12_SHADER_BYTECODE` 内部指针直接指向 `m_bytecode` 的内存
+- [GetInputLayout](GetInputLayout.md) 当前基本只是返回一个内部缓存字段，但这份字段没有在编译过程中自动填充
+- `UniformInfo` 反射是延迟执行的，但实现只提取了简化信息，不是完整反射模型
+
+## 反射部分需要特别注意
+
+当前 `CacheUniformInfos()` 只是一个“够用就好”的实现，存在几个重要限制：
+
+- 只遍历 `BoundResources`
+- `info.arraySize` 当前取自 `bindDesc.NumSamples`，而不是资源绑定数组长度
+- 常量缓冲大小通过 `GetConstantBufferByIndex(bindDesc.BindPoint)` 查询，这隐含了“bind point 恰好等于 reflection constant-buffer index”的假设
+- `info.offset` 没有被填充，保持默认值
+
+这意味着它更适合作为调试和轻量查询接口，而不是高可靠的绑定布局真相来源。
+
+## 为什么这样设计
+
+这套设计明显偏向“快速建立可工作的 D3D12 编译链路”：
+
+- 集成测试和样例可以直接从 HLSL 文件生成字节码
+- pipeline state 能直接拿到 `D3D12_SHADER_BYTECODE`
+- 调用方还能通过简化反射读到资源绑定名称和槽位
+
+代价是：
+
+- 编译链现代化程度不高
+- 反射信息不够完整
+- 文档必须把“哪些数据是可靠的、哪些只是近似或当前实现细节”写清楚
+
+## 当前限制
+
+- 没有 DXC 支持
+- 没有 include handler、自定义宏或多变体编译支持
+- 不自动生成输入布局
+- `GetType()` 在 `Shutdown()` 后不会恢复到“未知状态”，而是保留之前的类型值
+- `UniformInfo` 中的数组大小和部分常量缓冲尺寸信息在复杂 shader 下可能不准确
+- 当前工程里没有直接针对 D3D12 反射细节的专门单元测试
+
+## 关键方法
+
+- [CompileFromFile](CompileFromFile.md)
+- [Compile](Compile.md)
+- [GetD3D12Bytecode](GetD3D12Bytecode.md)
+- [GetUniformInfos](GetUniformInfos.md)
+- [GetUniformInfo](GetUniformInfo.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12Device](../D3D12Device/D3D12Device.md)
+- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
+- [RHIShader](../../RHIShader/RHIShader.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Destructor.md
index 5a7e091d..326587c8 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Destructor.md
@@ -1,29 +1,19 @@
-# D3D12Shader::~D3D12Shader()
-
-销毁对象并释放相关资源。
+# D3D12Shader::~D3D12Shader
 
 ```cpp
 ~D3D12Shader() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁 shader 对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部直接调用 [Shutdown](Shutdown.md)
+- 会释放字节码 blob、错误 blob 和缓存的反射结果
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [D3D12Shader](D3D12Shader.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecode.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecode.md
index 985e5cbd..f3839714 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecode.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecode.md
@@ -1,30 +1,23 @@
 # D3D12Shader::GetBytecode
 
-获取相关状态或对象。
-
 ```cpp
 const void* GetBytecode() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回原始编译字节码缓冲的起始地址。
 
-**返回：** `const void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_bytecode` 有效，返回 `m_bytecode->GetBufferPointer()`
+- 否则返回 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetBytecode(...)。
-    (void)object;
-}
-```
+如果你要构建 D3D12 PSO，优先使用 [GetD3D12Bytecode](GetD3D12Bytecode.md)。这个接口更适合调试、日志和外部序列化类场景。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetBytecodeSize](GetBytecodeSize.md)
+- [GetD3D12Bytecode](GetD3D12Bytecode.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecodeSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecodeSize.md
index f658e516..31502971 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecodeSize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetBytecodeSize.md
@@ -1,30 +1,23 @@
 # D3D12Shader::GetBytecodeSize
 
-获取相关状态或对象。
-
 ```cpp
 size_t GetBytecodeSize() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前编译字节码的大小。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_bytecode` 有效，返回 `m_bytecode->GetBufferSize()`
+- 否则返回 `0`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetBytecodeSize(...)。
-    (void)object;
-}
-```
+集成测试和调试输出里常用它来确认 shader 是否成功编译并生成了非零字节码。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetBytecode](GetBytecode.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetD3D12Bytecode.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetD3D12Bytecode.md
index 9eb3d6d5..f313577a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetD3D12Bytecode.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetD3D12Bytecode.md
@@ -1,30 +1,30 @@
 # D3D12Shader::GetD3D12Bytecode
 
-获取相关状态或对象。
-
 ```cpp
 const D3D12_SHADER_BYTECODE GetD3D12Bytecode() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回可以直接提交给 D3D12 PSO 创建接口的 `D3D12_SHADER_BYTECODE` 结构。
 
-**返回：** `const D3D12_SHADER_BYTECODE` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 如果 `m_bytecode` 有效：
+  - `pShaderBytecode = m_bytecode->GetBufferPointer()`
+  - `BytecodeLength = m_bytecode->GetBufferSize()`
+- 如果无效，返回零初始化结构
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 使用场景
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetD3D12Bytecode(...)。
-    (void)object;
-}
-```
+这是 `D3D12PipelineState` 和 D3D12 集成样例最重要的接口之一，因为 `CreateGraphicsPipelineState(...)` / `CreateComputePipelineState(...)` 直接需要它。
+
+## 注意事项
+
+返回的是一个按值复制的结构体，但里面的指针仍然指向当前对象持有的 blob 内存。调用方必须保证 shader 对象在 PSO 使用该字节码期间仍然有效。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetBytecode](GetBytecode.md)
+- [GetBytecodeSize](GetBytecodeSize.md)
+- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetInputLayout.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetInputLayout.md
index ee1723dc..cd3de3b7 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetInputLayout.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetInputLayout.md
@@ -1,30 +1,28 @@
 # D3D12Shader::GetInputLayout
 
-获取相关状态或对象。
-
 ```cpp
 const InputLayoutDesc& GetInputLayout() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 shader 对象内部保存的输入布局描述。
 
-**返回：** `const InputLayoutDesc&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_inputLayout`
+- 当前编译路径不会自动填充它
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 正确认识
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetInputLayout(...)。
-    (void)object;
-}
-```
+这意味着对当前 D3D12 后端来说，[GetInputLayout](GetInputLayout.md) 不是一个可靠的“从 shader 自动反射出顶点输入布局”的接口。
+
+实际图形 PSO 的输入布局更多来自：
+
+- [GraphicsPipelineDesc](../../RHITypes/RHITypes.md) 里的显式 `inputLayout`
+- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md) 的配置
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [D3D12PipelineState](../D3D12PipelineState/D3D12PipelineState.md)
+- [D3D12Shader](D3D12Shader.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetNativeHandle.md
index f9e99017..03cda486 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetNativeHandle.md
@@ -1,30 +1,23 @@
 # D3D12Shader::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回 shader 的原生句柄表示。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 返回 `m_bytecode.Get()`
+- 也就是 `ID3DBlob*`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetNativeHandle(...)。
-    (void)object;
-}
-```
+这不是某种“可直接绑定的 D3D12 shader 对象句柄”。D3D12 图形与计算着色器真正进入管线的方式，仍然是通过字节码构造 PSO。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetD3D12Bytecode](GetD3D12Bytecode.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetType.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetType.md
index 7bc6614c..d1312135 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetType.md
@@ -1,30 +1,25 @@
 # D3D12Shader::GetType
 
-获取相关状态或对象。
-
 ```cpp
 ShaderType GetType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前对象记录的 shader 类型。
 
-**返回：** `ShaderType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_type`
+- 它由 [CompileFromFile](CompileFromFile.md) / [Compile](Compile.md) 根据 `target` 字符串更新
+- [Shutdown](Shutdown.md) 不会重置它
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetType(...)。
-    (void)object;
-}
-```
+这个返回值反映的是“最近一次成功匹配到的 profile 前缀”，不是对字节码内容做实时解析得到的结论。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [CompileFromFile](CompileFromFile.md)
+- [Compile](Compile.md)
+- [IsValid](IsValid.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfo.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfo.md
index f034b06a..c3165ccb 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfo.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfo.md
@@ -1,31 +1,26 @@
 # D3D12Shader::GetUniformInfo
 
-获取相关状态或对象。
-
 ```cpp
 const UniformInfo* GetUniformInfo(const char* name) const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+按名称查找一条简化的资源绑定信息。
 
-**返回：** `const UniformInfo*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 会先确保 [GetUniformInfos](GetUniformInfos.md) 的缓存已经建立
+- 对 `m_uniformInfos` 做线性遍历
+- 找到同名项就返回其地址
+- 否则返回 `nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 注意事项
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetUniformInfo(...)。
-    (void)object;
-}
-```
+- 这是线性查找，不是哈希表查找
+- 返回的是内部缓存元素指针，只有在对象仍然有效且缓存未被清空时才可靠
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetUniformInfos](GetUniformInfos.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfos.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfos.md
index 24c88603..ad540717 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfos.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/GetUniformInfos.md
@@ -1,30 +1,42 @@
 # D3D12Shader::GetUniformInfos
 
-获取相关状态或对象。
-
 ```cpp
 const std::vector<UniformInfo>& GetUniformInfos() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回当前 shader 的简化资源绑定信息列表。
 
-**返回：** `const std::vector<UniformInfo>&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 首次调用时会触发内部 `CacheUniformInfos()`
+- `CacheUniformInfos()` 使用 `D3DReflect(...)` 获取 shader reflection
+- 遍历 `shaderDesc.BoundResources`
+- 为每个绑定资源生成一个 `UniformInfo`
+- 后续调用直接返回缓存结果
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 当前反射内容
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::GetUniformInfos(...)。
-    (void)object;
-}
-```
+每条 `UniformInfo` 至少会尝试填这些字段：
+
+- `name`
+- `bindPoint`
+- `type`
+- `size`
+- `arraySize`
+
+但需要注意：
+
+- `arraySize` 当前来自 `bindDesc.NumSamples`
+- `offset` 没有被填充
+- 常量缓冲 `size` 的查询实现比较脆弱
+
+## 使用建议
+
+把它当成“当前 shader 里有哪些绑定资源的大概清单”是合理的；把它当成完整、严格、可直接驱动绑定系统的元数据来源则不够安全。
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetUniformInfo](GetUniformInfo.md)
+- [D3D12Shader](D3D12Shader.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/IsValid.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/IsValid.md
index 83024481..86b63cf6 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/IsValid.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/IsValid.md
@@ -1,30 +1,26 @@
 # D3D12Shader::IsValid
 
-查询当前状态。
-
 ```cpp
 bool IsValid() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+判断当前 shader 是否持有有效字节码。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 判断条件只有一个：`m_bytecode != nullptr`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 这意味着什么
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::IsValid(...)。
-    (void)object;
-}
-```
+只要 blob 存在，它就会返回 `true`。这个接口不检查：
+
+- shader 类型是否符合当前用途
+- 反射信息是否成功缓存
+- 输入布局是否存在
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [GetNativeHandle](GetNativeHandle.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Shutdown.md
index 9b5a2730..b0d6f6a3 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Shader/Shutdown.md
@@ -1,30 +1,34 @@
 # D3D12Shader::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Shader.h`，当前页面用于固定 `D3D12Shader` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放编译结果和反射缓存。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- `m_bytecode.Reset()`
+- `m_error.Reset()`
+- `m_uniformInfos.clear()`
+- `m_uniformsCached = false`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Shader.h>
+## 重要说明
 
-void Example() {
-    XCEngine::RHI::D3D12Shader object;
-    // 根据上下文补齐参数后调用 D3D12Shader::Shutdown(...)。
-    (void)object;
-}
-```
+当前实现不会重置：
+
+- `m_type`
+- `m_inputLayout`
+
+因此在 [Shutdown](Shutdown.md) 之后：
+
+- [IsValid](IsValid.md) 会变成 `false`
+- 但 [GetType](GetType.md) 仍然可能返回上一次编译留下的 shader 类型
 
 ## 相关文档
 
-- [返回类总览](D3D12Shader.md)
-- [返回模块目录](../D3D12.md)
+- [IsValid](IsValid.md)
+- [GetType](GetType.md)
+- [Destructor](Destructor.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 21136e59..5bf00993 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-28 00:24:57`
+**生成时间**: `2026-03-28 00:40:20`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`