Add editor Assets watcher refresh loop

docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md

@@ -0,0 +1,186 @@
+# Assets目录Watcher与自动导入刷新计划
+
+日期: 2026-04-10
+
+## 1. 背景
+
+当前工程的资产导入链路已经具备以下能力：
+
+- 打开项目时执行一次 `BootstrapProject`
+- 手动执行 `Refresh / Reimport / Reimport All`
+- 资源真正加载时通过 `EnsureArtifact` 懒导入
+
+但它还缺少 Unity 风格里最关键的一层：
+
+- `Assets/` 目录发生外部变化时，编辑器能自动感知并刷新资产数据库
+
+这里的“外部变化”包括但不限于：
+
+- 资源文件新增、删除、覆盖
+- `.meta` 文件新增、删除、修改
+- 文件夹新增、删除、重命名
+- DCC 工具重新导出同路径资源
+- `git pull`、脚本生成、资源同步工具写入
+
+所以问题不在“拖进 editor 时是否导入”，而在“是否存在一条持续观察 `Assets` 目录变化并驱动资产系统刷新的通路”。
+
+## 2. 现状判断
+
+从当前代码结构看，这个功能是好加的，难度中等，不是重写级别：
+
+- `ResourceManager` 已经有 `RefreshProjectAssets()`、`ReimportProjectAsset()`、`RebuildProjectAssetCache()`
+- `AssetImportService / AssetDatabase` 已经能扫描项目、维护 Source DB / Artifact DB
+- editor 已经有稳定的每帧更新入口 `EditorWorkspace::Update`
+- `ProjectManager` 已经支持目录树刷新
+
+真正缺的是一个独立的 watcher 层，把“磁盘变化”转成“主线程上的资产刷新动作”。
+
+## 3. 目标
+
+第一阶段目标：
+
+- 编辑器运行时自动感知 `Assets/` 目录外部变化
+- 自动刷新 `AssetDatabase` lookup / metadata 状态
+- 自动刷新 Project 面板当前目录
+- 对批量拷贝和连续覆盖做去抖，不要每个文件都立刻刷新一次
+
+长期目标：
+
+- 接近 Unity 的体验：外部改动几乎无需手动 `Refresh`
+- 为后续更细粒度的增量 reimport、缩略图刷新、场景引用修复提供基础设施
+
+## 4. 非目标
+
+第一阶段不做：
+
+- 原生 Win32 `ReadDirectoryChangesW` 后台线程 watcher
+- 精确到单文件的增量 reimport 调度
+- 已经加载到场景里的资源热替换
+- 资产依赖图级别的自动级联重导
+- 跨平台 watcher 后端抽象
+
+这些放到后续阶段。
+
+## 5. 分阶段方案
+
+### Phase 1: 轮询式 Assets Watcher
+
+实现一个 editor 内部的 `ProjectAssetWatcher`：
+
+- 只监听当前项目的 `Assets/`
+- 通过定时扫描递归快照检测新增/修改/删除
+- 包含普通资源文件、文件夹、`.meta`
+- 通过扫描间隔 + 去抖窗口合并一批变化
+- 在主线程触发：
+  - `ResourceManager::RefreshProjectAssets()`
+  - `ProjectManager::RefreshCurrentFolder()`
+
+优点：
+
+- 实现快，风险低
+- 不引入后台线程和 Win32 句柄生命周期问题
+- 先把“自动感知外部变化”补上
+
+缺点：
+
+- 不是事件驱动，超大项目下效率一般
+- 只能做到“自动刷新资产数据库”，还不是“精确增量重导”
+
+### Phase 2: 原生 Win32 Directory Watcher
+
+把 Phase 1 的扫描后端替换为 Win32 原生目录通知：
+
+- `ReadDirectoryChangesW`
+- 递归监听 `Assets/`
+- 把原始事件推入线程安全队列
+- 主线程消费并做路径标准化、重命名配对、去抖合并
+
+目标：
+
+- 降低大项目轮询成本
+- 提高外部改动响应速度
+
+### Phase 3: 增量 Reimport 调度
+
+在 watcher 已经稳定后，再做更接近 Unity 的行为：
+
+- 对新增/修改的 importable asset 调用增量 reimport
+- 删除时清理 lookup / orphan artifact
+- 重命名时保证 `.meta` / GUID / path snapshot 同步
+- 限制一次批量刷新中的 `UnloadAll()` 影响范围
+
+这个阶段需要重新审视当前 `ResourceManager::ReimportProjectAsset()` 里 `UnloadAll()` 的语义，否则外部频繁改资源会让缓存抖动太大。
+
+## 6. 代码落点
+
+第一阶段建议改动：
+
+- `editor/src/Core/ProjectAssetWatcher.h/.cpp`
+  - watcher 快照、扫描、去抖、变更合并
+- `editor/src/Core/EditorWorkspace.h`
+  - `Attach / Detach / Update` 接入 watcher 生命周期
+- `editor/CMakeLists.txt`
+  - 编译新 watcher 文件
+
+可能的辅助修改：
+
+- 日志输出，方便确认自动刷新是否触发
+- 若后续需要 UI 提示，可再补 editor 事件或状态文本
+
+## 7. 第一阶段执行细则
+
+### 7.1 快照内容
+
+每个 `Assets` 路径记录：
+
+- 规范化相对路径 key
+- 是否目录
+- 文件大小
+- 最后写入时间
+
+目录也要纳入快照，这样能检测外部新建/删除文件夹。
+
+### 7.2 扫描策略
+
+- 默认扫描间隔：`0.75s`
+- 默认去抖窗口：`0.35s`
+- 若扫描发现连续变动，则不断延长本轮刷新触发时间
+- 当一小批变化稳定下来，再统一执行一次刷新
+
+### 7.3 主线程动作
+
+统一执行：
+
+- `ResourceManager::Get().RefreshProjectAssets()`
+- `context.GetProjectManager().RefreshCurrentFolder()`
+
+这一步先只刷新资产数据库和 Project 面板，不直接做逐文件 reimport。
+
+## 8. 风险点
+
+- 递归扫描频率太高会拖慢超大项目
+- 当前 `RefreshProjectAssets()` 不会主动生成所有 artifact，只是同步资产数据库
+- `ProjectManager::RefreshCurrentFolder()` 是整树重建，不是局部刷新
+- editor 内部自己改文件时，watcher 也会看到这些变化，需要接受重复刷新
+
+这些都在第一阶段可控范围内。
+
+## 9. 验收标准
+
+第一阶段完成后，应满足：
+
+- 外部往 `Assets/` 复制一个资源文件，Project 面板自动出现
+- 外部删除 `Assets/` 下资源，Project 面板自动消失
+- 外部覆盖修改已有资源，资产数据库自动刷新
+- 不需要用户手点 `Refresh`
+- 批量复制多个资源时，不会每个文件都触发一次明显卡顿的刷新
+
+## 10. 本次执行范围
+
+本次开始执行 Phase 1：
+
+- 先落地轮询式 watcher
+- 打通 editor 生命周期
+- 先让 `Assets` 外部变更自动刷新
+
+Phase 2 的 Win32 原生 watcher 放在后续迭代。

