mnote/ARCHITECTURE.md

MNOTE 当前架构梳理

更新时间：2026-05-19

2026-05-19 口径更新：产品形态已切换为 local-first workspace；本地文件夹是默认数据真相，Convex / 服务端降级为账号、分享、同步、协作和 AI 隔离控制面。相关设计已完成并迁入 design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md。本地 Markdown 图片与附件上传已新增 /api/local-folder/assets/upload，页面内上传默认写入 {mdBase}.assets/ 并保存相对 Markdown 路径，不再走 Convex media asset。

当前阶段：local-first MVP 骨架已达成。 3000 下文档页、Sidebar/File Tree/Page Tree 三层树模型、tree command（tree.* preferred）、tree realtime WS 主链 / SSE fallback、本地 Markdown 上传、AI 会话本地化与 VSCode-like agent 运行口径均已建立。剩余工作集中在管理员目录授权、VSCode-like 冲突合并 UI、agent diff 审计、本地索引 / 分享 / 同步闭环，而不是继续扩张专用 page-ai fast-path 或 Convex 主存储链。

本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。

1. 当前主线结论

当前仓库的主线不是：

• BlockNote-first
• Mindmap-first
• “先拆掉 Convex 再谈 Rust”

当前主线固定为：

1. tree-first graph kernel 是长期对象真相层
2. 本地文件夹是默认数据真相，Convex / 服务端退居账号、分享、同步、协作和 AI 隔离控制面
3. mnote-web 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
4. 文档页默认主编辑器已切到页面内 leptos-tiptap island
5. BlockNote 已退出文档页默认主路径，仅作为历史参考实现 / 对照材料保留
6. 页面 AI 当前最合理的长期形态是：MNote 只负责页面定位、白名单目录权限、agent runtime 管理、文件变更同步；Hermes / Reasonix 直接在授权工作区内编辑本地文件。page_ai_workflow 与 mnote.doc.* / mnote.block.* 保留为兼容 / cloud / 复杂结构辅助层，不再作为 local-first 普通正文编辑默认主路径

一句话收口：

Rust 持有语义主导权，本地文件夹是默认数据真相，Convex 只保留控制面与可选同步协作能力，前端逐步从重壳转向消费稳定 projection 与少量交互 island。

补充口径：

主 Web 执行面当前以 mnote-web 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。

页面 AI 的 local-first 主路径应尽量贴近 VSCode：当前页面解析成真实 .md 文件，Hermes / Reasonix 在授权目录白名单内直接读写，tiptap 只消费后台文件变化后的最新投影。

2. 当前主线目录

• /mnt/Data1T/mnote/recycle/wolai-frontend/ 已退役移入 recycle。React island 与 legacy compat 代码的历史来源；Next.js App Router 已被 Rust mnote-web SSR 替代，不再作为 3000 主入口。
• /mnt/Data1T/mnote/rust/crates/core-protocol/ Kernel 类型、projection 协议、编辑器协议、树 / 图核心术语。
• /mnt/Data1T/mnote/rust/crates/bridge-runtime/ Kernel query / command、bridge transport、Tiptap <-> editor document 适配、命令解释层。
• /mnt/Data1T/mnote/rust/crates/mnote-web/ Rust Web route、kernel projection、documents/search/mindmap shell、Hermes bridge、stream transport、compat，以及显式开启时的 debug shell；它是当前主 Web gateway / shell / transport owner。
• /mnt/Data1T/mnote/recycle/wolai-frontend/convex/ 已随 wolai-frontend 移入 recycle。当前活跃 Convex functions 位于 infra/convex/ 与 Rust bridge 中。
• /mnt/Data1T/mnote/infra/convex/ Convex 自托管部署与基础设施。
• /mnt/Data1T/mnote/wolai-backend/ 辅助后端与异步处理，不是当前页面主链。

3. 当前页面运行结构

3.1 根布局与 legacy island source（已退役）

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/app/layout.tsx

该文件已随 wolai-frontend 移入 recycle/，不再作为当前实现依据。

注意：

3000 当前根入口与文档页 shell 由 mnote-web Rust SSR 持有；Next App Router 已完全退役。

3.2 工作区壳与 Sidebar（已迁移至 Rust SSR）

以下文件已随 wolai-frontend 移入 recycle/，不再作为当前实现依据：

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/app-layout-shell.tsx
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/hooks/use-sidebar-data.ts
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/tree-stream/use-sidebar-tree-stream.ts
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts

当前 Sidebar/工作区壳的当前实现在 Rust mnote-web SSR：

• 工作区壳渲染入口：gateway.rs（root_entry）
• 文档页壳/文档面板：web_shell.rs（document_page_shell、build_document_panes_bootstrap_json）
• Sidebar tree stream 消费：layout.rs 嵌入 JS（startWithSse / startWithWebSocket）
• FileTree 渲染与交互：tree.rs 嵌入 JS

