XCEngine/docs/used/Assets目录Watcher与自动导入刷新计划_完成归档_2026-04-10.md

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 放在后续迭代。