editor/CMakeLists.txt

@@ -70,6 +70,7 @@ add_executable(${PROJECT_NAME} WIN32
     src/Theme.cpp
     src/Core/UndoManager.cpp
     src/Core/PlaySessionController.cpp
+    src/Core/ProjectAssetWatcher.cpp
     src/ComponentEditors/ComponentEditorRegistry.cpp
     src/Managers/SceneManager.cpp
     src/Managers/ProjectManager.cpp

editor/src/Core/EditorWorkspace.h

@@ -3,6 +3,7 @@
 #include "Commands/SceneCommands.h"
 #include "Core/IEditorContext.h"
 #include "Core/PlaySessionController.h"
+#include "Core/ProjectAssetWatcher.h"
 #include "Layout/DockLayoutController.h"
 #include "panels/ConsolePanel.h"
 #include "panels/GameViewPanel.h"
@@ -39,12 +40,14 @@ public:
         m_projectPanel->Initialize(context.GetProjectPath());
         Commands::LoadStartupScene(context);
         m_playSessionController.Attach(context);
+        m_projectAssetWatcher.Attach(context.GetProjectPath());
         m_dockLayoutController->Attach(context);
         m_panels.AttachAll();
     }
 
     void Detach(IEditorContext& context) {
         m_playSessionController.Detach(context);
+        m_projectAssetWatcher.Detach();
         Commands::SaveDirtySceneWithFallback(context, BuildFallbackScenePath(context));
 
         if (m_dockLayoutController) {
@@ -61,6 +64,7 @@ public:
     void Update(float dt) {
         ::XCEngine::Resources::ResourceManager::Get().UpdateAsyncLoads();
         if (IEditorContext* context = m_panels.GetContext()) {
+            m_projectAssetWatcher.Update(*context, dt);
             m_playSessionController.Update(*context, dt);
         }
         m_panels.UpdateAll(dt);
@@ -96,6 +100,7 @@ private:
     ProjectPanel* m_projectPanel = nullptr;
     std::unique_ptr<DockLayoutController> m_dockLayoutController;
     PlaySessionController m_playSessionController;
+    ProjectAssetWatcher m_projectAssetWatcher;
 };
 
 } // namespace Editor

editor/src/Core/ProjectAssetWatcher.cpp

@@ -0,0 +1,207 @@
+#include "Core/ProjectAssetWatcher.h"
+#include "Core/IProjectManager.h"
+
+#include <XCEngine/Core/Asset/ResourceManager.h>
+#include <XCEngine/Debug/Logger.h>
+
+#include <algorithm>
+#include <cctype>
+#include <system_error>
+
+namespace XCEngine {
+namespace Editor {
+
+namespace fs = std::filesystem;
+
+namespace {
+
+constexpr float kScanIntervalSeconds = 0.75f;
+constexpr float kDebounceWindowSeconds = 0.35f;
+
+std::string NormalizePathKey(const fs::path& path) {
+    std::string key = path.lexically_normal().generic_string();
+    std::transform(key.begin(), key.end(), key.begin(), [](unsigned char ch) {
+        return static_cast<char>(std::tolower(ch));
+    });
+    return key;
+}
+
+std::uint64_t GetFileSizeValue(const fs::path& path, bool isDirectory) {
+    if (isDirectory) {
+        return 0;
+    }
+
+    std::error_code ec;
+    const auto fileSize = fs::file_size(path, ec);
+    return ec ? 0 : static_cast<std::uint64_t>(fileSize);
+}
+
+std::uint64_t GetFileWriteTimeValue(const fs::path& path) {
+    std::error_code ec;
+    const auto writeTime = fs::last_write_time(path, ec);
+    if (ec) {
+        return 0;
+    }
+
+    return static_cast<std::uint64_t>(writeTime.time_since_epoch().count());
+}
+
+} // namespace
+
+void ProjectAssetWatcher::Attach(const std::string& projectPath) {
+    RefreshProjectBinding(projectPath);
+}
+
+void ProjectAssetWatcher::Detach() {
+    m_projectPath.clear();
+    m_assetsRoot.clear();
+    m_snapshot.clear();
+    m_pendingChanges.Clear();
+    m_scanCooldownSeconds = 0.0f;
+    m_debounceSeconds = 0.0f;
+    m_hasPendingRefresh = false;
+}
+
+void ProjectAssetWatcher::Update(IEditorContext& context, float dt) {
+    RefreshProjectBinding(context.GetProjectPath());
+    if (m_assetsRoot.empty()) {
+        return;
+    }
+
+    m_scanCooldownSeconds -= dt;
+    if (m_scanCooldownSeconds <= 0.0f) {
+        ScanForChanges();
+        m_scanCooldownSeconds = kScanIntervalSeconds;
+    }
+
+    if (!m_hasPendingRefresh) {
+        return;
+    }
+
+    m_debounceSeconds -= dt;
+    if (m_debounceSeconds <= 0.0f) {
+        FlushPendingRefresh(context);
+    }
+}
+
+void ProjectAssetWatcher::RefreshProjectBinding(const std::string& projectPath) {
+    if (projectPath == m_projectPath) {
+        return;
+    }
+
+    m_projectPath = projectPath;
+    m_assetsRoot = projectPath.empty() ? fs::path() : (fs::path(projectPath) / "Assets");
+    m_snapshot.clear();
+    m_pendingChanges.Clear();
+    m_scanCooldownSeconds = kScanIntervalSeconds;
+    m_debounceSeconds = 0.0f;
+    m_hasPendingRefresh = false;
+
+    if (!m_assetsRoot.empty()) {
+        BuildSnapshot(m_assetsRoot, m_snapshot);
+    }
+}
+
+void ProjectAssetWatcher::ScanForChanges() {
+    Snapshot currentSnapshot;
+    BuildSnapshot(m_assetsRoot, currentSnapshot);
+
+    const ChangeStats changes = DiffSnapshots(m_snapshot, currentSnapshot);
+    m_snapshot = std::move(currentSnapshot);
+    if (!changes.HasChanges()) {
+        return;
+    }
+
+    m_pendingChanges.Accumulate(changes);
+    m_hasPendingRefresh = true;
+    m_debounceSeconds = kDebounceWindowSeconds;
+}
+
+void ProjectAssetWatcher::FlushPendingRefresh(IEditorContext& context) {
+    if (!m_hasPendingRefresh) {
+        return;
+    }
+
+    Resources::ResourceManager::Get().RefreshProjectAssets();
+    context.GetProjectManager().RefreshCurrentFolder();
+
+    Debug::Logger::Get().Info(
+        Debug::LogCategory::FileSystem,
+        (std::string("[ProjectAssetWatcher] Refreshed project assets after external changes. added=") +
+         std::to_string(m_pendingChanges.added) +
+         " modified=" +
+         std::to_string(m_pendingChanges.modified) +
+         " removed=" +
+         std::to_string(m_pendingChanges.removed)).c_str());
+
+    m_pendingChanges.Clear();
+    m_debounceSeconds = 0.0f;
+    m_hasPendingRefresh = false;
+}
+
+void ProjectAssetWatcher::BuildSnapshot(const fs::path& assetsRoot, Snapshot& outSnapshot) {
+    outSnapshot.clear();
+
+    std::error_code ec;
+    if (assetsRoot.empty() || !fs::exists(assetsRoot, ec)) {
+        return;
+    }
+
+    for (fs::recursive_directory_iterator it(
+             assetsRoot,
+             fs::directory_options::skip_permission_denied,
+             ec),
+         end;
+         !ec && it != end;
+         it.increment(ec)) {
+        const fs::path entryPath = it->path();
+
+        std::error_code relativeEc;
+        const fs::path relativePath = fs::relative(entryPath, assetsRoot, relativeEc);
+        if (relativeEc || relativePath.empty()) {
+            continue;
+        }
+
+        std::error_code typeEc;
+        const bool isDirectory = it->is_directory(typeEc);
+        if (typeEc) {
+            continue;
+        }
+
+        AssetEntryState entryState;
+        entryState.isDirectory = isDirectory;
+        entryState.fileSize = GetFileSizeValue(entryPath, isDirectory);
+        entryState.writeTime = GetFileWriteTimeValue(entryPath);
+        outSnapshot.emplace(NormalizePathKey(relativePath), entryState);
+    }
+}
+
+ProjectAssetWatcher::ChangeStats ProjectAssetWatcher::DiffSnapshots(
+    const Snapshot& previousSnapshot,
+    const Snapshot& currentSnapshot) {
+    ChangeStats changes;
+
+    for (const auto& [pathKey, currentState] : currentSnapshot) {
+        const auto previousIt = previousSnapshot.find(pathKey);
+        if (previousIt == previousSnapshot.end()) {
+            ++changes.added;
+            continue;
+        }
+
+        if (!(previousIt->second == currentState)) {
+            ++changes.modified;
+        }
+    }
+
+    for (const auto& [pathKey, previousState] : previousSnapshot) {
+        (void)previousState;
+        if (currentSnapshot.find(pathKey) == currentSnapshot.end()) {
+            ++changes.removed;
+        }
+    }
+
+    return changes;
+}
+
+} // namespace Editor
+} // namespace XCEngine

editor/src/Core/ProjectAssetWatcher.h

@@ -0,0 +1,72 @@
+#pragma once
+
+#include "Core/IEditorContext.h"
+
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <unordered_map>
+
+namespace XCEngine {
+namespace Editor {
+
+class ProjectAssetWatcher {
+public:
+    void Attach(const std::string& projectPath);
+    void Detach();
+    void Update(IEditorContext& context, float dt);
+
+private:
+    struct AssetEntryState {
+        bool isDirectory = false;
+        std::uint64_t fileSize = 0;
+        std::uint64_t writeTime = 0;
+
+        bool operator==(const AssetEntryState& other) const {
+            return isDirectory == other.isDirectory &&
+                   fileSize == other.fileSize &&
+                   writeTime == other.writeTime;
+        }
+    };
+
+    struct ChangeStats {
+        std::uint32_t added = 0;
+        std::uint32_t modified = 0;
+        std::uint32_t removed = 0;
+
+        bool HasChanges() const {
+            return added > 0 || modified > 0 || removed > 0;
+        }
+
+        void Clear() {
+            added = 0;
+            modified = 0;
+            removed = 0;
+        }
+
+        void Accumulate(const ChangeStats& other) {
+            added += other.added;
+            modified += other.modified;
+            removed += other.removed;
+        }
+    };
+
+    using Snapshot = std::unordered_map<std::string, AssetEntryState>;
+
+    void RefreshProjectBinding(const std::string& projectPath);
+    void ScanForChanges();
+    void FlushPendingRefresh(IEditorContext& context);
+    static void BuildSnapshot(const std::filesystem::path& assetsRoot, Snapshot& outSnapshot);
+    static ChangeStats DiffSnapshots(const Snapshot& previousSnapshot, const Snapshot& currentSnapshot);
+
+    std::string m_projectPath;
+    std::filesystem::path m_assetsRoot;
+    Snapshot m_snapshot;
+    ChangeStats m_pendingChanges;
+    float m_scanCooldownSeconds = 0.0f;
+    float m_debounceSeconds = 0.0f;
+    bool m_hasPendingRefresh = false;
+};
+
+} // namespace Editor
+} // namespace XCEngine