mnote/design/03-rust-web/done/3-26-local-folder-filechange-service-v1.md

3-26 Local Folder FileChangeService 统一文件变化事件层 v1

创建时间：2026-06-29 状态：done Owner：03-rust-web 主控，协同 05-editor-mainline、07-ai 来源：当前 Page AI / OpenHub / opencode 写入本地 .md 后，左侧当前文档页不会自动更新，整页刷新后才读取到新内容。 参考：reference-code/sidex-main 的 watcher / EventThrottler / reaction 模型；reference-code/vscode 的 FileService.onDidFilesChange、Explorer 延迟刷新、TextFile editor reload/focus 补偿模型。

1. 结论

不要新增 OpenHub / opencode 专属“写完刷新当前页”链路，也不要完整重建 VSCode FileService。

本轮应把 MNote 现有 local-folder watcher / browser event bus 收口成一个轻量 FileChangeService：

• Rust watcher、OpenHub/opencode changedFiles、legacy Page AI tool receipt、MNote 自身保存回声都只能作为统一文件变化事件的输入源。
• 当前文档、filetree、page tree、knowledge source status 只消费统一 FileChange reaction，不直接解析 provider 事件。
• 当前打开文档只有在非 dirty / 非 saving / 非 recent input 时自动拉取最新 Page Aggregate；dirty 时进入外部冲突状态，不覆盖编辑器内容。
• filetree/page tree 继续走现有 projection / watch_batch / sidebar refresh 链路，但由统一事件层负责去抖、合并、self-write 抑制和最小刷新范围。

2. 背景与现状

当前已经存在文件变化监控链路，不应另起一套：

1. rust/crates/mnote-web/src/local_folder_watcher_registry.rs

   • 使用 notify 监听 local folder root。
   • 生成 relativePath、documentId、eventKind、revision、observedFileVersion、bufferFileVersion、selfWriteEcho。
   • 调用 BufferStore.mark_external_modified_if_version_changed_with_outcome 区分自写回声与外部修改。
   • 同步触发本地搜索索引刷新；该职责保持在 Rust 侧，不迁到浏览器 runtime。

2. rust/crates/mnote-web/src/routes/local_folder_events.rs

   • /api/local-folder/events?treeLive=true 复用同一个 watcher。
   • 聚合 watcher payload，输出 watch_batch。

3. rust/crates/mnote-web/browser/local-folder-event-bus-runtime.js

   • 复用单连接，转发 watch_batch。
   • 派发 mnote:local-folder:watch-batch、tree:local-folder-watch-batch、mnote:local-folder:filetree-parent-changed、mnote:local-folder:document-changed、mnote:local-folder:resource-changed、mnote:local-folder:sidebar-refresh-requested。

4. rust/crates/mnote-web/browser/document-session-runtime.js

   • 消费 mnote:local-folder:document-changed。
   • 命中当前 document session 后调用 refreshSessionFromExternalChange，再 fetch /api/page-aggregate/...。

问题说明：整页刷新后能看到 agent 写入内容，说明 Page Aggregate 读盘链路有效；当前缺口在“真实文件变化 / agent 写入结果 -> 当前打开 document session reaction”。

3. 参考实现判断

3.1 Sidex 可移植部分

从 reference-code/sidex-main 可迁移的是模型，不是完整代码：

• crates/sidex-workspace/src/watcher.rs

  • notify 事件包装。
  • path 级别 pending map 去重。
  • ignore pattern。

• crates/sidex-workspace/src/file_watcher_events.rs

  • EventThrottler.record_own_write(path) 抑制自身写入回声。
  • ingest() 合并短时间多事件。
  • flush() 把文件事件映射成 reaction。
  • dirty 文件 + external modified 进入冲突 reaction。

• src/vs/workbench/contrib/files/browser/explorerService.ts

  • Explorer 用延迟合并处理文件事件。
  • 编辑中不刷新树。
  • 只在展开父节点受影响时刷新。

