mnote/design/old/05-editor-mainline/process/rust-block-editor-blocknote-migration-v1.md

[recycle] BlockNote Migration Plan v1

更新时间：2026-04-18

1. 目标

这份文档用于冻结从 BlockNote 主路径迁移到 Rust block editor 的最小迁移顺序。

目标不是一次性删除所有旧代码，而是：

• 先让主文档页默认切到新 Rust editor 壳
• 再把 BlockNote 降到 compat/debug
• 最后清理旧依赖和主线耦合

2. 当前盘点

当前主路径仍直接依赖下面这些入口或依赖：

• @blocknote/core
• @blocknote/react
• @blocknote/mantine
• blocknote-editor.tsx
• schema.ts
• HocuspocusProvider
• Yjs

主路径宿主文件主要是：

• wolai-frontend/src/components/editor/document-content.tsx
• wolai-frontend/src/components/editor/blocknote-editor.tsx
• wolai-frontend/src/components/editor/schema.ts

3. 迁移分层

迁移固定分三层：

• 主路径 由 Rust block editor 接管
• compat 保留旧 BlockNote 入口，供临时回退
• debug 保留最小诊断入口，帮助排障

禁止继续把 BlockNote 当成默认编辑器。

4. 内容格式迁移策略

第一阶段不要求一次性消灭所有旧内容格式。

固定策略如下：

• 主写链以 Rust editor command 和 Rust document model 为准
• 旧 BlockNote JSON 通过兼容 codec 读取
• 写回时优先生成 Rust 侧统一结构
• 必要时保留从旧格式到新格式的单向迁移适配

重点对象：

• 段落
• 标题
• list/todo
• pageReference
• blockReference
• 附件和重型自定义块

5. 入口切换顺序

第一步：

• 在文档页入口切到 mnoteWebDocumentShellEnabled
• 默认走 mnote-web /document
• 保留 ?editor=compat 回退参数

第二步：

• document-content.tsx 继续保留为 compat 宿主壳
• blocknote-editor.tsx 继续保留为 compat 编辑器实现

第三步：

• 新主编辑器稳定后，再把主路径对 schema.ts、HocuspocusProvider、Yjs 的依赖收缩到 compat/debug

6. 依赖收敛

迁移完成前后要明确区分：

• 主路径是否仍依赖 @blocknote/core
• 主路径是否仍依赖 blocknote-editor.tsx
• 主路径是否仍依赖 HocuspocusProvider
• 主路径是否仍依赖 Yjs

最终要求：

• compat/debug 允许暂时保留
• 主路径不再依赖以上能力

7. 风险

主要风险如下：

• 旧页面内容与新结构双写不一致
• history / snapshot / TOC / stats 边界退化
• 重型块在新主路径下缺少最小宿主能力
• 回退入口不明确导致线上排障困难

8. 回退策略

必须保留显式回退：

• 文档页参数级 compat 入口
• 旧 BlockNote 组件继续可挂载
• debug 场景可直接验证旧壳

在没有确认新主路径稳定前，不得直接删除 compat/debug。

9. 验收标准

满足以下条件即可视为 migration v1 达标：

• 主文档页默认落到新 Rust editor 壳
• compat/debug 入口仍可独立使用
• blocknote-editor.tsx 不再是默认主路径
• schema.ts 不再决定默认主编辑器
• @blocknote/core
• blocknote-editor.tsx
• schema.ts
• HocuspocusProvider
• Yjs 已被明确标记为 compat/debug 或待删除对象