# [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 或待删除对象