XCEngine/editor/AGENT.md

# XCUI Editor Agent Guide

这份文档面向在 `editor/` 下工作的 coding agent / 开发者。它描述当前 editor 的真实工程边界、窗口架构和修改约束，不是产品说明。

如果本文和当前代码、`editor/CMakeLists.txt`、实际目录结构冲突，以当前 checkout 为准，并在本次工作里同步修正文档。

## 1. 当前定位

`editor/` 是当前 editor 应用主线。

当前工程事实：

- 构建目标是 `XCUIEditorApp`。
- 输出名是 `XCEngine`，构建产物为 `XCEngine.exe`。
- `editor/src` 是可复用的 XCEditor UI framework。
- `editor/include/XCEditor` 是 `editor/src` 的公开接口。
- `editor/app` 是具体 XCEngine editor 应用层。
- `editor/resources` 存放 editor 自有图标和 scene viewport shader。

虽然 `editor/CMakeLists.txt` 仍把这些代码编进一个可执行目标，但语义上已经分成 framework、app core、Win32 host 和 D3D12 host 四层。

## 2. 分层边界

推荐按下面五层理解和修改：

1. `editor/src` / `editor/include/XCEditor`
   XCEditor UI framework。这里应保持通用，不依赖具体项目、场景、Win32 宿主或 D3D12 实现。

2. `editor/app/Composition`、`Features`、`Project`、`Scene`、`State`、`Commands`
   Editor app core。这里装配 panel、项目运行时、场景运行时、选择状态、命令路由和 shell frame。

3. `editor/app/Windowing`
   Editor host seam。这里放平台无关的窗口内容 contract、workspace/utility content assembly、frame orchestration 和 host-facing transfer request。

4. `editor/app/Platform/Win32`
   Win32 host。这里负责原生窗口、消息分发、窗口生命周期、输入收集、title bar / chrome 和 surface/presenter。

5. `editor/app/Rendering`
   Editor rendering host。这里负责 D3D12 UI 渲染、窗口 swapchain、viewport 离屏资源、editor 图标纹理和 scene viewport pass。

依赖方向尽量保持：

```text
app/platform + app/rendering -> app/windowing -> app/core -> XCEditor framework -> engine UI primitives
```

不要让 `editor/src` 反向依赖 `editor/app`。

### 2.1 长期目标：把语义分层落成真实模块边界

当前 `editor/` 已经有语义上的四层划分，但还没有真正的编译/依赖边界。窗口相关代码最重要的长期目标，不是继续细拆 `Win32` 目录里的类，而是把下面这条关系变成代码和构建系统都能强制执行的事实：

```text
XCEditor framework
  <- editor app core
  <- editor host seam / app/Windowing
  <- Win32 host + D3D12 host
```

收敛要求：

- `editor/app/Platform/Win32` 只负责 native window、message pump、input translation、chrome、lifecycle 和 surface/presenter 等宿主职责。
- workspace mutation、utility window routing、shell composition、window content assembly 这类产品语义应逐步收敛到平台无关层，而不是继续堆进 Win32 host。
- `editor/src` / `editor/include/XCEditor` 不允许反向依赖 `editor/app`；公开头文件不应暴露 `App::*` 类型。
- 最终要通过独立 CMake target 和受限 include dirs 落实，而不是只靠目录约定。

后续凡是修改窗口系统，优先朝“缩小 `Platform/Win32` 对 `Composition`、`Features`、`UtilityWindows`、`Rendering` 的直接依赖面”这个方向收敛。如果一个新需求只能通过继续把业务语义塞进 Win32 host 才能完成，应先停下来评估是否缺少平台无关的 host seam。

## 3. 顶层启动流程

入口：

```text
app/main.cpp
  -> RunXCUIEditorApp
  -> Application::Run
```

核心对象关系：

```text
Application
  -> EditorContext
  -> EditorWindowManager
      -> EditorWindow
          -> EditorWindowRuntimeController
              -> D3D12WindowRenderer
              -> D3D12UiRenderer
              -> D3D12WindowRenderLoop
              -> EditorWindowContentController
                  -> EditorWorkspaceWindowContentController
                  -> EditorUtilityWindowContentController
```

