docs: rewrite root README

README.md

@@ -1,31 +1,40 @@
 # XCEngine
 
-XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting` 的可运行闭环，不再只是若干独立 sample 的集合。
+`XCEngine` 是一个 Windows-first、editor-first 的 C++20 游戏引擎工作区。当前主线围绕 `RHI -> Rendering -> Editor -> Asset Pipeline -> Mono Scripting` 演进，目标不是堆 sample，而是把可运行的引擎与编辑器主链持续收口成型。
-
-这份 README 面向引擎用户：重点回答项目是什么、当前能做什么、怎么构建、怎么启动，以及当前仓库各目录分别承担什么职责。面向参与引擎实现和文档维护的 coding agent，请看 [AGENT.md](AGENT.md)。
 
 ## 项目定位
 
-- `engine/` 构建静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Scripting` 等核心模块。
+- `engine/` 提供核心静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Input`、`Audio`、`Scripting` 等模块。
-- `editor/` 构建桌面编辑器 `XCEditor`，输出文件名仍为 `XCEngine.exe`，默认打开仓库内的 `project/`。
+- `editor/` 是当前正式桌面编辑器，宿主基于 Win32 + D3D12，编辑器 target 名为 `XCEditor`，输出文件名为 `XCEngine.exe`。
-- `new_editor/` 维护基于 `XCUI` 的新宿主与 UI sandbox，当前与旧 `editor/` 并行演进，应用输出名为 `XCUIEditor.exe`。
+- `new_editor/` 是基于 `XCUI` 的新编辑器主线，当前仍在并行演进。
-- `project/` 是随仓库维护的示例工程，已经采用 `Assets/ + .meta + Library/` 的工程布局。
+- `project/` 是随仓库维护的示例工程，已经采用 `Assets + .meta + Library` 布局。
-- `managed/` 负责 `XCEngine.ScriptCore.dll`、示例 `GameScripts.dll` 以及项目脚本程序集构建。
+- `tests/` 覆盖 Engine、Rendering、RHI、Editor、Scripting、UI 等主线模块。
-- `tests/` 覆盖 Engine、RHI、Rendering、Editor、Scripting、XCUI 等主线模块。
 
-## 当前能力概览
+## 当前能力
 
-- `RHI` 当前维护 `D3D12 / OpenGL / Vulkan` 三后端。
+- `RHI` 当前维护 `D3D12 / OpenGL / Vulkan` 三个后端。
-- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链，支持 `ObjectId`、`InfiniteGrid`、`Outline`、`overlayPasses` 等能力。
+- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链。
-- `Core/Asset` 已经不是简单加载器，当前真实维护 `Assets/.meta/Library` 风格的 `AssetDatabase`、artifact 缓存和项目资源索引。
+- Scene View 已接通 object-id picking、selection outline、grid、overlay 与 gizmo 渲染。
-- `Library` 当前已经采用“启动阶段恢复索引与缓存状态 + 运行时按需异步恢复 payload”的混合工作流，`BootstrapProject()` 已接入正式启动链路。
+- 资源系统已采用 `AssetDatabase + Artifact + Library` 工作流，而不是简单文件直读。
-- `Material` 与材质 artifact 已经进入稳定格式阶段，当前 `.xcmat` 使用 schema v2。
+- `Material / Shader / Texture / Mesh` 已接入正式资源导入与运行时加载链路。
-- 编辑器 Scene/Game viewport 已通过引擎 `Rendering + RHI` 链路渲染到离屏纹理，再接入 ImGui。
+- 编辑器已支持项目加载、Scene/Game viewport、Inspector、Hierarchy、Project 面板等基础闭环。
-- `ScriptComponent` 已打通脚本类发现、字段元数据读取、字段编辑和运行时字段同步。
+- Mono C# 脚本运行时与项目脚本程序集构建链路已接入当前工作区。
+- `new_editor/` 正在推进 `XCUI` 宿主、控件与 shell 体系。
+
+## 仓库结构
+
+- `engine/`：引擎核心实现与公共头文件。
+- `editor/`：当前正式编辑器与 viewport 接线。
+- `new_editor/`：XCUI 新编辑器主线。
+- `managed/`：`XCEngine.ScriptCore` 与示例托管程序集。
+- `project/`：示例工程与随仓库维护的资产。
+- `tests/`：单元测试、集成测试与阶段性回归入口。
+- `docs/`：架构说明、API 文档、计划与历史归档。
+- `mvs/`：原型、实验工程与外部参考材料。
 
 ## 环境要求
 
-当前推荐在 Windows 上使用和构建。
+当前推荐在 Windows 上构建和运行。
 
 - Windows 10/11
 - Visual Studio 2022 / MSVC v143
@@ -34,492 +43,109 @@ XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎
 - .NET SDK
 - Git LFS
 
-启用 Mono 脚本运行时时，还需要：
+脚本运行时启用时，还需要：
 
-- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 头文件、静态库与 `mscorlib.dll`
+- 可用的 Mono 依赖，默认路径来自 `参考/Fermion/Fermion/external/mono`
 
 补充说明：
 
-- `engine/CMakeLists.txt` 当前对 `Vulkan` 是硬依赖，未配置 Vulkan SDK 时无法完成配置。
+- 当前根 CMake 配置里，`Vulkan SDK` 仍是硬依赖。
-- `editor/` 和 `tests/` 首次配置会通过 `FetchContent` 从 Gitee 镜像拉取 `ImGui` 与 `googletest`；离线环境请确保已有可复用的 `_deps` 缓存。
+- NanoVDB 头文件是可选能力，仅影响 `.nvdb` 体积资源支持。
-- 如果需要 `mvs/3DGS-Unity/room.ply` 这类大文件示例，请先执行 Git LFS 拉取。
+- 如果仓库里的大资源依赖 Git LFS，请先执行 `git lfs pull`。
 
 ## 快速开始
 
 ### 1. 配置
 
-```bash
+```powershell
 cmake -S . -B build -A x64
 ```
 
 如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：
 
