docs: sync api and planning docs

docs/plan/Editor架构说明.md

@@ -6,15 +6,19 @@
 
 - 把视觉样式、交互路由、编辑命令、dock 布局、面板壳层拆开。
 - 把 `Hierarchy / Project / Inspector / Console / MenuBar` 统一到同一套 shared UI 和 action 语义上。
-- 保持 `Scene / Game` 先作为空壳 panel，等待后续 `Viewport / RHI` 回归。
+- 把 `Scene / Game` viewport 保持在当前真实主链上：`ViewportHostService -> Rendering + RHI -> ImGui panel`。
+- 把 `Assets + .meta + Library` 项目工作流、脚本程序集构建与运行时状态纳入 editor 正式分层，而不是继续当外围脚本。
 
-这意味着当前 editor 的重点是“编辑器外壳架构完整”，不是“运行时视口功能完整”。
+这意味着当前 editor 的重点已经不是“先把外壳搭出来”，而是：
+
+- 在现有外壳分层上继续收口真实可运行的 viewport / project / scripting 主链。
+- 让 panel、viewport helper、commands、managers 和引擎侧 `Rendering / Resources / Scene / Scripting` 的边界继续清晰化。
 
 ## 2. 总体分层
 
 当前 editor 推荐按下面的依赖方向理解：
 
-`Application -> EditorLayer -> EditorWorkspace -> Panels -> Actions -> Commands -> Managers/Core`
+`Application -> EditorLayer -> EditorWorkspace -> Panels/Viewport -> Actions -> Commands -> Managers/Core`
 
 同时还有一条横向的共享 UI 层：
 
@@ -24,6 +28,10 @@
 
 `InspectorPanel -> ComponentEditorRegistry -> IComponentEditor`
 
+以及一条已经落地的 editor 到引擎主链：
+
+`Viewport / Managers / Scripting -> Rendering / Resources / Scene / Scripting / RHI`
+
 允许依赖的基本原则：
 
 - `UI` 只负责样式 token、共享控件、popup/property-grid 等表现层能力，不承担业务语义。
@@ -32,6 +40,7 @@
 - `Panels` 只保留最小的渲染壳层和少量局部瞬时状态，不直接堆业务逻辑。
 - `Layout` 只负责 dockspace 和布局持久化，不处理 scene/project 业务。
 - `Core/Managers` 提供 editor 运行时共享状态与数据入口。
+- `Viewport` 是 editor 宿主和引擎渲染主链之间的正式桥接层，不是 panel 内随手拼的辅助代码。
 
 不允许继续扩散的方向：
 
@@ -272,6 +281,60 @@
 3. 在 `ComponentEditorRegistry.cpp` 注册。
 4. 如果涉及复杂交互，优先复用 `UI::PropertyGrid` 和 undo interactive change 机制。
 
