lix/mnote

Files

T

lix-2026 1882db7681 收口 MNote P0 P1 P2 审查尾项

- 归档 OnlyOffice live bridge、Page AI、mindmap、design governance 与相关 bug 条目
- 补齐 MinerU OCR 后端 runtime 合同与 smoke/test 基线
- 收口 ChatOnly/Doubao、ObjectIdentity、Page Aggregate compat 与 runtime owner 文档口径

验证：
- cargo test --manifest-path rust/Cargo.toml -p mnote-web local_ocr -- --test-threads=1
- cargo test --manifest-path rust/Cargo.toml -p mnote-web onlyoffice_bridge -- --test-threads=1
- git diff --check
- git diff --cached --check
- codegraph index . --force && codegraph status .
- codegraph sync . && codegraph status .

2026-06-01 09:29:12 +08:00

12 KiB

Raw Blame History

4-49 Local File Operation 与 Watch Event 合同 v1

状态：done Owner：04-tree-domain / 03-rust-web 背景：Sidex / VSCode Explorer 对照显示，MNote local_folder 的 tree command、watch event、refresh/reveal 和 opened resource 生命周期之间仍缺少稳定合同。当前前端常靠 relativePath / previousRelativePath 反推刷新父级，watch event 又容易退回全量 resync，导致大目录、批量操作和已打开资源场景下出现重复刷新、状态漂移和错误恢复困难。

1. 结论

local_folder 命令结果必须从“执行成功 + 少量路径字段”升级为“文件操作事件合同”：

后端声明 affectedParents，前端不再猜 old/new/current parent。
命令结果携带 revealTarget / selectTarget，刷新后可稳定落焦。
watch event 按 root 合并批次，输出 changedPaths、affectedParents、eventKinds。
opened editor/resource 通过 participant 参与 rename/move/delete，处理 buffer rekey、stale、close 或 redirect。
批量 paste/delete/move 用 batch id 聚合执行结果和刷新点。

2. Sidex / VSCode 对照

2.1 可借鉴的行为

ExplorerService 对 create/copy/move/delete 明确计算 old parent、new parent、nested parent，并刷新对应 item。
file changes 先进入延迟队列，批量判断是否影响已解析模型，再决定是否 refresh。
WorkingCopyFileService 在 move/delete 前后处理 dirty working copy，失败时发结构化 fail event。
BulkFileEdits 按批次执行，收集 per-item result 和 undo 操作。

2.2 不照搬的内容

不引入 VSCode undo/redo service 全模型。
不引入完整 working copy service container。
不改变 MNote 当前 local-first 文件系统事实源。
不把 Convex command 分支重新变成本地默认路径。

3. 当前缺口

3.1 command result 刷新边界不足

当前 local_folder command 走 execute_local_tree_command_with_sort 后返回 execution，前端再用 relativePath、previousRelativePath、parentRelativePath 和 request body 推断刷新父级。这个推断对 rename、move、trash、restore、bulk paste 都容易遗漏 old parent 或 new parent。

3.2 批量操作没有一致提交点

paste / bulk delete 当前逐项 dispatch command，单项成功后可能立即 patch DOM。多个结果交错时，UI 会经历多次 refresh，失败项也缺少结构化状态。

3.3 watch event 粒度偏粗

watcher 可以观察 path 事件，但 live event route 仍容易 rebuild full snapshot / resync。前端 fallback 有 debounce，服务端 SSE/resync 路径缺同等批处理语义。

3.4 opened resource 生命周期缺 participant

rename/move/delete 对已打开 Markdown buffer、mindmap、office resource tab 的影响仍分散：

Markdown buffer key 绑定 relative path。
resource tab identity 由前端字符串拼接。
delete/archive 后是否 close、mark stale、redirect，没有统一参与层。

4. 目标

所有 local_folder tree command 成功结果都能说明影响哪些 parent。
前端 refresh scheduler 只消费 affectedParents，不解析 action-specific 路径字段。
批量操作只在 batch 完成后统一 refresh/apply。
watcher event 按 root 合并，优先刷新 visible/loaded affected parents。
opened resource 在文件操作前后收到 participant 通知，能处理 dirty、rekey、stale、close。
所有失败路径发结构化 error，包含 phase/rootUri/action/path/batchId。

5. 非目标

不实现全局 undo/redo。
不重写 trash 物理存储。
不改变现有 tree command URL。
不把 resource tab group persistence 放进本设计；那属于 editor-mainline 后续。

6. 协议草案

6.1 Command result

建议 local command result 至少包含：

{
  "schema": "mnote.local_file_operation_result.v1",
  "operationId": "uuid-or-short-id",
  "batchId": "",
  "action": "rename",
  "rootUri": "file:///mnt/Data1T/mnote",
  "resource": {
    "documentId": "local-md:design/foo.md",
    "relativePath": "design/foo.md",
    "objectIdentity": "resource:file:file:///mnt/Data1T/mnote:design/foo.md"
  },
  "previousResource": {
    "documentId": "local-md:design/old.md",
    "relativePath": "design/old.md",
    "objectIdentity": "resource:file:file:///mnt/Data1T/mnote:design/old.md"
  },
  "affectedParents": [
    { "relativePath": "design", "reason": "old-parent" },
    { "relativePath": "design/new", "reason": "new-parent" }
  ],
  "revealTarget": {
    "relativePath": "design/foo.md",
    "rowId": "local:file:design/foo.md"
  },
  "selectTarget": {
    "relativePath": "design/foo.md",
    "rowId": "local:file:design/foo.md"
  }
}

约束：

rename same-parent 也必须返回 affected parent。
move cross-parent 必须返回 old parent 和 new parent。
delete/archive 必须返回 old parent 和 next focus hint。
restore 必须返回 restored parent 和 reveal target。
objectIdentity 必须来自后端 canonical identity，不由前端拼接。

6.2 Batch result

批量操作返回：

{
  "schema": "mnote.local_file_operation_batch_result.v1",
  "batchId": "batch-20260527-001",
  "action": "paste",
  "succeeded": 3,
  "failed": 1,
  "results": [],
  "affectedParents": [],
  "primaryRevealTarget": {}
}

前端规则：

batch 未完成前不做全量 refresh。
per-item 可做乐观占位，但最终以 batch result 的 affected parents 为准。
部分失败时展示结构化失败列表，不用 alert 拼字符串作为唯一反馈。

6.3 Watch event batch

服务端按 root 聚合短窗口：

{
  "schema": "mnote.local_folder_watch_batch.v1",
  "rootUri": "file:///mnt/Data1T/mnote",
  "watchRevision": {},
  "changedPaths": [
    { "relativePath": "design/foo.md", "kind": "modified" }
  ],
  "affectedParents": [
    { "relativePath": "design", "reason": "child-modified" }
  ],
  "eventKinds": ["modified"],
  "fallbackResync": false
}