refactor: advance runtime and pipeline architecture split

docs/plan/runtime-rendering-framedata-structure-subplan.md

@@ -0,0 +1,107 @@
+# XCEngine 子计划：Runtime Rendering FrameData 第一刀
+
+## 1. 为什么现在切这个
+
+截至 `2026-05-01`：
+
+- `Runtime/Asset`
+- `Runtime/Resources`
+- `Runtime/Scene`
+- `Runtime/Rendering/Caches`
+- `Runtime/Rendering/Shadow`
+- `Runtime/Rendering/Materials`
+- `Runtime/Rendering/Picking`
+
+`Picking` 已完成后，下一步优先选择 `Runtime/Rendering/FrameData`，原因是：
+
+- `FrameData` 主要由稳定数据头和少量 header-only 工具组成
+- 依赖虽然广，但大多是只读消费，不牵涉主流程重构
+- 可以继续按低风险方式把 rendering 运行时数据契约落到真实树
+- 能为后续 `Extraction` 收口提前建立稳定内部路径
+
+## 2. 本子计划切什么
+
+这一轮聚焦：
+
+- `RenderCameraData.h`
+- `RenderEnvironmentData.h`
+- `CullingResults.h`
+- `VisibleRenderItem.h`
+- `VisibleGaussianSplatItem.h`
+- `VisibleVolumeItem.h`
+- `RenderSceneData.h`
+- `RendererListUtils.h`
+
+如果这些文件继续保持 header-only，就只迁真实头文件位置并收口 include。
+
+这一轮明确不碰：
+
+- `RenderSceneExtractor.cpp`
+- `RenderSceneUtility.cpp`
+- `Builtin*Pass` 行为逻辑
+- `RenderGraph`
+- `RenderPipeline`
+
+除非只是机械性的 include / CMake 路径调整。
+
+## 3. 目标
+
+这一刀至少达到：
+
+- frame data 真实定义迁到 `engine/Runtime/Rendering/FrameData/*`
+- 旧 `engine/include/XCEngine/Rendering/FrameData/*` public 头收窄成兼容 forwarding 层
+- 内部实现侧 include 改用稳定内部路径
+- `XCEditor` 编译和 12 秒 editor smoke 继续稳定
+
+## 4. 建议切法
+
+### Step 1：先切基础数据头
+
+优先处理：
+
+- `RenderCameraData.h`
+- `RenderEnvironmentData.h`
+- `CullingResults.h`
+
+原因：
+
+- 是更上层 `RenderSceneData` 的直接基础
+- 结构独立、风险最低
+
+### Step 2：再切 visible item 与 scene data
+
+随后处理：
+
+- `VisibleRenderItem.h`
+- `VisibleGaussianSplatItem.h`
+- `VisibleVolumeItem.h`
+- `RenderSceneData.h`
+
+原因：
+
+- 构成 render scene 抽取结果的主体数据契约
+- 对后续 `Extraction` 收口是前置条件
+
+### Step 3：最后切 `RendererListUtils`
+
+统一收口：
+
+- `RendererListUtils.h`
+- `engine/CMakeLists.txt`
+- 旧 public 头 forwarding
+- 内部真实路径 include
+- 阶段验证
+
+## 5. 验证要求
+
+本阶段完成后继续保持：
+
+1. 编译 `XCEditor`
+2. 执行 12 秒 `editor_ui_smoke_runner`
+
+## 6. 当前状态
+
+截至 `2026-05-01`：
+
+- `Runtime/Rendering/Picking` 第一刀已完成
+- 下一刀从 `RenderCameraData` 开始

docs/plan/target-architecture.md

@@ -37,8 +37,8 @@
 代码库按执行阶段拆分为：
 
 - `engine/foundation`：基础设施层
-- `engine/shared`：跨阶段稳定契约层
-- `engine/runtime`：运行时系统
+- `engine/Shared`：跨阶段稳定契约层
+- `engine/Runtime`：运行时系统
 - `pipeline`：导入、构建、烘焙系统
 - `editor`：当前编辑器应用树
 - `programs`：各类可执行入口
@@ -135,11 +135,11 @@ XCEngine/
         passes/
         pipelines/
         frame_graph/
-        gpu_cache/
+        Caches/
       audio/
       physics/
       scripting/
-  pipeline/
+  Pipeline/
     core/
       SourceAssetDB/
       ArtifactDB/
@@ -187,7 +187,7 @@ XCEngine/
     foundation/
     shared/
     runtime/
-    pipeline/
+    Pipeline/
     editor/
     e2e/
   docs/
@@ -210,7 +210,7 @@ XCEngine/
 - 序列化
 - 文件系统封装
 
-### 5.2 `engine/shared`
+### 5.2 `engine/Shared`
 
 共享契约层承载跨阶段稳定数据结构：
 
