Add editor Assets watcher refresh loop
This commit is contained in:
186
docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md
Normal file
186
docs/plan/Assets目录Watcher与自动导入刷新计划_2026-04-10.md
Normal file
@@ -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 放在后续迭代。
|
||||
Reference in New Issue
Block a user