`EditorContext` 是全局共享应用状态。每个 workspace window 持有自己的 `UIEditorWorkspaceController` 和 `EditorShellRuntime`。utility window 不持有 workspace controller。

## 4. 显式窗口架构

当前窗口系统已经显式区分两类窗口：

- `EditorWindowCategory::Workspace`
  主窗口和由 dock tab / panel 拖出的独立窗口。
- `EditorWindowCategory::Utility`
  颜色选择器、Add Component 这类天然工具窗。

两类窗口共享同一个 native host：

```text
EditorWindow
  -> EditorWindowRuntimeController
  -> D3D12WindowRenderLoop
  -> EditorWindowContentController
```

差异放在 content controller 和 policy 上，而不是靠“有没有 workspace binding”隐式推断。

### 4.1 Workspace Window

workspace window 的内容控制器是 `EditorWorkspaceWindowContentController`，内部持有：

- `UIEditorWorkspaceController`
- `EditorShellRuntime`
- `EditorWindowFrameOrchestrator`

这类窗口是完整 shell/workspace 容器。主窗口和 detached workspace window 都属于这一类。

### 4.2 Utility Window

utility window 的内容控制器是 `EditorUtilityWindowContentController`，内部持有：

- `EditorUtilityWindowPanel`

当前 utility 窗口通过 registry/factory 创建，已实现显式 descriptor：

- `EditorUtilityWindowDescriptor`
- `EditorUtilityWindowReusePolicy`
- `EditorWindowChromePolicy`
- `EditorWindowNativeStylePolicy`

当前 `ColorPicker` 和 `AddComponent` 都是单例复用窗口。

## 5. 窗口能力与策略

窗口内容能力由 `EditorWindowContentCapabilities` 描述。创建窗口时，host 会校验：

- `Workspace` 分类必须对应具备 workspace capability 的 content controller。
- `Utility` 分类必须对应具备 utility capability 的 content controller。

这一步是硬校验，不再依赖后续 coordinator 通过空 binding 兜底。

窗口外观/宿主策略当前最少包括：

- `EditorWindowChromePolicy`
  当前用于控制 detached title bar tab strip、frame stats，以及 utility window 的 topmost pin 按钮/默认置顶策略。
- `EditorWindowNativeStylePolicy`
  当前用于控制扩展窗口样式和是否复用 host 默认 style。

当前默认规则：

- workspace window 允许 detached title bar tab strip。
- utility window 不允许 detached title bar tab strip。
- utility window 不显示 frame stats。
- utility window 顶栏显示 topmost pin 按钮，且默认置顶。
- utility window 使用 `WS_EX_TOOLWINDOW`。

## 6. Workspace / Utility 协调器边界

### 6.1 Workspace Coordinator

`EditorWindowWorkspaceCoordinator` 只处理 `Workspace` 窗口：

- 维护 window workspace set
- 处理 detach panel
- 处理 global tab drag
- 处理 cross-window dock/drop
- 更新 detached workspace title

utility window 不参与：

- workspace set
- dock target hit test
- cross-window drop target

### 6.2 Utility Coordinator

`EditorUtilityWindowCoordinator` 只处理 utility window 请求：

- 根据 `EditorUtilityWindowDescriptor` 创建工具窗
- 按 reuse policy 决定复用还是新建
- 对现有 utility window 做 focus / restore

不要把 utility window 塞进 workspace mutation 流程。

## 7. Frame Request 结构

`EditorWindowFrameTransferRequests` 已拆成两个子域：

```text
workspace:
  beginGlobalTabDrag
  detachPanel

utility:
  openUtilityWindow
```

规则：

- `EditorWindowWorkspaceCoordinator` 只消费 `transferRequests.workspace`
- `EditorUtilityWindowCoordinator` 只消费 `transferRequests.utility`
- queued immediate frame 也按两个子域分别合并

不要再把 workspace 和 utility 的窗口请求混进同一个平铺字段集合。

## 8. 每帧流程

当前每帧主路径：