3.2 Sidex 复核补充

Sidex 的关键收益不是更换 watcher，而是在 watcher 与消费者之间增加稳定事件质量层：

能力	Sidex 模型	MNote 当前状态	本设计处理
两段去重	watcher pending map + EventThrottler	只有 local_folder_events.rs 的 120ms 连续 payload 聚合	增加 per-root FileChange throttler，跨批次合并同一路径
own-write 处理	record_own_write + 过期窗口	Rust 已产出 selfWriteEcho，但 browser consumer 仍要各自判断	统一 reaction 层消费 selfWriteEcho，避免各消费方重复判断
Reaction	FileWatcherReaction	前端各 runtime 自己解析 JSON	增加统一 reaction schema，再兼容输出旧事件
dirty 冲突	throttler/working copy 层决定 reload 或 conflict	BufferStore 有版本仲裁，前端也有 conflict panel 壳	reaction 层统一把 dirty/saving/recent input 转成冲突
ignore	watcher 层忽略构建产物	主要覆盖 .mnote / 索引相关路径	后续补 .git、node_modules、target 等

3.3 不直接移植部分

• 不迁 Tauri app.emit("watch-batch")，MNote 使用 Rust Web SSE/WS/browser event bus。
• 不迁 VSCode extension host FileSystemWatcher。
• 不让 watcher 携带文件内容；MNote 正文读取仍走 Page Aggregate。
• 不把 Sidex 的 settings/extensions reload 规则原样迁入；MNote 后续可补自己的偏好、插件、knowledge source reaction。
• 不新增第二条 broadcast/event stream。统一层必须复用现有 /api/local-folder/events 与 browser event bus。

4. 目标架构

4.1 事件输入

统一输入源：

来源	入口	说明
Rust local-folder watcher	/api/local-folder/events?treeLive=true	主来源，真实磁盘文件变化
MNote 编辑器保存	BufferStore / existing save completion event	用于 self-write echo 抑制和保存态同步
OpenHub / opencode	changedFiles adapter	只能转成 FileChange input，不直接刷新 UI
legacy Page AI tool receipt	agentRunReceipt.changedFiles	只能转成 FileChange input
local upload / resource save	existing local-upload event	资源 tab 与附件场景

4.2 标准事件

统一标准事件命名为 mnote.file_change.v1：

{
  "schema": "mnote.file_change.v1",
  "rootUri": "file:///...",
  "workspaceId": "local-ws:...",
  "relativePath": "新页面145827/新页面145827.md",
  "documentId": "local-md:...",
  "resourceKind": "markdown",
  "changeType": "modified",
  "fileVersion": "local-md:...",
  "source": "watcher|editor_save|openhub|opencode|agent_receipt|local_upload",
  "selfWriteEcho": false,
  "observedFileVersion": "...",
  "bufferFileVersion": "...",
  "createdAt": 1782738295000
}

批量事件命名为 mnote.file_change_batch.v1：

{
  "schema": "mnote.file_change_batch.v1",
  "rootUri": "file:///...",
  "workspaceId": "local-ws:...",
  "source": "watcher",
  "changes": [],
  "affectedParents": [],
  "revision": "..."
}

4.3 Reaction

统一 reaction 命名为 mnote.file_change_reaction.v1：

Reaction	触发条件	消费方
refresh_current_document	当前打开文档 clean 且命中 changed .md	document-session-runtime.js
external_conflict_current_document	当前打开文档 dirty/saving/recent input 且同文件外部变化	document-conflict-panel-runtime.js / session status
refresh_filetree_parents	创建/删除/重命名/父目录变化	sidebar-tree-live-apply-runtime.js / filetree
refresh_page_tree_projection	.md 页面新增/删除/重命名	sidebar page tree
refresh_resource_tab	当前资源文件变化	document-resource-tab-runtime.js
refresh_knowledge_source_status	knowledge source 文件变化	knowledge RAG status
ignore_self_write_echo	selfWriteEcho=true 且 session 已处于 saved/clean	不触发 UI 刷新