@@ -223,7 +223,7 @@ XCEngine/
 
 这一层只放数据契约，不放 manager、loader、cache、importer、orchestrator。
 
-### 5.3 `engine/runtime`
+### 5.3 `engine/Runtime`
 
 运行时层负责：
 
@@ -282,13 +282,13 @@ editor 内部目录重组不属于第一阶段工作。
 
 当前主要系统映射如下：
 
-- `ResourceManager` -> `engine/runtime/asset/AssetManager`
-- `ResourceCache` -> `engine/runtime/asset/ResourceStore`
-- `AsyncLoader` -> `engine/runtime/asset/AsyncLoad`
-- `ProjectAssetIndex` -> `pipeline/core/SourceIndex`
-- `AssetImportService` -> `pipeline/core/ImportService`
-- `AssetDatabase` -> `pipeline/core/SourceAssetDB` + `pipeline/core/ArtifactDB`
-- `RenderResourceCache` -> `engine/runtime/rendering/gpu_cache`
+- `ResourceManager` -> `engine/Runtime/Asset/AssetManager`
+- `ResourceCache` -> `engine/Runtime/Asset/ResourceStore`
+- `AsyncLoader` -> `engine/Runtime/Asset/AsyncLoad`
+- `ProjectAssetIndex` -> `Pipeline/Core/SourceIndex`
+- `AssetImportService` -> `Pipeline/Core/ImportService`
+- `AssetDatabase` -> `Pipeline/Core/SourceAssetDB` + `Pipeline/Core/ArtifactDB`
+- `RenderResourceCache` -> `engine/Runtime/Rendering/Caches`
 
 重构过程中，editor 迭代路径先保持在现有项目工作流上，再逐步完成职责分拆。
 
@@ -375,7 +375,7 @@ xcshadercook
 
 工作项：
 
-- 把文件迁移到 `engine/foundation`、`engine/shared`、`engine/runtime`、`pipeline`
+- 把文件迁移到 `engine/foundation`、`engine/Shared`、`engine/Runtime`、`pipeline`
 - 更新 include、CMake 和测试
 - 除非前置拆分强依赖，否则不在这一阶段重组 editor 内部树
 
@@ -411,3 +411,29 @@ xcshadercook
 4. shared 层只保留稳定数据契约。
 5. phases 1 到 3 期间，editor 日常迭代路径保持连续可用。
 6. 每个阶段完成后都要先编译 `XCEditor`，再执行 12 秒冒烟测试。
+
+## 10. 当前推进状态
+
+截至 `2026-05-01`：
+
+- `engine/Shared/Asset` 已承接 `ArtifactContainer`、`AssetGUID`、`ResourceTypes`、`ResourceDependencyGraph` 的真实定义与实现
+- `Pipeline/Core` 已承接 `AssetDatabase`、`AssetImportService`、`ProjectAssetIndex`、`ProjectAssetService` 与相关 contracts
+- `engine/Runtime/Asset` 已承接 `ResourceManager`、`ResourceCache`、`AsyncLoader`
+- `engine/Runtime/Resources` 已承接 `Texture`、`Mesh`、`AudioClip`、`Shader`、`Material`
+- 对应旧 `engine/include/XCEngine/Core/Asset/*` 与 `engine/include/XCEngine/Resources/*` 的迁移对象已逐步收窄为兼容 forwarding 层
+- `engine/Runtime/Scene` 已承接 `Scene`、`SceneRuntime`、`SceneManager`、`RuntimeLoop`、`ModelSceneInstantiation`
+- `Scene` 这一刀已完成 `XCEditor` 编译与 12 秒 editor smoke 验证
+
+当前活跃子计划：
+
+- `Runtime/Rendering/FrameData` 第一刀
+
+下一步优先项：
+
+- `Runtime/Rendering/Caches` 第一刀已完成，真实定义已迁到 `engine/Runtime/Rendering/Caches`
+- `Runtime/Rendering/Shadow` 第一刀已完成，真实定义已迁到 `engine/Runtime/Rendering/Shadow`
+- `Runtime/Rendering/Materials` 第一刀已完成，真实定义已迁到 `engine/Runtime/Rendering/Materials`
+- `Runtime/Rendering/Picking` 第一刀已完成，真实定义已迁到 `engine/Runtime/Rendering/Picking`
+- 继续收窄旧 `engine/include/XCEngine/Rendering/FrameData/*` public 头
+- 将 `RenderCameraData`、`RenderEnvironmentData`、`CullingResults`、`Visible*`、`RenderSceneData`、`RendererListUtils` 的真实定义迁到 `engine/Runtime/Rendering/FrameData`
+- 在不重组渲染主流程的前提下，继续把低耦合 rendering 支撑块从旧 `include/src` 物理布局中抽离出来