-```bash
+```powershell
 cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
 ```
 
-### 2. 构建常用目标
+### 2. 构建当前编辑器
 
-```bash
+```powershell
-cmake --build build --config Debug --target XCEngine
 cmake --build build --config Debug --target XCEditor
-cmake --build build --config Debug --target xcengine_managed_assemblies
-cmake --build build --config Debug --target xcengine_project_managed_assemblies
 ```
 
-说明：
+编辑器产物路径：
 
-- `XCEngine` 是引擎静态库。
+- `editor/bin/Debug/XCEngine.exe`
-- `XCEditor` 是编辑器 target，输出文件名仍为 `editor/bin/<Config>/XCEngine.exe`。
-- `xcengine_managed_assemblies` 生成 `managed/` 下的示例托管程序集。
-- `xcengine_project_managed_assemblies` 会扫描 `project/Assets/**/*.cs`，并把结果输出到 `project/Library/ScriptAssemblies/`。
 
-### 3. 启动编辑器
+### 3. 运行编辑器
 
-```bash
+```powershell
 .\editor\bin\Debug\XCEngine.exe
 ```
 
-默认情况下，编辑器会自动把仓库内的 `project/` 识别为工程根目录。也可以显式指定其他工程：
+显式指定工程目录：
 
-```bash
+```powershell
-.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\MyProject
+.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project
 ```
 
-如果 Inspector 里看不到 C# 脚本类，先确认 `project/Library/ScriptAssemblies/` 中已经生成下面这 3 个程序集。当前工作树如果暂时缺少 `XCEngine.ScriptCore.dll`，通常说明项目脚本程序集还没有按最新状态完成重建：
+### 4. 构建项目脚本程序集
 
-- `XCEngine.ScriptCore.dll`
+如果你要验证 `ScriptComponent`、脚本类发现或 Inspector 字段编辑，先构建：
-- `GameScripts.dll`
-- `mscorlib.dll`
 
-### 4. 当前推荐验证入口
+```powershell
+cmake --build build --config Debug --target xcengine_project_managed_assemblies
+```
 