4.4 Browser 侧 owner

当前最小实现放在 rust/crates/mnote-web/browser/local-folder-event-bus-runtime.js，作为现有 event bus 的升级，不新增并行 runtime。

后续如果文件变大，再拆为：

• filechange-event-runtime.js：标准化、去抖、source adapter、diagnostics。
• filechange-reaction-runtime.js：reaction 计算。
• local-folder-event-bus-runtime.js：只负责 transport 与连接复用。

Rust 侧后续可增加类型化结构，但不要求首批大改广播签名：

• Phase A 保持 SSE JSON 兼容，补齐字段透传与 browser 标准化。
• Phase B/C 再评估是否在 mnote-web/src/file_change_service.rs 引入 FileChangeEvent / FileChangeReaction Rust 类型，并由现有 Value 序列化出口兼容输出。
• throttler 必须是 per-root 实例，放在 LocalFolderWatchChannel 或等价 root-scoped state 中，避免不同 workspace 互相去重。

5. 核心流程

5.1 外部编辑器 / agent 直接写 .md

1. 文件系统变化进入 Rust watcher。
2. watcher 更新 BufferStore 并生成标准字段。
3. /api/local-folder/events?treeLive=true 输出 watch_batch。
4. browser event bus 标准化为 mnote.file_change_batch.v1。
5. reaction 层判断命中当前 document session。
6. 当前文档 clean：调用 refreshSessionFromExternalChange 拉 Page Aggregate 并派发 tiptap 内容。
7. 当前文档 dirty：设置 external-change-conflict，不覆盖内容。

5.2 OpenHub / opencode 写当前页面

1. provider 事件或 session changedFiles 进入 adapter。
2. adapter 将绝对路径解析为当前 rootUri 下 relativePath。
3. 生成 mnote.file_change_batch.v1，source 为 openhub 或 opencode。
4. 后续与 watcher 事件走同一 reaction。
5. 如果真实 watcher 随后也到达，同一路径同版本事件被去抖合并，不重复刷新。

5.3 MNote 自己保存

1. 保存链记录 write intent / save operation / fileVersion。
2. watcher 回声到达时带出 selfWriteEcho=true。
3. FileChangeService 产出 ignore_self_write_echo 或只同步 clean metadata，不触发外部冲突。

6. 非目标

• 不引入周期轮询或 setInterval 检测文件是否变化。
• 不把 OpenHub/opencode changedFiles 当作事实源；它只是 watcher 补偿输入。
• 不让前端直接读取本地文件正文；正文仍走 Page Aggregate。
• 不复活 BlockNote / Convex / Next 作为当前刷新主链。
• 不把 filetree/page tree 的 projection 真相搬到前端。
• 不在 AI runtime 中直接调用 document editor 私有刷新逻辑。

7. 实施 Checklist

Batch A：现状断点复核

• 复核 LocalFolderWatcherRegistry 产出的 selfWriteEcho、observedFileVersion、bufferFileVersion 是否完整进入 watch_batch.changedPaths[]。
• 复核 /api/local-folder/events?treeLive=true 是否对当前 workspace root 只有一个 watcher 连接。
• 复核 local-folder-event-bus-runtime.js 是否把 documentId/eventKind/selfWriteEcho/fileVersion 保留给 document-session-runtime.js。
• 复核 document-session-runtime.js 的命中条件：documentId、relativePath、rootUri、workspaceId。
• 复核当前截图场景中 Page AI/OpenHub 写入后是否有真实 watcher 事件、synthetic event、或两者都没有。
• 复核是否存在跨批次重复事件导致同一路径多次 refresh。
• 复核 ignore 规则是否放过 .git、node_modules、target、dist 等高频目录。

验收：

• 产出一份断点日志或 smoke 证据，能指出“事件未到达 / 字段丢失 / session 未命中 / dirty 拦截 / refresh 失败”的具体层级。

