对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00
parent 8c895b3dc0
commit afb2a5b8a0
89 changed files with 23188 additions and 84 deletions
@@ -0,0 +1,459 @@
+# [recycle] 文档访问性能根治重构路线 v1
+
+> 更新时间：2026-04-16
+>
+> 相关文档：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/ai-frontend-simplification-plan-v1.md`
+> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md`
+
+## 1. 目标
+
+这份文档只回答一个长期问题：
+
+> **如果不满足于“临时优化”，而要从架构上根治文档访问和页面切换卡顿，mnote 应该重构成什么样。**
+
+本文的目标不是“再做几处按需加载”，而是定义：
+
+- 哪些前端能力应继续保留
+- 哪些能力应退出当前重前端壳
+- Rust Web 层应该采用什么形态
+- `BlockNote` 应该如何被隔离，而不是继续拖慢整个页面系统
+
+---
+
+## 2. 当前事实
+
+结合当前仓库结构，可以先确认四个事实：
+
+### 2.1 当前最重的前端成本，不在服务端语言
+
+当前文档页主链仍然是：
+
+`documents/[id]/page.tsx -> DocumentShell -> DocumentContent -> BlockNoteEditor`
+
+而且存在以下典型问题：
+
+- 文档进入页面后仍有 `meta -> content -> editor` 的串行加载链
+- `DocumentShell` 与 `DocumentContent` 仍在客户端串联挂载
+- `BlockNoteEditor` 本身是当前最重的前端运行时之一
+- 文档页周边仍挂载多类抽屉、面板和桥接组件
+
+这说明当前访问速度问题的核心，不是“Node 不够快”，而是：
+
+> **页面切换时仍然把太多东西当成同一层前端运行时来初始化。**
+
+### 2.2 当前只有一类能力明确难以短期替换
+
+从产品结构看，短期最难替换的是：
+
+- `BlockNote`
+
+因为它同时承担：
+
+- 文档编辑核心
+- 自定义 block 运行时
+- 当前正文交互和保存链
+
+而下面这些东西，从长期看都不是必须继续绑在当前 React/Next 大壳里的：
+
+- Sidebar / 页面树 / 文件树
+- 搜索壳与搜索结果面板
+- Mindmap
+- AI 面板
+- 历史 / 评论 / 回链 / 页面选项等周边面板
+- 在线表格
+
+### 2.3 OnlyOffice 不应被当成主阻塞项
+
+根据当前架构，OnlyOffice 本来就是独立页面型编辑器，不是正文内嵌主编辑器。
+
+这意味着：
+
+- 它不会决定文档页的首屏切换模式
+- 它可以继续保留“外挂页面/外部编辑器”定位
+- 它不应影响主文档访问性能路线判断
+
+### 2.4 Mindmap 是优先级更高的可替换对象
+
+当前 Mindmap 虽然复用了前端组件链，但它并不像 BlockNote 那样不可轻易动。
+
+因此长期上：
+
+- Mindmap 可以先于 BlockNote 重写
+- 它很适合作为“从当前重前端壳中剥离”的第一批对象
+
+---
+
+## 3. 根治原则
+
+如果目标是“根治”，而不是“补丁式提速”，那么应遵守以下原则。
+
+### 3.1 页面切换必须先回到“读优先”
+
+当前问题的根子之一，是页面切换几乎默认在进入“编辑器世界”。
+
+长期正确方向应改为：
+
+- 先快速进入页面阅读态
+- 再按需进入编辑态
+- `BlockNote` 不得阻塞普通页面访问
+
+换句话说：
+
+> **文档页要从“先挂编辑器，再展示页面”改成“先展示页面，再按需挂编辑器”。**
+
+### 3.2 除 `BlockNote` 外，其余能力应尽量退出当前重前端壳
+
+长期目标不应是“继续给当前 Next/React 应用做瘦身”，而应是：
+
+- 让能退出的都退出
+- 让必须保留在浏览器的只剩真正需要浏览器的那部分
+
+理想形态是：
+
+- 文档阅读页：极薄
+- 文档编辑岛：`BlockNote`
+- 外挂编辑器：OnlyOffice
+- 独立能力：Mindmap、AI、搜索、Sidebar 等各自最小化
+
+### 3.3 Rust 化的意义在于“统一业务执行面”，不是“自动更快”
+
+把东西改成 Rust 并不会自动让页面切换更快。
+
+Rust 真正的价值在于：
+
+- 统一业务执行平面
+- 让文档、块、导图、搜索、树结构、审计、AI 业务桥收口到同一体系
+- 支持更薄的前端和更强的 SSR / server-first 输出
+
+所以“Rust 化”必须和“页面运行模型重构”一起发生，才构成根治。
+
+---
+
+## 4. 技术选型判断
+
+这一节只回答一个问题：
+
+> **长期重构时，到底是“就用 Rust”，还是要明确选择 `axum` 等 Rust Web 框架。**
+
+结论先给出：
+
+> **不能只说“用 Rust”。长期要落地，必须明确分层选型。推荐方案是：`axum` 作为 Web/服务承载层，配合 `Leptos Islands` 作为 server-first 页面壳；不推荐只用 `axum`，也不建议把 Dioxus/Yew 作为主文档访问层的第一选择。**
+
+### 4.1 为什么不能只说“Rust”
+
+“Rust”是语言，不是 Web 渲染方案。
+
+如果只决定“以后改成 Rust”，但不明确：
+
+- 服务端路由由谁承接
+- 页面 SSR 由谁承接
+- islands / hydration 模型由谁承接
+- 浏览器交互层由谁承接
+
+那最后很容易回到：
+
+- 只是把 API 改写成 Rust
+- 但前端页面模型仍然没变
+
+这不能根治。
+
+### 4.2 `axum` 的定位：非常适合做 Web 承载层，但不负责前端 UI 模型
+
+官方 `axum` 文档显示，它非常适合承担：
+
+- Router
+- Handler
+- Middleware
+- JSON / Query / Form / WebSocket / SSE
+- `tokio` 上的高并发服务
+
+这使它非常适合作为 mnote 长期的：
+
+- API 层
+- 文档查询层
+- 树结构聚合层
+- 搜索层
+- AI / Hermes 业务桥
+- SSR 页面外壳承载层
+
+但要注意：
+
+> **`axum` 不是前端渲染框架。它能承接 Web 服务，不会替你解决“页面如何减少 hydration、如何隔离 BlockNote”这类前端模型问题。**
+
+因此，**只用 `axum` 不够。**
+
+### 4.3 为什么推荐 `Leptos Islands`
+
+官方 Leptos Islands 文档最值得关注的点是：
+
+- 默认服务端组件不进入客户端
+- 只有显式 `#[island]` 的部分才被编译到浏览器
+- islands 应尽量“小而具体”
+
+这和 mnote 的长期目标高度一致，因为你现在最想要的是：
+
+- 绝大多数页面内容不再变成大块客户端运行时
+- 只有真正需要交互的部分进入浏览器
+- `BlockNote` 成为最后一个重交互 island
+
+也就是说，Leptos Islands 的思路天然支持：
+
+- 页面树/文件树作为轻交互 island
+- 搜索框作为轻交互 island
+- AI 面板作为独立 island
+- `BlockNote` 作为最后的重 island
+- 其余大量阅读内容只做 server-rendered HTML
+
+这比“继续在全页 React hydration 里做局部优化”更接近根治。
+
+### 4.4 为什么不把 Dioxus 作为主推荐
+
+官方 Dioxus Fullstack 文档自己就把它定位得更偏“app-like”：
+
+- 它支持 SSR
+- 但更强调交互型应用
+- 文档中明确区分 CSR 的 app 架构与 SSR 的 site 架构
+
+而 mnote 的长期目标不是继续维持一个“整页 app 先跑起来”的文档访问模型，而是：
+
+- 页面先出来
+- 交互再局部接上
+
+所以 Dioxus 不是不能用，而是**不如 Leptos Islands 对这个目标直接。**
+
+### 4.5 为什么不把 Yew 作为主推荐
+
+Yew 更接近经典 Rust/WASM 前端框架。
+
+它的问题不是能力不够，而是：
+
+- 更偏客户端应用思路
+- 不天然突出 islands-first
+- 对你当前“尽量减少客户端代码、把交互压缩为少数岛”的目标，不是最优选
+
+---
+
+## 5. 推荐的长期方案
+
+## 5.1 总体选型
+
+推荐长期架构采用：
+
+- **服务承载层：`axum`**
+- **页面壳与 islands 模型：`Leptos Islands`**
+- **业务执行面：现有 mnote Rust `core-protocol + bridge-runtime + storage-convex-bridge` 继续演进**
+- **AI runtime：Hermes API Server**
+- **最后保留的重编辑岛：`BlockNote`**
+
+一句话版：
+
+> **`axum` 负责服务，`Leptos` 负责薄页面与 islands，Rust 内核负责业务，Hermes 负责 agent，`BlockNote` 留作最后的重前端孤岛。**
+
+## 5.2 为什么这是最适合 mnote 的方案
+
+因为这个方案同时满足四个条件：
+
+### A. 适合逐步迁移
+
+你不需要一次性推翻所有前端。
+
+可以先把：
+
+- Sidebar
+- 页面树 / 文件树
+- 搜索壳
+- 阅读页
+- Mindmap
+
+逐步迁到 `axum + Leptos`
+
+再把 `BlockNote` 留在最后处理。
+
+### B. 适合“读写分离”
+
+`Leptos Islands` 很适合把页面拆成：
+
+- 读页面：服务端输出
+- 写页面：局部 island
+
+这正是文档访问性能根治的核心。
+
+### C. 适合 Rust 单栈长期收口
+
+当前你已经做过大范围 Rust 重构，未来继续统一到：
+
+- Web 壳
+- 业务协议
+- AI 业务桥
+- CLI
+
+会比继续维护“Rust 内核 + 重 Next 前端壳”的分裂状态更稳定。
+
+### D. 风险可控
+
+你不需要一开始就重写 `BlockNote`。
+
+最难的部分可以留到最后，不会卡死整个长期路线。
+
+---
+
+## 6. 最终目标架构
+
+长期目标建议收敛成下面这张逻辑图：
+
+```text
+浏览器
+  -> axum 路由层
+    -> Leptos server-rendered 文档壳
+      -> 少量 islands
+        - Sidebar / 页面树 / 文件树
+        - Search
+        - AI 面板
+        - Mindmap（重写后）
+        - BlockNote（最后保留的重岛）
+
+axum / Leptos
+  -> mnote Rust 业务执行面
+    - 文档
+    - 块
+    - 搜索
+    - 导图
+    - 审计 / trace / event
+
+Hermes API Server
+  -> 调用 mnote Rust 暴露的业务能力桥
+
+OnlyOffice
+  -> 继续独立页面 / 外挂编辑器
+```
+
+在这个目标架构里：
+
+- 页面切换不再默认进入“整页前端应用”
+- 绝大多数阅读内容不需要大块 hydration
+- `BlockNote` 成为唯一需要谨慎处理的大前端负担
+
+---
+
+## 7. 推荐迁移顺序
+
+长期路线建议分四阶段，不建议一口气重做。
+
+## Phase 1：先把文档访问模型改成 server-first
+
+先做：
+
+- 用 Rust Web 壳承接文档阅读态
+- 页面进入时直接输出 `meta + content`
+- 不再进入页面后再串行拉正文
+- 把“页面切换”和“编辑器启动”拆开
+
+这一阶段的目标不是替换 BlockNote，而是先把它从切页主链里移走。
+
+## Phase 2：优先重写可替换的常驻模块
+
+优先级建议：
+
+1. Sidebar / 页面树 / 文件树
+2. 搜索壳与搜索结果页
+3. 页面选项、历史、评论、回链等周边面板
+4. AI 面板
+
+原因：
+
+- 这些东西是跨页面常驻能力
+- 高频出现
+- 比 BlockNote 更容易先抽离
+
+## Phase 3：重写 Mindmap，继续缩小前端重负担
+
+Mindmap 是非常适合优先退出当前重前端壳的对象。
+
+建议：
+
+- 把导图数据和执行面继续放在 Rust
+- 前端重新实现为更轻的独立渲染层
+- 不再依赖当前文档页大壳去承载
+
+## Phase 4：最后再处理 BlockNote
+
+这时再决定：
+
+- 是否继续保留 BlockNote，但隔离为独立 island
+- 是否逐步替换 BlockNote 的部分能力
+- 是否长期把编辑体验拆成更多 Rust 原生能力 + 少量 JS 编辑器兼容层
+
+**在此之前，不建议把 BlockNote 当成第一刀。**
+
+---
+
+## 8. 非目标
+
+为了避免路线漂移，下面这些都不应被误认为“根治方案”。
+
+### 8.1 不是“把 Next API 改成 Rust 就算完成”
+
+如果页面仍然是：
+
+- 重客户端壳
+- 重 hydration
+- 切页即初始化编辑器
+
+那只是服务端换语言，不是根治。
+
+### 8.2 不是“先全面重写 BlockNote”
+
+BlockNote 是最难对象，不应先作为第一刀。
+
+正确顺序应是：
+
+- 先移除外围负担
+- 最后再碰 BlockNote
+
+### 8.3 不是“继续在当前 React 壳里无限做局部修补”
+
+按需加载、拆组件这些短期仍有价值，但如果最终仍然保留：
+
+- 大型客户端文档壳
+- 大型常驻 Sidebar
+- 大型客户端页面切换模型
+
+那还是治标不治本。
+
+---
+
+## 9. 最终建议
+
+如果以“根治文档访问性能”为唯一目标，我给出的长期技术判断是：
+
+> **应该继续推进 Rust 主导重构，但不是笼统地说“以后用 Rust”，而是明确采用 `axum + Leptos Islands + mnote Rust 内核 + Hermes` 的组合。**
+
+其中：
+
+- `axum`
+  适合做 Web 服务承载层、API、SSE、AI 业务桥、SSR 外壳。
+- `Leptos Islands`
+  适合做 server-first 文档页和极小交互岛，是把 `BlockNote` 隔离成“最后一个重前端岛”的最佳路线。
+- `Dioxus`
+  可以关注，但更适合作为偏 app 化交互场景的备选，不是当前文档访问性能根治的第一推荐。
+- `Yew`
+  不作为当前主路线推荐。
+
+最后用一句话收口：
+
+> **mnote 的根治路线，不是“把现有前端改快一点”，而是“把除了 BlockNote 之外的大多数页面能力从当前重前端壳中迁出，交给 Rust 主导的 server-first Web 架构承载”。**
+
+---
+
+## 10. 外部参考
+
+以下外部资料支持上面的技术判断：
+
+- `axum` 官方文档：
+  https://docs.rs/axum/latest/axum/
+- Leptos Islands 指南：
+  https://book.leptos.dev/islands.html
+- Dioxus Fullstack SSR 文档：
+  https://dioxuslabs.com/learn/0.7/essentials/fullstack/ssr/