chore: checkpoint turso and ai runtime work

2026-07-03 23:20:16 +08:00
parent a75b3d11f9
commit 36d027a4a1
67 changed files with 4224 additions and 914 deletions
@@ -0,0 +1,321 @@
+# 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`：
+
+```json
+{
+  "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`：
+
+```json
+{
+  "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：现状断点复核
+
+- [x] 复核 `LocalFolderWatcherRegistry` 产出的 `selfWriteEcho`、`observedFileVersion`、`bufferFileVersion` 是否完整进入 `watch_batch.changedPaths[]`。
+- [x] 复核 `/api/local-folder/events?treeLive=true` 是否对当前 workspace root 只有一个 watcher 连接。
+- [x] 复核 `local-folder-event-bus-runtime.js` 是否把 `documentId/eventKind/selfWriteEcho/fileVersion` 保留给 `document-session-runtime.js`。
+- [x] 复核 `document-session-runtime.js` 的命中条件：`documentId`、`relativePath`、`rootUri`、`workspaceId`。
+- [x] 复核当前截图场景中 Page AI/OpenHub 写入后是否有真实 watcher 事件、synthetic event、或两者都没有。
+- [x] 复核是否存在跨批次重复事件导致同一路径多次 refresh。
+- [x] 复核 ignore 规则是否放过 `.git`、`node_modules`、`target`、`dist` 等高频目录。
+
+验收：
+
+- [x] 产出一份断点日志或 smoke 证据，能指出“事件未到达 / 字段丢失 / session 未命中 / dirty 拦截 / refresh 失败”的具体层级。
+
+### Batch B：标准 FileChange batch
+
+- [x] 在 browser event bus 增加标准化函数：从 watcher `watch_batch`、synthetic changedFiles、legacy receipt 转成 `mnote.file_change_batch.v1`。
+- [x] 统一绝对路径到 root-relative path 的解析规则，路径不在 rootUri 下时丢弃并记录 diagnostics。
+- [x] 合并同一 `rootUri + relativePath` 的短时间重复事件。
+- [x] 保留 `source`、`eventKind`、`selfWriteEcho`、`observedFileVersion`、`bufferFileVersion`。
+- [x] 暴露 diagnostics：最近 batch source、changed count、dropped count、last reaction。
+- [x] 保持旧 `watch_batch.changedPaths/affectedParents/eventKinds` 字段兼容，新增标准 batch 不破坏旧消费者。
+- [x] 如 Rust 侧改类型，保证最终 SSE/JS JSON 格式仍兼容旧 smoke。
+
+验收：
+
+- [x] `task540-local-folder-event-bus-single-connection-smoke.js` 仍通过。
+- [x] 新增静态 smoke 确认 `mnote.file_change_batch.v1`、`selfWriteEcho`、`emitSyntheticWatchBatch` adapter 存在。
+
+### Batch C：Reaction 分发
+
+- [x] 新增 reaction 计算：当前文档 clean -> `refresh_current_document`。
+- [x] dirty/saving/recent input -> `external_conflict_current_document`。
+- [x] self-write echo -> `ignore_self_write_echo`。
+- [x] filetree affected parents -> `refresh_filetree_parents`。
+- [x] resource tab -> `refresh_resource_tab`。
+- [x] 保持旧事件兼容输出：`tree:local-folder-watch-batch`、`mnote:local-folder:document-changed`、`mnote:local-folder:resource-changed`。
+- [x] 不在 Rust watcher 回调中做新的重 I/O；reaction 计算应基于已有事件字段和 session state。
+
+验收：
+
+- [x] 外部写当前 `.md` 后，当前 tiptap 页面无需浏览器刷新显示新文本。
+- [x] 当前页面 dirty 时，外部写同一 `.md` 不覆盖编辑器，显示 external conflict。
+- [x] filetree/page tree 仍按局部 parent 刷新，不整页 reload。
+
+### Batch D：AI source adapter 收口
+
+- [x] OpenHub/opencode changedFiles 只调用统一 FileChange input，不直接调用 `refreshPrimaryDocument`。
+- [x] legacy Page AI receipt 只调用统一 FileChange input。
+- [x] 移除或降级旧的 provider 专属直接刷新路径；保留兼容时必须标注为 fallback diagnostics。
+- [x] changedFiles 为空时不伪造 diff；只依赖真实 watcher 或 explicit changedFiles。
+
+验收：
+
+- [x] agent/OpenHub/opencode 写当前 `.md` 后，当前页面自动更新。
+- [x] 若 provider 不报 changedFiles，真实 watcher 仍能驱动更新。
+- [x] 若 watcher 漏报但 provider 报 changedFiles，synthetic FileChange 可驱动同一 reaction。
+
+### Batch E：回归与归档
+
+- [x] 新增或更新 smoke：
+  - [x] `task-local-folder-filechange-current-document-refresh-smoke.js`
+  - [x] `task-page-ai-filechange-current-document-refresh-smoke.js`
+  - [x] `task-local-folder-filechange-dirty-conflict-smoke.js`
+- [x] 运行 `cargo test -p mnote-web` 中相关单测。
+- [x] 运行 local-folder event bus、filetree lazy loading、page aggregate refresh 相关 smoke。
+- [x] `codegraph sync .` 并确认状态。
+- [x] 完成后把本设计从 `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 主路径。