```text
Application::Run
  -> EditorWindowManager::RenderAllWindows
      -> EditorWindowRuntimeController::BeginFrame
      -> EditorWindowRuntimeController::UpdateAndAppend
          -> EditorWindowFrameOrchestrator::UpdateAndAppend
              -> EditorShellRuntime::Update
                  -> EditorShellSessionCoordinator::PrepareShellDefinition
                  -> EditorShellInteractionEngine::Update
                      -> UpdateUIEditorShellInteraction
                      -> ViewportHostService::RequestViewport
                  -> EditorShellSessionCoordinator::FinalizeFrame
                  -> EditorShellHostedPanelCoordinator::Update
              -> EditorShellRuntime::Append
      -> EditorWindowRuntimeController::RenderRequestedViewports
      -> EditorWindowRuntimeController::Present
```

重要约束：

- viewport 先在 shell layout 阶段通过 `RequestViewport()` 申明尺寸和纹理需求。
- 再在 `RenderRequestedViewports()` 阶段真正渲染。
- 不要打乱这两个阶段的顺序。

## 9. 修改规范

- 先判断改动属于 framework、app core、windowing seam、Win32 host 还是 rendering host。
- 小改动优先贴近现有模式，不顺手做跨层重构。
- 新增通用 widget 放 `editor/src` / `editor/include/XCEditor`。
- 新增具体 editor 功能放 `editor/app/Features/<FeatureName>`，再由 composition 装配。
- 新增 host-facing window content、frame request、content assembly 放 `editor/app/Windowing`。
- 新增 Win32 宿主行为放 `editor/app/Platform/Win32`，通过 seam/controller/policy 与 app core 通信。
- 新增 viewport 渲染资源或 pass 放 `editor/app/Rendering/Viewport` 或 `editor/resources/shaders/scene-viewport`。
- draw append 只负责绘制，不修改 editor runtime 或 scene/project state。
- D3D12 host、Win32 host、panel 之间避免双向强耦合。

## 10. 当前架构债务

这轮重构完成后，仍有以下债务：

- `editor/CMakeLists.txt` 还没有把 framework、app core、windowing seam、Win32 host、D3D12 host 拆成独立 target。
- `EditorContext` 仍然过重，混合了全局状态、service locator、command bridge、session sync 和状态输出。
- `EditorShellRuntime` 仍然过重，既持有 panel，又持有 viewport host、shell frame、draw composer 和 interaction coordinator。
- panel 仍缺少统一 feature 接口，`HierarchyPanel`、`ProjectPanel`、`InspectorPanel` 只是模式相似。
- `app/Windowing` 目前只是首刀 ownership 调整，workspace / utility window orchestration 仍主要停留在 Win32 coordinator。

这些债务后续要分步处理，不要一次性重写整个窗口系统。

## 11. 验证基线

当前这轮窗口架构重构的验证状态：

- 用户已完成 GUI 行为验证。
- `cmake --build build --config Debug --target XCUIEditorApp` 已通过。
- `build/editor/Debug/XCEngine.exe` 的 12 秒启动冒烟测试已通过，进程可正常响应关闭请求。

后续涉及窗口架构的改动，至少应维持这条验证基线。

## 12. 推荐阅读入口

开始 editor 相关任务时，优先阅读：

- `editor/CMakeLists.txt`
- `editor/app/Bootstrap/Application.*`
- `editor/app/Composition/EditorContext.*`
- `editor/app/Composition/EditorShellRuntime.*`
- `editor/app/Windowing/Content/EditorWindowContentController.h`
- `editor/app/Windowing/Frame/EditorWindowFrameOrchestrator.*`
- `editor/app/Platform/Win32/Windowing/EditorWindow.*`
- `editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.*`
- `editor/app/Platform/Win32/Windowing/EditorUtilityWindowCoordinator.*`
- `editor/app/UtilityWindows/EditorUtilityWindowRegistry.*`
- `editor/include/XCEditor/Workspace/UIEditorWorkspaceController.h`
- `editor/include/XCEditor/Shell/UIEditorShellInteraction.h`