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