+### 3.10 Viewport
+
+关键文件：
+
+- `editor/src/Viewport/ViewportHostService.h`
+- `editor/src/Viewport/IViewportHostService.h`
+- `editor/src/Viewport/SceneViewportChrome.h`
+- `editor/src/Viewport/SceneViewportInteractionFrame.h`
+- `editor/src/Viewport/SceneViewportNavigation.h`
+- `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h`
+- `editor/src/Viewport/SceneViewportOverlayBuilder.h`
+- `editor/src/Viewport/SceneViewportOverlayFrameCache.h`
+- `editor/src/Viewport/SceneViewportOverlaySpriteResources.h`
+- `editor/src/Viewport/SceneViewportResourcePaths.h`
+- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h`
+
+职责：
+
+- 作为 editor 宿主与引擎 `Rendering + RHI` 的桥接层，维护 Scene / Game viewport 的离屏渲染接线。
+- 维护当前 Scene View helper 主链：
+  - `SceneViewportChrome`
+  - `SceneViewportInteractionFrame`
+  - `SceneViewportNavigation`
+  - `SceneViewportTransformGizmoCoordinator`
+  - `ViewportHostService`
+- 负责 overlay builder、overlay frame cache、sprite 资源准备、object-id picking、grid、outline 和 gizmo overlay state。
+
+边界：
+
+- `Viewport` 是正式子系统，不再是“等待未来回归”的空位。
+- panel 不应自己拼接一套独立渲染路径；新的 viewport 行为优先落到 helper、host service 或 overlay pass。
+- `SceneViewportShaderPaths.h` 当前主要是兼容 include；资源路径真实 owner 已经转到 `SceneViewportResourcePaths.h`。
+
+### 3.11 Scripting / Project Workflow
+
+关键文件：
+
+- `editor/src/Scripting/EditorScriptAssemblyBuilder.h`
+- `editor/src/Scripting/EditorScriptRuntimeStatus.h`
+- `editor/src/Managers/ProjectManager.h`
+- `editor/src/Managers/SceneManager.h`
+- `editor/src/Utils/ProjectFileUtils.h`
+
+职责：
+
+- 解析项目根目录、读写 `Project.xcproject`，并把仓库内 `project/` 或 `--project <path>` 解析为当前工程。
+- 驱动 `Assets + .meta + Library` 风格项目 workflow，包括项目资源浏览、脚本程序集重建入口和运行时状态反馈。
+- 把项目脚本程序集与 editor/runtime 实际消费的 `Library/ScriptAssemblies/` 目录连接起来。
+
+边界：
+
+- 与项目资产、`.meta`、`Library`、脚本程序集相关的问题，不应再按“editor 仍处于无工程状态”理解。
+- `ProjectManager`、`SceneManager`、`EditorScriptAssemblyBuilder` 与引擎侧 `ResourceManager / AssetImportService / ScriptEngine` 是协作关系，不应在 panel 里各自复制一层状态机。
+
 ## 4. EventBus 使用规则
 
 `EventBus` 现在主要承担两类职责：
@@ -334,16 +397,19 @@
 - dock layout controller 与 editor workspace 装配。
 - inspector 的 component editor registry 接入。
 - editor 级回归测试基础框架与关键命令测试。
+- `Scene / Game` viewport 已经重新接回当前正式主链：引擎 `Rendering + RHI` 离屏输出 -> `ViewportHostService` -> ImGui panel。
+- `Assets + .meta + Library` 项目工作流、`Project.xcproject`、脚本程序集重建与脚本运行时状态已经进入 editor 正式工作流。
+- viewport helper 已按 `Chrome -> InteractionFrame -> Navigation -> TransformGizmoCoordinator -> ViewportHostService` 显式拆层。
 
 当前明确暂缓：
 
-- `Scene` panel 内容。
-- `Game` panel 内容。
-- `Viewport` 与 RHI 重新接入。
+- 把 editor 主线程上残留的同步资源兜底点继续清理到更严格的异步消费模型。
+- 把 `Library bootstrap / scene streaming / explicit import` 的状态模型继续正式化到 UI。
+- 继续减少 panel 内局部瞬时状态与 helper 间重复规则。
 
 原因很明确：
 
-- 这三部分依赖渲染壳层与后续 renderer/RHI 重构，暂时不适合和 editor UI 架构收尾混在一起。
+- 前三项已经不是“没接回来的未来工作”，而是已经落地、但还要继续收口的当前主线。
 
 ## 8. 后续新增功能时的落点原则
 
@@ -355,6 +421,7 @@
 - 新 inspector 组件面板：放 `ComponentEditors`
 - 新 dock/window 布局控制：放 `Layout`
 - 新 editor 全局状态：放 `Core/Managers`
+- 新 viewport host / overlay / interaction helper：放 `Viewport`
 - 只是把已有能力拼进某个窗口：放 `Panels`
 
 如果一个功能不知道放哪，一般先问自己：
@@ -371,8 +438,9 @@
 
 - 继续压缩少量 panel 本地瞬时状态，能下沉的继续下沉。
 - 继续补命令/路由回归测试，尤其是 inspector interactive undo 边界。
-- 为将来的 viewport 回归预留稳定接入口，但暂不提前接入渲染逻辑。
+- 继续补 viewport helper、project workflow、script assembly builder 与 scene streaming 相关回归测试。
+- 把 `Library bootstrap`、显式导入、后台 scene asset streaming 这三类状态在 editor UI 上分开表达。
 
 结论：
 
-editor 当前已经形成稳定分层，后面再做功能迭代时，应坚持“先看边界，再落代码”，不要回到 panel 内部堆逻辑的旧路线。
+editor 当前已经形成稳定分层，而且这套分层已经承接了真实的 viewport / project / scripting 工作流。后面再做功能迭代时，应坚持“先看边界，再落代码”，不要回到 panel 内部堆逻辑的旧路线。