XCEngine/AGENT.md

# XCEngine Agent Guide

这个文件面向在当前仓库里工作的 coding agent / 开发者。它不负责介绍项目卖点，而是给出当前 checkout 的真实工程状态、优先入口、硬约束和推荐验证方式。

如果 README、旧文档和当前文件树 / `CMakeLists.txt` / 测试 target 冲突，以当前 checkout 为准，并在本次工作里顺手修正文档。

## 1. 开工顺序

进入仓库后，优先按下面顺序建立上下文：

1. [AGENT.md](AGENT.md)
2. [README.md](README.md)
3. 相关模块的 `CMakeLists.txt`
4. 对应模块最近的测试目录与聚合 target
5. 对应设计文档

当前最常用的设计入口：

- [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- [docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md)
- [docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md)
- [docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md)
- [docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md](docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md)
- [docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md](docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md)
- [docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md](docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md)
- [docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md](docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md)
- [docs/plan/XCUI完整架构设计与执行计划.md](docs/plan/XCUI完整架构设计与执行计划.md)
- [docs/plan/C#脚本模块下一阶段计划.md](docs/plan/C%23脚本模块下一阶段计划.md)
- [tests/TEST_SPEC.md](tests/TEST_SPEC.md)
- [tests/UI/TEST_SPEC.md](tests/UI/TEST_SPEC.md)

已归档但当前仍常用的背景文档：

- [Library资产导入与缓存系统收口计划（归档）](docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md)
- [API 文档第三轮任务池（归档基线）](docs/used/API文档实时同步任务池_2026-04-03.md)
- [XCUI Phase Status 2026-04-05（归档）](docs/used/XCUI_Phase_Status_2026-04-05.md)
- [Shader与Material系统下一阶段计划（归档）](docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md)
- [Unity 风格 Shader 体系正式化计划（归档）](docs/used/Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md)
- [Renderer 当前阶段正式收口（阶段归档）](docs/used/Renderer当前阶段正式收口计划_阶段归档_2026-04-10.md)
- [NanoVDB 后续正式化（阶段归档）](docs/used/NanoVDB稀疏体积渲染后续正式化计划_阶段归档_2026-04-10.md)
- [SceneViewport Overlay / Gizmo 重构计划（归档）](docs/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md)
- [Unity式 SceneView Gizmo 正式化方案（归档）](docs/used/Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md)
- [NanoVDB 第一阶段完成归档](docs/used/NanoVDB稀疏体积渲染正式集成计划_第一阶段完成归档_2026-04-09.md)

如果任务落在 API 文档：

1. 先检查 `docs/plan/` 下最新的 API 相关计划或并行任务板。当前工作树里已经存在多份 2026-04-09 的活跃文件，例如：
   - [docs/plan/API文档目录重构计划_2026-04-09.md](docs/plan/API文档目录重构计划_2026-04-09.md)
   - [docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md](docs/plan/API文档目录结构重大重构并行任务板_2026-04-09.md)
   - [docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md](docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md)
   - [docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md](docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md)
   - [docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md](docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md)
2. 如果这些活跃文件都不覆盖当前问题，再回看 [docs/used/API文档实时同步任务池_2026-04-03.md](docs/used/API文档实时同步任务池_2026-04-03.md) 作为最近一轮完成基线。
3. 再看 [docs/api-skill.md](docs/api-skill.md)。
4. 再看 `docs/api/main.md` 和 `docs/api/_meta/rebuild-status.md`，确认当前问题落在 `XCEngine` 还是 `XCEditor` 根树。
5. 一次只认领一个任务块，先改状态为 `DOING`，只写自己任务块允许的范围。

## 2. 当前工程事实

- 顶层 `CMakeLists.txt` 当前纳入 `engine/`、`editor/`、`new_editor/`、`managed/`、`mvs/RenderDoc/` 和 `tests/`。
- `engine/` 构建静态库 `XCEngine`；`editor/` 构建 `XCEditor`，但输出文件名仍是 `editor/bin/<Config>/XCEngine.exe`。
- `editor/` 目前继续保留为当前正式编辑器、行为对照和视觉基线来源。
- `new_editor/` 当前构建 `XCUIEditorLib`、`XCUIEditorHost`；启用 `XCENGINE_BUILD_XCUI_EDITOR_APP` 时会输出 `new_editor/bin/<Config>/XCUIEditor.exe`，并被视为未来正式编辑器主线，而不再只是临时 sandbox。
- editor 默认把仓库内的 `project/` 识别为工程根目录，也支持 `--project <path>` 覆盖。
- 当前工程真实使用 `Assets/ + .meta + Library/` 的项目布局；`project/Library/` 是当前 workflow 的一部分，不是可随手忽略的垃圾目录。
- Mono 运行时与 editor 的脚本类发现都从 `<project>/Library/ScriptAssemblies/` 加载程序集。
- 当前根目录里没有 `native` 占位项；更新目录树或迁移旧文档时，不要继续传播这条过期事实。
- 当前工作机是 Windows 文件系统；文档里统一写 `tests/Editor/`、`tests/Core/`、`tests/Scripting/` 等真实目录名，不要制造大小写噪音。
- `engine/CMakeLists.txt` 当前对 Vulkan 是硬依赖；`editor/` 和 `tests/` 首次配置会拉取 `ImGui` 与 `googletest`。

## 3. 子系统现状

### 3.1 Core / Asset / Resources

- `Core/Asset/AssetDatabase`、`AssetImportService`、`ProjectAssetIndex`、`ResourceManager` 已形成正式导入与运行时加载链路。
- 当前真实职责包括：
  - 扫描 `Assets/`
  - 为资源生成 `.meta`
  - 维护 `Library/SourceAssetDB/assets.db`
  - 维护 `Library/ArtifactDB/artifacts.db`
  - 写入 `Library/Artifacts/`
- 最新活跃设计文档已经把下一阶段目标收口到“启动阶段前置恢复索引 / 缓存状态，运行时按需异步加载 payload”。
- `BootstrapProject()` / `BootstrapProjectAssets()` 已正式接入启动链路；接下来重点是指标固化、UI 状态拆分和剩余同步兜底点审计。
- 当前还不要把 `AssetImportService`、`ProjectAssetIndex`、`ResourceManager` 的职责重新揉回一团；先看 [docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md)。
- 材质 artifact 当前是 schema v2：
  - `kMaterialArtifactSchemaVersion = 2`
  - magic `XCMAT02`
  - texture binding 序列化三元组是 `binding name + encoded AssetRef + optional path`
- `Material` 当前同时维护 loaded handle、稳定 `AssetRef` 与 path 元数据；`GetTexture()` 首次访问时可触发懒加载，`GetTextureBindingLoadedTexture()` 不触发加载。

### 3.2 Rendering

- 当前正式主链是 `SceneRenderer -> CameraRenderer -> RenderPipeline`。
- 现有正式能力包括：
  - forward 主几何渲染
  - `ObjectId` 渲染与 editor picking
  - `BuiltinInfiniteGridPass`
  - `BuiltinObjectIdOutlinePass`
  - `directional shadow`
  - `skybox`
  - `CameraRenderRequest::postScenePasses`
  - `CameraRenderRequest::overlayPasses`
- `post-process / final color` 当前处于正式化收口阶段，不再是纯预留接口。
- `NanoVDB` 体积渲染已进入当前正式运行链路，但 Vulkan / OpenGL 的 rollout 和多后端能力边界仍在继续收口。
- 当前资源与导入主线正在继续向 `Model` 资产架构与 `3DGS GaussianSplat` 资源链扩展，不要再把 `.obj/.fbx/.ply` 简化理解为“文件直读后立刻渲染”的旧 sample 流程。
- 当前主线不是 render graph，而是 shader / material contract、builtin pass contract 和 renderer-owned feature contract。

### 3.3 Editor

- editor 仍然是 `D3D12` 宿主应用。
- Scene/Game viewport 已通过引擎 `Rendering + RHI` 输出离屏纹理，再由 editor 宿主接入 ImGui。
- 当前 Scene View 主链已经显式拆成：
  - `SceneViewportChrome`
  - `SceneViewportInteractionFrame`
  - `SceneViewportNavigation`
  - `SceneViewportTransformGizmoCoordinator`
  - `ViewportHostService`
- `editor/src/Viewport/` 当前稳定存在的关键入口包括：
  - `SceneViewportCameraController`
  - `SceneViewportChrome`
  - `SceneViewportEditorModes`
  - `SceneViewportHudOverlay`
  - `SceneViewportInteractionActions`
  - `SceneViewportInteractionFrame`
  - `SceneViewportInteractionResolver`
  - `SceneViewportMoveGizmo`
  - `SceneViewportNavigation`
  - `SceneViewportOverlayBuilder`
  - `SceneViewportOverlayFrameCache`
  - `SceneViewportOverlayProviders`
  - `SceneViewportOverlaySpriteResources`
  - `SceneViewportPassSpecs`
  - `SceneViewportPicker`
  - `SceneViewportResourcePaths`
  - `SceneViewportRotateGizmo`
  - `SceneViewportScaleGizmo`
  - `SceneViewportShaderPaths`
  - `SceneViewportTransformGizmoCoordinator`
  - `SceneViewportTransformGizmoFrameBuilder`
  - `ViewportHostRenderFlowUtils`
  - `ViewportHostRenderTargets`
  - `ViewportHostSurfaceUtils`
  - `ViewportObjectIdPicker`
- `SceneViewportShaderPaths.h` 当前主要是兼容 include；路径真实 owner 已转到 `SceneViewportResourcePaths.h`。
- `tests/Editor/` 已有 `test_scene_viewport_chrome.cpp`、`test_scene_viewport_interaction_frame.cpp`、`test_scene_viewport_navigation.cpp` 与 `test_scene_viewport_transform_gizmo_coordinator.cpp`，不要再按“这些 helper 还没落地”理解当前 editor。

### 3.4 XCUI / New Editor

- `new_editor/` 是未来正式编辑器主线，不再只是 sandbox；旧 `editor/` 当前继续保留为正式编辑器、行为对照和视觉基线。
- 当前宿主分层是：
  - `XCUIEditorLib`
  - `XCUIEditorHost`
  - `XCUIEditorApp`（可选应用壳）
- 共享 UI core、runtime screen host 与 widget 基础能力主要沉淀在 `engine/include/XCEngine/UI/` 与 `engine/src/UI/`；`new_editor/` 负责 XCUI editor 壳、宿主与产品装配。
- `tests/UI/` 是当前 XCUI `Core / Editor / Runtime` 三层的唯一正式基础层验证入口；`new_editor/` 不承担测试堆场职责。

### 3.5 Scripting

- 当前脚本链路由三部分组成：
  - `managed/XCEngine.ScriptCore/`
  - `managed/GameScripts/`
  - `project/Assets/**/*.cs`
- 构建结果分两类：
  - `xcengine_managed_assemblies` 生成引擎示例程序集
  - `xcengine_project_managed_assemblies` 生成项目脚本程序集，并复制到 `project/Library/ScriptAssemblies/`
- `project/Library/ScriptAssemblies/` 里的当前快照可能落后于目标态；判断“成功构建后应有哪些程序集”时，以 `managed/CMakeLists.txt`、`editor/src/Scripting/EditorScriptAssemblyBuilder.cpp` 与对应测试为准，而不是只看工作树里此刻存着什么。
- `ScriptEngine` 当前已具备脚本类发现、字段元数据读取、默认值读取、stored override 管理和运行时 managed field 同步。
- Inspector 侧已经存在 `ScriptComponentEditor`；脚本相关改动通常同时影响 `engine/src/Scripting/`、`managed/`、`project/Assets/Scripts/`、`editor/src/ComponentEditors/` 与 `tests/Scripting/` / `tests/Editor/`。

### 3.6 Tests

当前测试主目录包括：

- `tests/Components/`
- `tests/Core/`
- `tests/Debug/`
- `tests/Editor/`
- `tests/Fixtures/`
- `tests/Input/`
- `tests/Memory/`
- `tests/NewEditor/`
- `tests/Rendering/`
- `tests/Resources/`
- `tests/RHI/`
- `tests/Scene/`
- `tests/Scripting/`
- `tests/Threading/`
- `tests/UI/`

需要特别记住的聚合 target：

- `rhi_all_tests`
- `rendering_all_tests`
- `rendering_phase_regression`
- `editor_tests`
- `core_ui_tests`
- `editor_ui_tests`
- `runtime_ui_tests`
- `scripting_tests`

## 4. 不可忽视的硬约束

### 4.1 文档服从真实 checkout

如果文档与当前目录结构、target 名称、代码事实冲突：

- 先信当前 checkout
- 再更新文档

不要沿用“计划中但未落地”的旧说法。

### 4.2 不要随手清空 `project/Library/` 或删 `.meta`

`project/Library/` 虽然可重建，但它在当前 workflow 里承载：

- `SourceAssetDB`
- `ArtifactDB`
- `Artifacts`
- `ScriptAssemblies`

涉及资源导入、artifact、脚本程序集发现时，不要把删库重建当作默认修复手段。

### 4.3 RHI 抽象层与后端层必须分层

`tests/RHI/unit/` 与 `tests/RHI/integration/` 只能依赖公共 RHI 抽象。

不要为了让抽象层测试通过而：

- include 后端私有头
- 直接使用原生句柄
- 给单一后端写抽象层特判

如果必须这么做，优先修 RHI，而不是污染测试边界。

### 4.4 Editor 是宿主，不是第二套渲染器

如果 viewport、outline、picking 或 gizmo 有问题，优先判断：

- 是 `Rendering` 模块问题
- 是 `RenderSurface` / RHI 输出问题
- 还是 editor 宿主接线问题

不要因为 editor 当前是 D3D12 host，就把问题草率塞回 editor 私有渲染逻辑。

### 4.5 不要再把新逻辑堆回旧的 ImGui world overlay

新的世界空间 overlay / gizmo 逻辑如果仍然直接堆在：

- `SceneViewPanel.cpp`
- panel 层临时拼的 immediate draw / ad-hoc overlay 路径

通常就是逆着当前架构方向在走。优先入口是：

- `CameraRenderRequest::overlayPasses`
- `SceneViewportOverlayBuilder`
- `SceneViewportEditorOverlayPass`
- `SceneViewportTransformGizmoCoordinator`

### 4.6 `backpack` 导入行为必须统一

这是仓库里已经踩过的真实坑。`backpack` 相关资源在以下路径中的导入行为必须保持一致：

- editor
- runtime
- rendering tests
- rhi abstraction tests

不要只在局部路径里额外加 `MeshImportFlags::FlipUVs` 之类的补丁。

### 4.7 `mvs/` 不是长期主线模块

`mvs/` 里有样例、研究和工具，但当前正式引擎逻辑的长期落点应优先是：

- `engine/`
- `editor/`
- `managed/`
- `tests/`

不要把正式渲染逻辑重新堆回 sample 子树长期存活。

### 4.8 API 文档任务必须看最新计划并复跑审计

只要任务涉及 `docs/api/`：

1. 先读 `docs/plan/API文档目录*.md` 里日期最新的 API 计划 / 并行任务板。
2. 再看 [docs/api-skill.md](docs/api-skill.md) 和 `docs/api/_meta/rebuild-status.md`。
3. 如果活跃计划没有覆盖当前问题，再回看 [docs/used/API文档实时同步任务池_2026-04-03.md](docs/used/API文档实时同步任务池_2026-04-03.md) 作为最近一轮归档基线。
4. 改完必须重新执行：

```powershell
python -B docs/api/_tools/audit_api_docs.py
```

如果审计没回绿，不算完成。
当前审计口径已经同时覆盖：

- `engine/include/XCEngine/**`
- `new_editor/include/XCEditor/**`
- `editor/src/**`

## 5. 推荐构建与验证入口

### 5.1 配置

```bash
cmake -S . -B build -A x64
```

如果当前任务不需要 Mono：

```bash
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```

### 5.2 常用构建 target

```bash
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
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 scripting_tests
```

### 5.3 按改动类型选择验证

- 改 `engine/RHI`：先跑 `rhi_abstraction_tests` 或 `rhi_backend_tests`，再决定是否扩展到 `rhi_all_tests`
- 改 `engine/Rendering`：先跑 `rendering_unit_tests` 和最相关的 `rendering_integration_*`，必要时再跑 `rendering_phase_regression`
- 改 `editor/Viewport`、`editor/UI` 或 Inspector：先跑 `editor_tests`
- 改 `engine/Scripting`、`managed/`、`project/Assets/Scripts/`：先构建 `xcengine_project_managed_assemblies`，再跑 `scripting_tests`
- 改资源导入、`.meta`、artifact 相关逻辑：优先跑 `tests/Resources/` 里的对应 target

### 5.4 全量测试入口

```bash
ctest --test-dir build -C Debug --output-on-failure
```

## 6. 按任务找入口

- RHI 抽象与后端：`engine/include/XCEngine/RHI/`、`engine/src/RHI/`、`tests/RHI/`
- Rendering 主链与 pass：`engine/include/XCEngine/Rendering/`、`engine/src/Rendering/`、`tests/Rendering/`
- 资源导入与工程布局：`engine/include/XCEngine/Core/Asset/`、`engine/src/Core/Asset/`、`editor/src/Managers/ProjectManager.cpp`、`project/Assets/`、`project/Library/`
- Material / shader / artifact：`engine/include/XCEngine/Resources/Material/`、`engine/src/Resources/Material/`、`engine/include/XCEngine/Core/Asset/ArtifactFormats.h`、`tests/Resources/Material/`
- Editor viewport / gizmo / picking：`editor/src/Viewport/`、`editor/src/panels/SceneViewPanel.cpp`、`tests/Editor/`
- XCUI / new_editor：`engine/include/XCEngine/UI/`、`engine/src/UI/`、`new_editor/include/XCEditor/`、`new_editor/src/`、`tests/UI/`
- Editor actions / project routing：`editor/src/Actions/`、`editor/src/Commands/`、`editor/src/Core/`、`editor/src/Managers/`、`tests/Editor/test_action_routing.cpp`
- 脚本运行时与程序集：`engine/include/XCEngine/Scripting/`、`engine/src/Scripting/`、`managed/`、`project/Assets/Scripts/`、`tests/Scripting/`
- API 文档：`docs/api/main.md`、`docs/api/XCEngine/`、`docs/api/XCEditor/`、`docs/api/_guides/`、`docs/api/_tools/audit_api_docs.py`、`docs/plan/API文档目录*.md`、`docs/used/API文档实时同步任务池_2026-04-03.md`

## 7. 适合当前仓库的工作方式

1. 先读当前模块的 `CMakeLists.txt`、最近测试和设计文档，再动代码。
2. 优先在既有模块边界里解决问题，不要绕开系统回到 sample 式实现。
3. 先跑与改动最相关的最小验证，再决定是否扩大全量验证。
4. 目录、target、入口、文档名改了，就同步更新 README / AGENT / 相关说明。
5. 如果任务会有意重建 `project/Library/`、脚本程序集或 `.meta`，在结果里明确说明哪些文件是有意生成的。

这份文档的作用，是给 agent 一条“当前真实工程长什么样”的基线。它本身也必须随着工程演进一起维护，不能再落回旧状态说明。