Batch B：标准 FileChange batch

• 在 browser event bus 增加标准化函数：从 watcher watch_batch、synthetic changedFiles、legacy receipt 转成 mnote.file_change_batch.v1。
• 统一绝对路径到 root-relative path 的解析规则，路径不在 rootUri 下时丢弃并记录 diagnostics。
• 合并同一 rootUri + relativePath 的短时间重复事件。
• 保留 source、eventKind、selfWriteEcho、observedFileVersion、bufferFileVersion。
• 暴露 diagnostics：最近 batch source、changed count、dropped count、last reaction。
• 保持旧 watch_batch.changedPaths/affectedParents/eventKinds 字段兼容，新增标准 batch 不破坏旧消费者。
• 如 Rust 侧改类型，保证最终 SSE/JS JSON 格式仍兼容旧 smoke。

验收：

• task540-local-folder-event-bus-single-connection-smoke.js 仍通过。
• 新增静态 smoke 确认 mnote.file_change_batch.v1、selfWriteEcho、emitSyntheticWatchBatch adapter 存在。

Batch C：Reaction 分发

• 新增 reaction 计算：当前文档 clean -> refresh_current_document。
• dirty/saving/recent input -> external_conflict_current_document。
• self-write echo -> ignore_self_write_echo。
• filetree affected parents -> refresh_filetree_parents。
• resource tab -> refresh_resource_tab。
• 保持旧事件兼容输出：tree:local-folder-watch-batch、mnote:local-folder:document-changed、mnote:local-folder:resource-changed。
• 不在 Rust watcher 回调中做新的重 I/O；reaction 计算应基于已有事件字段和 session state。

验收：

• 外部写当前 .md 后，当前 tiptap 页面无需浏览器刷新显示新文本。
• 当前页面 dirty 时，外部写同一 .md 不覆盖编辑器，显示 external conflict。
• filetree/page tree 仍按局部 parent 刷新，不整页 reload。

Batch D：AI source adapter 收口

• OpenHub/opencode changedFiles 只调用统一 FileChange input，不直接调用 refreshPrimaryDocument。
• legacy Page AI receipt 只调用统一 FileChange input。
• 移除或降级旧的 provider 专属直接刷新路径；保留兼容时必须标注为 fallback diagnostics。
• changedFiles 为空时不伪造 diff；只依赖真实 watcher 或 explicit changedFiles。

验收：

• agent/OpenHub/opencode 写当前 .md 后，当前页面自动更新。
• 若 provider 不报 changedFiles，真实 watcher 仍能驱动更新。
• 若 watcher 漏报但 provider 报 changedFiles，synthetic FileChange 可驱动同一 reaction。

Batch E：回归与归档

• 新增或更新 smoke：
  • task-local-folder-filechange-current-document-refresh-smoke.js
  • task-page-ai-filechange-current-document-refresh-smoke.js
  • task-local-folder-filechange-dirty-conflict-smoke.js
• 运行 cargo test -p mnote-web 中相关单测。
• 运行 local-folder event bus、filetree lazy loading、page aggregate refresh 相关 smoke。
• codegraph sync . 并确认状态。
• 完成后把本设计从 process/ 移到 done/，记录验证命令和剩余风险。

8. 风险与防线

• 事件重复：watcher 与 synthetic changedFiles 同时到达。防线：按 rootUri + relativePath + fileVersion/source window 去抖。
• 自写回声误判外部冲突。防线：保留并消费 selfWriteEcho、write intent、save operation。
• dirty 编辑器被覆盖。防线：dirty/saving/recent input 一律进入 conflict reaction。
• filetree/page tree 首屏被 debug/diagnostics 挤占。防线：diagnostics 只写 DOM data attribute 或折叠开发态。
• provider 事件格式不稳定。防线：OpenHub/opencode 只做 adapter，不作为系统事实源。
• 前端拼第二份页面真相。防线：正文刷新只拉 Page Aggregate，不从 changedFiles 读取内容。
• 第二条事件总线造成状态分裂。防线：只复用现有 /api/local-folder/events 与 browser event bus，不新增并行 broadcast。
• throttler 误合并不同 workspace 事件。防线：per-root/per-workspace scoped state。