4. 文档页主链

4.1 入口

文档页入口的当前实现在 Rust mnote-web：

• 文档页壳 SSR：web_shell.rs（document_page_shell），直接输出 HTML + bootstrap JSON
• Page Aggregate 快照 API：web_shell.rs（page_aggregate）返回 /api/page-aggregate/:id
• 前端桌面/窗口面板布局：web_shell.rs（build_document_panes_bootstrap_json）

历史 wolai-frontend Next 文档页入口（已移入 recycle/）：

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/page-aggregate-loader.ts
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/app/(app)/documents/[id]/page.tsx
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/page-aggregate.ts

4.2 文档壳（已迁移至 Rust SSR）

历史 React 文档壳组件（已随 wolai-frontend 移入 recycle/，不再作为当前实现）：

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/document-shell.tsx
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/document-content.tsx

当前文档壳由 Rust mnote-web SSR 输出：

• web_shell.rs → document_page_shell 直接渲染 HTML shell，不在前端保留 React 文档壳 runtime。

4.3 默认编辑器 host（已迁移至 WASM island）

历史 React 编辑器 host（已移入 recycle/）：

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/editor-host-config.ts
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/editor-host.tsx
• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx

当前默认主编辑器是页面内 Leptos/WASM island，由 Rust mnote-web SSR 加载：

• WASM 产物：rust/spikes/leptos-tiptap-spike/
• 加载路由：web_shell.rs → leptos_tiptap_manifest / leptos_tiptap_asset

4.5 BlockNote 的当前位置

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/components/editor/blocknote-editor.tsx

BlockNote 已随 wolai-frontend 移入 recycle，仅作为历史对照材料，不参与当前实现。

而不是默认主编辑器方向。

5. 当前编辑器与页面聚合关系

当前文档页已经开始消费统一的 PageAggregateProjection，但仍不能说“页面域已完全统一成 Rust 单一真源”。

当前真实状态是：

• 读取主链已优先消费 Rust mnote.page_aggregate.v1 snapshot
• Page Aggregate 已输出 blockDocument、blockProjectionVersion 与 projectionSource
• 标题链路已开始与工作区树 canonical snapshot 对齐
• 正文默认由 leptos-tiptap island 编辑与保存
• 页面设置已有一部分进入 island 运行时语义
• page_tree / pageSubtree 已进入统一聚合入口
• 页面/块 AI tools 可通过 Page Aggregate block projection 读取、定位、dry-run、替换、插入和受限移动块；local-first 普通正文编辑不再要求走块工具，在线 / cloud / compat 场景才回到受控 mnote tool 写入。

2026-05-16 更新：以下四项已通过真实 3000 browser smoke 验证（证据见 tmp/page-aggregate-* 目录）：

• 标题写入后 Page Aggregate、页头、Breadcrumb、Sidebar、Page Tree、File Tree 一致性（task110）
• 正文保存后 body.revision / conflictDetectionKey / blockDocument 同步（task-page-aggregate-body-sync-smoke）
• 页面设置写入后 layout.pageOptions 与 island runtime DOM 同步，刷新后不退回（task-page-aggregate-options-sync-smoke / task-page-aggregate-refresh-persistence-smoke）
• Convex 不可用时返回 degraded error（503 + x-error-code=convex_unavailable），不返回伪 fixture（route 级负向测试）

仍未完成的关键点是：

1. Rust 侧已提供最小 Page Aggregate snapshot 和 block projection v1，但当前 block projection 仍主要从 documents.content / local markdown content 投影（projectionSource=documents.content），不是 EditorBlockDocument 原生落库完成态
2. 标题 / 正文 / 页面设置虽已收口到 page.* family 和 local-first 文件版本模型，但客户端仍保留 PageAggregateClientState reducer（混合 server snapshot / draft title / local content），页面域单一真源仍未完全闭环
3. AI 块工具继续作为复杂结构辅助；local-first 普通 Markdown 编辑主路径已经转为“授权文件引用 + agent 原生 patch/diff + watcher 同步”
4. Sidebar 仍通过 preferred snapshot（initial / query / tree_stream）做 freshness 选择，tree realtime live cache 未统一

因此当前正确表述应是：

文档页读取主链已进入 Rust-first page aggregate 过渡态，标题/正文/页面设置 smoke 已通过，但页面域单一真源（ClientState → Rust snapshot）与 tree realtime live cache 仍未闭环。

6. 当前树域结构

6.1 Kernel projection 与 route

• /mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/kernel.rs

当前 Rust 已提供：

• sidebar_tree
• page_tree
• file_tree
• subtree
• edges
• graph

