用途：让浏览器 UI 与智能体在磁盘上的文件改动保持实时同步。智能体写文件后，UI 自动更新，无需轮询或手动刷新，是“文件即数据库”模式实现实时感的关键。
主要能力：服务端用 chokidar 递归监听数据目录，通过共享模块创建监听器，并以基于文件的路由暴露 SSE 端点；客户端用 useFileWatcher 监听事件并让 React Query 失效相关缓存。
必要用法：在 server/lib/watcher.ts 中调用 createFileWatcher("./data") 创建监听器；在 server/routes/api/events.get.ts 中用 createSSEHandler(watcher) 暴露端点；客户端调用 useFileWatcher({ queryClient, queryKeys: ["files", "projects"] })。多数据模型时可用 onEvent 回调按路径过滤，只失效相关查询；并给查询设置 staleTime（如 2000）以缓解快速写入导致的缓存抖动。
限制与注意：不要轮询；不要为每个模型单独创建 fs.watch()，一个递归监听器足够；不要自行创建 EventSource，自定义处理应使用 onEvent 回调。智能体快速写入大量文件时可能产生事件风暴与高 CPU，需用 staleTime 和路径过滤缓解。
排障：UI 不更新时检查 queryClient 与 queryKeys 是否匹配；SSE 不触发时在开发者工具 Network 中查看 /api/events 是否连接；监听不到变化时确认路径相对 CWD 是否正确；频繁重连检查服务端是否崩溃。
相关技能：files-as-database、scripts、self-modifying-code。