-```bash
+### 5. 可选构建 XCUI 新编辑器
+
+```powershell
+cmake --build build --config Debug --target XCUIEditorApp
+```
+
+产物路径通常为：
+
+- `new_editor/bin/Debug/XCUIEditor.exe`
+
+## 测试
+
+列出测试：
+
+```powershell
 ctest --test-dir build -N -C Debug
+```
+
+运行测试：
+
+```powershell
 ctest --test-dir build -C Debug --output-on-failure
 ```
 
-按模块常用的构建 / 验证 target：
+常用目标：
 
-```bash
+```powershell
-cmake --build build --config Debug --target rhi_all_tests
-cmake --build build --config Debug --target rendering_all_tests
-cmake --build build --config Debug --target rendering_phase_regression
 cmake --build build --config Debug --target editor_tests
+cmake --build build --config Debug --target rendering_all_tests
+cmake --build build --config Debug --target rhi_all_tests
 cmake --build build --config Debug --target scripting_tests
 ```
 
-## 当前仓库状态
+更细的测试组织与约定见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。
 
-### Engine
+## 文档入口
 
-- `RHI` 已经不是单后端实验代码，而是 `D3D12 / OpenGL / Vulkan` 三后端并行维护。
+- 编辑器说明：[editor/README.md](editor/README.md)
-- `Rendering` 当前正式主线是 `SceneRenderer -> CameraRenderer -> RenderPipeline`，而不是 sample 私有渲染分支。
-- `Resources` 与 `Core/Asset` 已形成项目资源导入、artifact 缓存和运行时加载的统一链路。
-
-### Editor
-
-- 当前 editor 是 `D3D12` 宿主应用，但 Scene/Game viewport 渲染本身走引擎 `Rendering + RHI`。
-- `Viewport` 子系统当前已经拆成更清晰的链路：`SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService`。
-- `tests/Editor/` 已覆盖 `SceneViewportChrome`、`SceneViewportInteractionFrame`、`SceneViewportNavigation`、`SceneViewportTransformGizmoCoordinator` 等新 helper。
-
-### Project & Scripting
-
-- 示例工程位于 `project/`，工程文件是 `Project.xcproject`，启动场景为 `Assets/Scenes/Main.xc`。
-- `project/Library/` 虽然是生成目录，但在当前 workflow 里承担 `SourceAssetDB`、`ArtifactDB`、`Artifacts`、`ScriptAssemblies` 等关键角色。
-- `managed/` 会生成引擎脚本 API 与示例脚本程序集，项目资产下的 `.cs` 文件也会单独编译为项目脚本程序集。
-
-### Tests
-
-- `tests/` 已覆盖 `Core`、`Memory`、`Threading`、`Scene`、`Resources`、`RHI`、`Rendering`、`Editor`、`Scripting` 等主线模块。
-- `tests/Rendering/` 当前维护一组集成场景测试。
-- `tests/RHI/` 同时维护抽象层测试与后端专用测试。
-
-## 完整目录结构
-
-以下目录树按当前工作树整理，保留了当前 workflow 已经真实使用的生成目录与关键子树；省略 `.git/`、`build/_deps/` 与部分重复资源文件。像 `project/.xceditor/thumbs/`、`project/Library/Artifacts/` 这类会随本地导入状态变化的内容，用结构模式表示。
-
-```text
-XCEngine/
-|- .gitattributes
-|- .gitignore
-|- AGENT.md
-|- CMakeLists.txt
-|- README.md
-|- build/                                      # 本地 CMake 构建输出
-|- docs/
-|  |- api/
-|  |  |- XCEngine/
-|  |  |- _guides/
-|  |  |- _meta/
-|  |  |- _tools/
-|  |  `- main.md
-|  |- issues/
-|  |  `- Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md
-|  |- plan/
-|  |  |- end/
-|  |  |  |- RHI模块设计与实现/
-|  |  |  |  |- RHIFence.md
-|  |  |  |  `- RHI模块总览.md
-|  |  |  `- 编辑器与运行时分层架构设计.md
-|  |  |- 开题报告和任务书/
-|  |  |- 旧版题目/
-|  |  |- API文档实时同步任务池_2026-04-03.md
-|  |  |- C#脚本模块下一阶段计划.md
-|  |  |- Editor架构说明.md
-|  |  |- Library启动预热与运行时异步加载混合重构计划_2026-04-04.md
-|  |  |- Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md
-|  |  |- Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md
-|  |  |- Unity SRP API参考文档.md
-|  |  |- XCUI_Phase_Status_2026-04-05.md
-|  |  |- XCUI完整架构设计与执行计划.md
-|  |  `- Unity绝区零开发文档还原版.md
-|  |- used/                                   # 历史材料、归档计划与截图
-|  |  |- API文档实时同步任务池_2026-04-03_第一轮归档.md
-|  |  |- API文档实时同步任务池_2026-04-03_第二轮归档.md
-|  |  |- C#脚本模块的设计与实现_阶段一归档_2026-04-03.md
-|  |  |- Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md
-|  |  |- Renderer结构收口与代码正式化计划_完成归档_2026-04-05.md
-|  |  |- SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md
-|  |  |- Shader与Material系统下一阶段计划_完成归档_2026-04-04.md
-|  |  |- Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md
-|  |  |- Unity式Tick系统与PlayMode运行时方案-阶段进展.md
-|  |  `- Unity式Tick系统与PlayMode运行时方案.md
-|  |- api-skill.md
-|  |- blueprint-skill.md
-|  `- blueprint.md
-|- editor/
-|  |- CMakeLists.txt
-|  |- README.md
-|  |- bin/                                   # 编辑器输出目录，产物名为 XCEngine.exe
-|  |- resources/
-|  |  `- Icons/
-|  `- src/
-|     |- Actions/
-|     |- Commands/
-|     |- ComponentEditors/
-|     |- Core/
-|     |- Layers/
-|     |- Layout/
-|     |- Managers/
-|     |- panels/
-|     |  |- ConsolePanel.cpp
-|     |  |- ConsolePanel.h
-|     |  |- GameViewPanel.cpp
-|     |  |- GameViewPanel.h
-|     |  |- HierarchyPanel.cpp
-|     |  |- HierarchyPanel.h
-|     |  |- InspectorPanel.cpp
-|     |  |- InspectorPanel.h
-|     |  |- MenuBar.cpp
-|     |  |- MenuBar.h
-|     |  |- Panel.cpp
-|     |  |- Panel.h
-|     |  |- PanelCollection.h
-|     |  |- ProjectPanel.cpp
-|     |  |- ProjectPanel.h
-|     |  |- SceneViewPanel.cpp
-|     |  |- SceneViewPanel.h
-|     |  `- ViewportPanelContent.h
-|     |- Platform/
-|     |- Scripting/
-|     |- UI/
-|     |- Utils/
-|     |- Viewport/
-|     |  |- Passes/
-|     |  |  |- SceneViewportEditorOverlayPass.cpp
-|     |  |  |- SceneViewportEditorOverlayPass.h
-|     |  |  |- SceneViewportGridPass.cpp
-|     |  |  |- SceneViewportGridPass.h
-|     |  |  |- SceneViewportSelectionOutlinePass.cpp
-|     |  |  `- SceneViewportSelectionOutlinePass.h
-|     |  |- IViewportHostService.h
-|     |  |- SceneViewportCameraController.h
-|     |  |- SceneViewportChrome.cpp
-|     |  |- SceneViewportChrome.h
-|     |  |- SceneViewportEditorModes.h
-|     |  |- SceneViewportEditorOverlayData.h
-|     |  |- SceneViewportHudOverlay.cpp
-|     |  |- SceneViewportHudOverlay.h
-|     |  |- SceneViewportInteractionActions.cpp
-|     |  |- SceneViewportInteractionActions.h
-|     |  |- SceneViewportInteractionFrame.h
-|     |  |- SceneViewportInteractionResolver.cpp
-|     |  |- SceneViewportInteractionResolver.h
-|     |  |- SceneViewportMath.h
-|     |  |- SceneViewportMoveGizmo.cpp
-|     |  |- SceneViewportMoveGizmo.h
-|     |  |- SceneViewportNavigation.h
-|     |  |- SceneViewportOrientationGizmo.cpp
-|     |  |- SceneViewportOrientationGizmo.h
-|     |  |- SceneViewportOverlayBuilder.cpp
-|     |  |- SceneViewportOverlayBuilder.h
-|     |  |- SceneViewportOverlayFrameCache.cpp
-|     |  |- SceneViewportOverlayFrameCache.h
-|     |  |- SceneViewportOverlayHandleBuilder.h
-|     |  |- SceneViewportOverlayHitTester.h
-|     |  |- SceneViewportOverlayProviders.cpp
-|     |  |- SceneViewportOverlayProviders.h
-|     |  |- SceneViewportOverlaySpriteResources.cpp
-|     |  |- SceneViewportOverlaySpriteResources.h
-|     |  |- SceneViewportPassSpecs.h
-|     |  |- SceneViewportPicker.cpp
-|     |  |- SceneViewportPicker.h
-|     |  |- SceneViewportRenderPlan.h
-|     |  |- SceneViewportResourcePaths.h
-|     |  |- SceneViewportRotateGizmo.cpp
-|     |  |- SceneViewportRotateGizmo.h
-|     |  |- SceneViewportScaleGizmo.cpp
-|     |  |- SceneViewportScaleGizmo.h
-|     |  |- SceneViewportShaderPaths.h
-|     |  |- SceneViewportTransformGizmoCoordinator.cpp
-|     |  |- SceneViewportTransformGizmoCoordinator.h
-|     |  |- SceneViewportTransformGizmoFrameBuilder.h
-|     |  |- ViewportHostRenderFlowUtils.h
-|     |  |- ViewportHostRenderTargets.h
-|     |  |- ViewportHostService.h
-|     |  |- ViewportHostSurfaceUtils.h
-|     |  `- ViewportObjectIdPicker.h
-|     |- Application.cpp
-|     |- Application.h
-|     |- EditorApp.rc
-|     |- EditorResources.h
-|     |- Theme.cpp
-|     |- Theme.h
-|     `- main.cpp
-|- engine/
-|  |- CMakeLists.txt
-|  |- include/
-|  |  `- XCEngine/
-|  |     |- Audio/
-|  |     |- Components/
-|  |     |- Core/
-|  |     |  |- Asset/
-|  |     |  |- Containers/
-|  |     |  |- IO/
-|  |     |  `- Math/
-|  |     |- Debug/
-|  |     |- Input/
-|  |     |- Memory/
-|  |     |- Platform/
-|  |     |  `- Windows/
-|  |     |- Rendering/
-|  |     |  |- Passes/
-|  |     |  |- Pipelines/
-|  |     |  |- CameraRenderer.h
-|  |     |  |- CameraRenderRequest.h
-|  |     |  |- ObjectIdPass.h
-|  |     |  |- RenderPipeline.h
-|  |     |  |- RenderSurface.h
-|  |     |  `- SceneRenderer.h
-|  |     |- Resources/
-|  |     |  |- AudioClip/
-|  |     |  |- Material/
-|  |     |  |- Mesh/
-|  |     |  |- Shader/
-|  |     |  `- Texture/
-|  |     |- RHI/
-|  |     |  |- D3D12/
-|  |     |  |- OpenGL/
-|  |     |  `- Vulkan/
-|  |     |- Scene/
-|  |     |- Scripting/
-|  |     |  `- Mono/
-|  |     `- Threading/
-|  |- src/                                   # 与 include/XCEngine 中的主模块一一对应
-|  |- third_party/
-|  |  |- assimp/
-|  |  |- GLAD/
-|  |  |- kissfft/
-|  |  |- renderdoc/
-|  |  `- stb/
-|  `- tools/
-|     `- renderdoc_parser/
-|- managed/
-|  |- CMakeLists.txt
-|  |- GameScripts/
-|  `- XCEngine.ScriptCore/
-|- mvs/
-|  |- 3DGS-Unity/
-|  |- D3D12/
-|  |- Music fluctuations/
-|  |- OpenGL/
-|  |- RenderDoc/
-|  |- Res/
-|  |- ui/                                   # 早期 ImGui + D3D12 UI 原型
-|  `- VolumeRenderer/
-|- new_editor/
-|  |- app/
-|  |  |- Host/
-|  |  |- Application.cpp
-|  |  |- Application.h
-|  |  `- main.cpp
-|  |- bin/                                   # XCUIEditor.exe 输出目录
-|  |- include/
-|  |  `- XCEditor/
-|  |     |- Core/
-|  |     `- Widgets/
-|  |- src/
-|  |  |- Core/
-|  |  |- Platform/
-|  |  `- Widgets/
-|  |- ui/
-|  `- CMakeLists.txt
-|- project/
-|  |- .xceditor/
-|  |  |- imgui_layout.ini
-|  |  `- thumbs/
-|  |- Assets/
-|  |  |- Materials/
-|  |  |- Materials.meta
-|  |  |- Models/
-|  |  |- Models.meta
-|  |  |- New Folder.meta
-|  |  |- New Folder 1.meta
-|  |  |- New Material.mat
-|  |  |- New Material.mat.meta
-|  |  |- Scenes/
-|  |  |  |- Backpack.xc
-|  |  |  |- Backpack.xc.meta
-|  |  |  |- Main.xc
-|  |  |  |- Main.xc.meta
-|  |  |  |- NewFolder.meta
-|  |  |  `- NewFolder/
-|  |  |- Scenes.meta
-|  |  |- Scripts/
-|  |  |  |- ProjectScriptProbe.cs
-|  |  |  |- ProjectScriptProbe.cs.meta
-|  |  |  |- Textures/
-|  |  |  |- Textures.meta
-|  |  |  |- TickLogProbe.cs
-|  |  |  `- TickLogProbe.cs.meta
-|  |  `- Scripts.meta
-|  |- Library/
-|  |  |- ArtifactDB/
-|  |  |  `- artifacts.db
-|  |  |- Artifacts/
-|  |  |  `- <bucket>/<artifact-id>/
-|  |  |- ScriptAssemblies/
-|  |  |  |- GameScripts.dll
-|  |  |  `- mscorlib.dll
-|  |  `- SourceAssetDB/
-|  |     `- assets.db
-|  |- Assets.meta
-|  `- Project.xcproject
-|- scripts/
-|  `- Run-RendererPhaseRegression.ps1
-|- tests/
-|  |- CMakeLists.txt
-|  |- TEST_SPEC.md
-|  |- Components/
-|  |- Core/
-|  |  |- Asset/
-|  |  |- Containers/
-|  |  |- IO/
-|  |  `- Math/
-|  |- Debug/
-|  |- Editor/
-|  |  |- CMakeLists.txt
-|  |  |- test_action_routing.cpp
-|  |  |- test_application_asset_cache_stub.cpp
-|  |  |- test_builtin_icon_layout_utils.cpp
-|  |  |- test_editor_console_sink.cpp
-|  |  |- test_editor_script_assembly_builder.cpp
-|  |  |- test_editor_script_assembly_builder_utils.cpp
-|  |  |- test_play_session_controller.cpp
-|  |  |- test_play_session_controller_scripting.cpp
-|  |  |- test_scene_viewport_camera_controller.cpp
-|  |  |- test_scene_viewport_chrome.cpp
-|  |  |- test_scene_viewport_interaction_actions.cpp
-|  |  |- test_scene_viewport_interaction_frame.cpp
-|  |  |- test_scene_viewport_interaction_resolver.cpp
-|  |  |- test_scene_viewport_move_gizmo.cpp
-|  |  |- test_scene_viewport_navigation.cpp
-|  |  |- test_scene_viewport_overlay_providers.cpp
-|  |  |- test_scene_viewport_overlay_renderer.cpp
-|  |  |- test_scene_viewport_picker.cpp
-|  |  |- test_scene_viewport_rotate_gizmo.cpp
-|  |  |- test_scene_viewport_scale_gizmo.cpp
-|  |  |- test_scene_viewport_shader_paths.cpp
-|  |  |- test_scene_viewport_transform_gizmo_coordinator.cpp
-|  |  |- test_script_component_editor_utils.cpp
-|  |  |- test_viewport_host_surface_utils.cpp
-|  |  |- test_viewport_object_id_picker.cpp
-|  |  |- test_viewport_render_flow_utils.cpp
-|  |  `- test_viewport_render_targets.cpp
-|  |- Fixtures/
-|  |  `- Resources/
-|  |- Input/
-|  |- Memory/
-|  |- NewEditor/                             # 当前为空的预留测试根目录
-|  |- Rendering/
-|  |  |- integration/
-|  |  |  |- backpack_lit_scene/
-|  |  |  |- backpack_scene/
-|  |  |  |- camera_stack_scene/
-|  |  |  |- cull_material_scene/
-|  |  |  |- depth_sort_scene/
-|  |  |  |- material_state_scene/
-|  |  |  |- offscreen_scene/
-|  |  |  |- textured_quad_scene/
-|  |  |  `- transparent_material_scene/
-|  |  `- unit/
-|  |- Resources/
-|  |  |- AudioClip/
-|  |  |- Material/
-|  |  |- Mesh/
-|  |  |- Shader/
-|  |  `- Texture/
-|  |- RHI/
-|  |  |- D3D12/
-|  |  |  |- integration/
-|  |  |  `- unit/
-|  |  |- integration/
-|  |  |  |- backpack/
-|  |  |  |- fixtures/
-|  |  |  |- minimal/
-|  |  |  |- quad/
-|  |  |  |- sphere/
-|  |  |  `- triangle/
-|  |  |- OpenGL/
-|  |  |  |- integration/
-|  |  |  `- unit/
-|  |  |- unit/
-|  |  `- Vulkan/
-|  |     |- integration/
-|  |     `- unit/
-|  |- Scene/
-|  |- Scripting/
-|  |- Threading/
-|  `- UI/
-|     |- Core/
-|     |- Editor/
-|     |- Runtime/
-|     `- TEST_SPEC.md
-|- 参考/
-|  |- Fermion/
-|  |- TransformGizmo/
-|  |- unity editor/
-|  |- unity-editor-icons/
-|  |- unity-icons/
-|  `- UnityRuntimeSceneGizmo-master/
-`- .vscode/
-```
-
-## 关键文档入口
-
-- 编辑器模块说明：[editor/README.md](editor/README.md)
-- 面向引擎实现者和 coding agent 的协作基线：[AGENT.md](AGENT.md)
 - API 文档入口：[docs/api/main.md](docs/api/main.md)
 - 架构蓝图：[docs/blueprint.md](docs/blueprint.md)
-- RHI 基线设计：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
+- Editor 架构说明：[docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
-- Library 启动与运行时加载主线：[docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md)
-- Editor 当前架构：[docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
-- 当前 Shader / Material 主线：[docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md](docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md)
-- XCUI 总体蓝图：[docs/plan/XCUI完整架构设计与执行计划.md](docs/plan/XCUI完整架构设计与执行计划.md)
-- XCUI 阶段状态：[docs/plan/XCUI_Phase_Status_2026-04-05.md](docs/plan/XCUI_Phase_Status_2026-04-05.md)
 - 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)
+- 协作约定：[AGENT.md](AGENT.md)
 
-## 许可说明
+## 当前状态
+
+`XCEngine` 仍处于高频迭代阶段，但当前仓库已经不是“零散原型集合”，而是一个以编辑器工作流为中心持续收口的引擎工作区。接口、目录和构建细节仍可能调整，但主线方向已经比较明确：
+
+- 稳定 `RHI / Rendering / Asset Pipeline / Editor` 主链。
+- 继续推进 `Mono Scripting` 与项目脚本工作流。
+- 推进 `XCUI` 新编辑器主线从组件库走向完整宿主。
 
-当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。