这些 route 说明树域 projection family 已经在 Rust 侧具备清晰边界。

6.2 树命令现状

• /mnt/Data1T/mnote/recycle/wolai-frontend/src/lib/documents/tree-command-client.ts
• /mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/tree.rs
• /mnt/Data1T/mnote/rust/crates/storage-convex-bridge/src/mapping.rs

当前树命令已经开始以 tree.* 为 preferred command name，例如：

• tree.node.create
• tree.node.rename
• tree.subtree.move

但兼容层仍广泛保留：

• documents.create
• documents.title.update
• documents.move

这说明 tree command cutover 已开始，但还没有完成。

6.3 树 realtime 现状

当前 Sidebar 已有：

• query snapshot
• tree stream
• preferred snapshot 选择

正式的 snapshot + delta 主链已经固定到 mnote-web 的 /api/tree/events，Next /api/mnote-web/stream 只保留 compat alias。

因此当前正确表述应是：

树域 realtime 主链由 Rust Web /api/tree/events 持有，前端只消费稳定 stream contract 与 projection。

补充：

3000 主壳当前已不再通过 /api/tree/projections/* 额外维护第二条 runtime live fallback；snapshot / delta / resync 直接消费 /api/tree/events 载荷。

6.4 Resource Tree / File Tree / Page Tree 三层模型

当前树域已建立三层语义（合同见 design/04-tree-domain/done/4-24-* 与 design/05-editor-mainline/done/5-12-*）：

• Resource Tree：长期 canonical 对象组织树，Rust kernel 持有语义。资源类型包括 page、mindmap、attachment、onlyoffice、code 等（KernelObjectIdentity、KernelProjectionResourceKind 已在 core-protocol 落地）。
• File Tree：Resource Tree 的主组织投影。展示页面文件夹、{title}.md（非 index.md）、mindmap、附件等资源。文件树行消费 Rust /api/tree/projections/file 或等价 projection，不在前端临时拼装第二真相。
• Page Tree：面向阅读/导航的快捷投影。只显示页面关系和导航语义，不拥有排序、父子、附件归属的最终真相。

关键规则：

• 文件树点击 mindmap 打开 mindmap object editor，不被 {title}.md 吞掉
• {title}.md 只代表页面正文（Page Aggregate body），mindmap / OnlyOffice / 附件是不同 object model
• 页面树不持有独立结构真相，只显示文档导航关系

7. Mindmap 与 OnlyOffice

7.1 Mindmap

当前 Mindmap 不再是系统中心，而是：

• tree-first graph kernel 的一种视图 / 编辑挂件

它仍有：

• 文档内嵌块形态
• 独立页面形态

但不应再被理解为对象真相层。

7.2 OnlyOffice

OnlyOffice 仍然是：

• 独立页面型编辑器

它不直接嵌入正文主编辑画布；正文中通常通过附件块跳转进入。

8. 当前最优先的架构收口

当前最优先的三条主线，不是继续大规模 UI 重写，而是：

8.1 Page Aggregate

目标：

• 让标题 / 页面设置 / 正文 / page tree 统一成同一组 page aggregate projection 与 command family
• 前端不在页面壳、island 外侧、Sidebar preferred snapshot 外再拼第二份页面真相

当前进度（2026-05-16）：

• ✅ 文档页读取主链已 Rust-first，TS builder 退出 runtime，Next compat 返回 410
• ✅ 标题单一真源 smoke 通过（task110）：页头/Breadcrumb/Sidebar/Page Tree/File Tree 一致
• ✅ 正文写入后 body.revision / blockDocument 同步 smoke 通过
• ✅ 页面设置写入后 pageOptions 同步与刷新持久化 smoke 通过
• ✅ local-first page.body.write / /api/page-body/write 与 expectedFileVersion 已成为本地正文写入主入口，/api/documents/save 降级为 compat adapter
• ✅ 本地 Markdown 图片 / 附件上传写入 sibling assets，并由真实浏览器 smoke 覆盖保存后刷新恢复
• ✅ Convex 不可用时返回 degraded error，不返回伪 fixture
• ⬜ cloud / compat block projection 继续减少 documents.content 后备；local-first 正文真相已转为 .md 文件投影
• ⬜ 客户端 PageAggregateClientState reducer 退役，页面域完全以 Rust snapshot 为单一运行时真相

对应设计稿：

• /mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md
• /mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md
• /mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md

8.2 Tree Command Cutover

目标：

• 让 tree.* 成为正式命令面
• documents.* 降为兼容层

对应设计稿：

• /mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md

8.3 Tree Realtime Event Stream

目标：

• 让 snapshot + delta 正式成为树域实时主链
• 减少当前 query/refetch/freshness 补偿链的长期存在

对应设计稿：

• /mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md

8.4 Page / Block AI Tooling

目标：

• 让 local-first 页面 AI 默认走“页面定位 -> 授权文件引用 -> agent 原生 patch/diff -> 前台同步”
• 把 mnote.page.save 固定为页面级兜底写入工具，不再代表普通正文编辑默认入口
• 把 mnote.doc.* / mnote.block.* 收口为兼容 / cloud / 复杂结构辅助工具
• 补齐 scope=selection、白名单目录权限、changed_files/diff 审计、前台同步刷新矩阵

当前进度（2026-05-19，按 2-2 完成态更新）：

• ✅ 页面 AI 与 ACP runtime 已能承载本地优先方向
• ✅ page_ai_workflow 已在 local source 下退出主路径
• ✅ Hermes tools（mnote.doc.* / mnote.block.*）已可作为兼容 / cloud / 复杂结构辅助层读取和写入
• ✅ 本地优先设计已经收口为 VSCode-like 运行模型：页面定位 + 白名单目录 + agent 直改文件 + tiptap 同步显示
• ✅ 页面 AI 默认输入已收口到 currentFile + selection + allowedRoots / aiAccessScope
• ✅ Hermes / Reasonix runtime 已显式带白名单目录运行
• ⬜ MNote 回收 changed_files / diff 审计
• ⬜ scope=selection、format=page_xml/text 继续作为结构化辅助输出，不作为普通 Markdown 编辑必需路径
• ⬜ tool manifest annotations 继续补齐 destructive / requiresApproval 等高级语义
• ⬜ Phase C（设计冻结，不实施）：StreamApplyController + ReviewSession + GhostTextOverlay（流式 apply + suggest/review）
• ⬜ stale revision / idempotency 重放保护（已有 revision 乐观锁覆盖，补端到端 smoke）

关键原则（2026-05-18 口径更新）：

• local-first 主路径：当前页面解析成授权 .md 文件，Hermes / Reasonix 在白名单目录内直接读写，MNote 负责权限、审计和前台同步
• 兼容两层模型（参考 CLI Main Lark Doc）：mnote.doc.markdown_edit 作为文本级兼容 / fallback，mnote.doc.apply_block_ops 作为块级结构性辅助；local-first 正常编辑优先走“授权文件引用 + agent 原生 patch/diff + 文件版本冲突模型”
• mnote.block.* 降级为结构性辅助（拖拽排序、精确块删除等），不删除
• 当前 local_rule planner（direct_block_edit_operations）是过渡实现，应继续退役
• cloud / remote agent 无法直接访问本地文件时，才回到 resolve_source → Convex | LocalFS 的受控代理写入
• Markdown 既是 AI 编辑格式也是人类可读格式，不需要 XML 中间层
• 流式 apply + suggest/review（参考 BlockNote AI 的 StreamToolExecutor + suggestChanges）仅作为 Phase C 设计冻结，当前不实施

对应设计稿：

• /mnt/Data1T/mnote/design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md
• /mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md
• /mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md

8.5 定向 Bug Hunt 与质量基线

目标：

• 围绕已知架构风险做定向排查，而非泛泛"找 bug"

优先关注：

• Page Aggregate 回流不一致
• AI 块写入 conflict / stale revision
• File Tree {title}.md 与 page title 同步
• tree stream resync / 双浏览器一致性
• debug / compat / fallback 是否混入首屏主链

已有 smoke 体系（scripts/ 目录）：

• task110-page-title-single-truth-smoke.js：标题全链路一致性
• task-page-aggregate-body-sync-smoke.js：正文写入后 Page Aggregate 同步
• task-page-aggregate-options-sync-smoke.js：页面设置写入后同步
• task-page-aggregate-refresh-persistence-smoke.js：刷新持久化
• task123-rust-web-tree-live-stream-consumer-smoke.js：tree realtime 消费
• task169-mindmap-realtime-smoke.js：mindmap 隔离与持久化
• task179-tree-create-delete-no-reload-smoke.js：树操作无刷新

9. 当前不该再用的旧口径

下面这些说法现在都不准确：

• “默认文档页仍然是 BlockNoteEditor”
• “主编辑器还没切到页面内 Leptos island”
• “当前最优先是继续证明 leptos-tiptap 能不能跑”
• “当前最优先是先做树域 UI 重构”
• “Rust Web 还只是实验，没有接真实页面链路”
• “页面 AI 编辑必须经过 Hermes agent，没有快路径”
• “页面 AI 编辑必须经过 MNote 专用工具才能改普通 Markdown”

当前真正的卡点已经从“能不能跑”变成：

管理员目录授权、文件版本冲突合并、agent diff 审计、本地索引 / 分享 / 同步如何产品化；Page Aggregate ClientState、projection / command / realtime 兼容链如何继续瘦身。