9. 验收定义

本设计完成的最低验收：

1. 真实外部写当前 .md，当前页面自动刷新正文。
2. OpenHub/opencode/agent 写当前 .md，当前页面自动刷新正文。
3. dirty 当前页遇到外部写入时不覆盖，显示冲突状态。
4. 文件树/页面树仍使用同一 event bus 更新，没有新增并行轮询。
5. OpenHub/opencode 没有直接持有编辑器刷新逻辑，只作为统一 FileChange input。

10. 完成记录

完成时间：2026-06-29

实现摘要：

• Rust watcher batch 继续复用 /api/local-folder/events?treeLive=true，并在 changedPaths[] 保留 documentId、eventKind、selfWriteEcho、observedFileVersion、bufferFileVersion、lastWriteIntentId、lastSaveOperationId。
• Browser local-folder-event-bus-runtime.js 升级为轻量 FileChangeService：标准化 mnote.file_change_batch.v1，80ms 去抖合并，输出 mnote:file-change-batch / mnote:file-change-reaction，并兼容旧 tree:local-folder-watch-batch / mnote:local-folder:document-changed / resource-changed。
• document-session-runtime.js 统一消费 selfWriteEcho，clean 当前页走 Page Aggregate 自动刷新，dirty/saving/recent input 当前页进入 external conflict，不覆盖编辑器内容。
• OpenHub/opencode/legacy receipt changedFiles 收口到 emitChangedFiles / FileChange input，不再直接调用 refreshPrimaryDocument 作为 provider 专属刷新链路。
• watcher ignore 扩展到 .git、node_modules、target、dist、build 等高频目录。

验证命令：

• node --check rust/crates/mnote-web/browser/local-folder-event-bus-runtime.js && node --check rust/crates/mnote-web/browser/document-session-runtime.js && node --check rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js && node --check scripts/task540-local-folder-event-bus-single-connection-smoke.js && node --check scripts/task779-openhub-file-edit-document-pane-refresh-smoke.js && node --check scripts/task-local-folder-filechange-current-document-refresh-smoke.js && node --check scripts/task-local-folder-filechange-dirty-conflict-smoke.js && node --check scripts/task-page-ai-filechange-current-document-refresh-smoke.js
• cargo fmt --check -p mnote-web
• cargo test -p mnote-web local_folder -- --nocapture
• MNOTE_UI_BASE_URL=http://127.0.0.1:3010 MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3010 node scripts/task540-local-folder-event-bus-single-connection-smoke.js
• MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3010 node scripts/task-local-folder-filechange-current-document-refresh-smoke.js
• MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3010 node scripts/task-local-folder-filechange-dirty-conflict-smoke.js
• MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3010 node scripts/task-page-ai-filechange-current-document-refresh-smoke.js
• MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3010 node scripts/task776-openhub-changed-files-bridge-smoke.js（live probe 因缺少 task774 真实文件编辑结果跳过，静态检查通过）

剩余风险：

• task-local-folder-filechange-current-document-refresh-smoke.js 与 dirty conflict smoke 复用现有 task436 主流程，覆盖真实外部写入、AI 写入、dirty conflict、rename/delete conflict，但不是独立新实现的更细粒度脚本。
• FileChange reaction 当前通过 document session debug snapshot 判断当前页状态，并已暴露 data-mnote-file-change-service-session-api diagnostics；后续可把这层升级成正式 session registry API。
• mnote:page-ai-tool-write-completed 仍保留为 changedFiles 为空时的 legacy fallback，不作为 OpenHub/opencode/receipt changedFiles 主路径。