# 5-3 [recycle] Tiptap + `leptos-tiptap` + Rust Kernel 迁移清单 v1

> 更新时间：2026-04-19
>
> 这份文档已经按当前现实重排：
>
> `localhost:8123` 证明了 `Leptos + leptos-tiptap` 这条路线可行，当前不再需要继续证明“能不能做出一个像 Tiptap 的 spike”。
>
> 当前最关键的问题是：
>
> **它还没有接入主编辑器，所以真实页面中的加载、保存、路由、投影、权限、布局、回归 bug 都还没有暴露完全。**

## 1. 当前结论

这条线现在应当明确收口到下面这个口径：

1. 体验 benchmark 继续参考 `Tiptap` 官方 `notion-like-editor`。
2. 浏览器编辑 runtime 继续使用 `leptos-tiptap`。
3. 文档真相、块语义、引用语义、保存合同继续由 Rust/kernel 掌握。
4. 当前阶段不再平均推进所有功能，而是先完成 `P0.5`：
   **把当前编辑器接入主编辑器，并接上 Rust truth。**

这意味着：

- 不是继续打磨孤立 spike 页面。
- 不是继续围绕 runtime shell 做体验修补。
- 不是先做一长串 Wolai 对标增强项。
- 而是先让这套编辑器进入真实文档链路。

## 2. 参考优先级

主参考优先级固定如下：

1. `Tiptap` 官方 `notion-like-editor`
2. `leptos-tiptap`
3. `core-protocol` / `mnote-editor-core` / `mnote-web`
4. `blocks`
5. `kode`

明确降级说明：

- `mnote-next` 只保留为历史样本，不作为当前主参考。
- `edita-core` 只保留为 Rust-native 块模型参考，不作为当前体验 benchmark。
- `runtime shell` 只保留为 spike/debug，不再作为正式编辑器目标页。

## 3. 本地参考位置

### 3.1 官方体验 benchmark

- 模板入口：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/page.tsx`
- 主编辑器：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/components/notion-like-editor.tsx`
- 浮动工具条：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-templates/notion-like/components/notion-like-editor-toolbar-floating.tsx`
- slash 菜单：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/slash-dropdown-menu/slash-dropdown-menu.tsx`
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/slash-dropdown-menu/use-slash-dropdown-menu.ts`
- 块菜单与手柄：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-ui/drag-context-menu/drag-context-menu.tsx`
- 缩进扩展：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-notion-like-registry/materialized/tiptap-extension/indent-extension.ts`

### 3.2 Leptos 运行时桥接参考

- `leptos-tiptap` crate：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/leptos-tiptap/Cargo.toml`
- Rust 扩展枚举：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/leptos-tiptap/src/api/extensions.rs`
- Rust 命令 API：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/leptos-tiptap/src/api/commands.rs`
- 运行时注册：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/leptos-tiptap/src/runtime/registration.rs`
- JS 扩展实现：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/leptos-tiptap/tiptap/src/extensions/`

### 3.3 `mnote` 当前主线落点

- 当前 `Leptos + Tiptap` spike：
  `/mnt/Data1T/mnote/rust/spikes/leptos-tiptap-spike/src/main.rs`
- Rust editor 模型：
  `/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/model.rs`
- Rust editor 命令：
  `/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/command.rs`
- Rust editor core：
  `/mnt/Data1T/mnote/rust/crates/mnote-editor-core/src/model.rs`
  `/mnt/Data1T/mnote/rust/crates/mnote-editor-core/src/command.rs`
- Rust 文档与查询桥：
  `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/documents.rs`
  `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/query_support.rs`
  `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/editor.rs`

### 3.4 辅助参考

- `blocks`：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/lib.rs`
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/history.rs`
- `kode`：
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/kode/kode-leptos/src/markdown_editor_component.rs`
  `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/kode/kode-leptos/src/wysiwyg/tree_editor.rs`

## 4. 当前真实基线

### 4.1 已经完成的基础验证

当前 spike 已经证明下面这些能力可以跑起来：

- 真正的 Tiptap surface 已可渲染
- `paragraph / heading / bullet list / ordered list / task list / quote / code block / divider` 可编辑
- slash 菜单已具备最小产品级入口
- 浮动工具条已具备常用文本操作
- 左侧块手柄、块菜单、拖拽、`turn into` 已有一版
- reload 后结构不再退化成纯文本
- `get_html()` / `get_json()` / `on_change` 可用

### 4.2 当前真正缺的不是“再做一个 spike 功能”

当前真正缺的是：

- 还没进入主编辑器
- 还没接上正式 Rust 保存链路
- 还没建立稳定 block id 真相边界
- 还没把当前 schema 与 `EditorBlockType` / `EditorCommand` 对齐成正式合同

因此，下面这些事项都不应继续排在前面：

- Markdown 导入导出回归
- `kode` 分层整理
- 完整表格
- 协作
- Tiptap Cloud AI

## 5. 当前阶段划分

新的阶段划分改为：

- `P0.5`：接入主编辑器，接上 Rust truth
- `P1`：补齐成为正式主编辑器所需的结构能力
- `P1.5`：对标 Wolai 的操作层与块体验增强
- `P2`：增强项与后置兼容项

其中：

**当前只重点规划 `P0.5`。**

`P1 / P1.5` 先只保留方向，不在本轮继续展开成大而全 checklist。

## 6. P0.5 Checklist

### 6.1 目标

`P0.5` 的目标不是继续“把 demo 做得更像官方模板”，而是：

> **把当前已经可用的 `leptos-tiptap` 编辑器接入真实主编辑器链路，让 bug 在真实环境里暴露，并让 Rust 成为正式保存与块语义边界。**

### 6.2 完成标准

满足下面条件，才算 `P0.5` 完成：

1. 默认文档编辑路径使用真正的 Tiptap/Leptos 编辑器，而不是 runtime shell。
2. 文档打开、刷新、保存、重新进入后，结构保持稳定。
3. 块级结构与 Rust `EditorBlockDocument` 有明确映射。
4. 块的身份标识不再依赖前端临时索引。
5. 当前已有的 slash / toolbar / handle / turn into 能在真实页面中工作。

### 6.3 Checklist

- [ ] 明确主编辑器接入点。
  目标：不再让 `localhost:8123` 这种孤立 spike 充当“完成态”。
  要求：确定真实文档页的接入入口，后续 bug 统一在主页面暴露和验证。

- [ ] 明确 runtime shell 退场策略。
  参考：`/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/editor.rs`
  原则：该路线只保留为 debug/prototype，不再作为正式文档页 benchmark。

- [ ] 将当前 `leptos-tiptap` 编辑器嵌入真实页面壳。
  要求：进入真实文档路由、真实布局、真实加载链，而不是单独的实验页。
  目的：尽早暴露首屏、刷新、回填、焦点、布局、侧栏联动、回归问题。
  补充口径：这里指的是把 `8123` 那套真实 `Leptos + Tiptap` 页面壳 / editor stage 接进主编辑器，而不是另做一套长得不像 `8123` 的 host。

- [ ] 建立正式 load/save 边界。
  参考：`/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/documents.rs`
  参考：`/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/model.rs`
  要求：前端 runtime 输入与 Rust 真相之间有单一转换边界，不再引入 shell 专用格式。

- [ ] 明确 `EditorBlockDocument -> Tiptap doc -> EditorBlockDocument` 的最小映射。
  `P0.5` 至少覆盖：
  `Paragraph`、`Heading`、`BulletListItem`、`NumberedListItem`、`Todo`、`Quote`、`CodeBlock`
  目标：先保证主链常用块类型可稳定往返，不追求一次做完整能力面。

- [ ] 提前引入稳定 block id 策略。
  参考：官方 `UniqueID.configure(...)`
  参考：`/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/model.rs`
  原则：Rust `EditorBlock.block_id` 是最终真相；`UniqueID` 只作为浏览器 runtime 辅助，不应反过来成为持久化规则。

- [ ] 对齐最小命令合同，而不是先做完所有体验功能。
  参考：`/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/command.rs`
  `P0.5` 优先对齐：
  `ReplaceBlock`
  `InsertBlockAfter`
  `DeleteBlock`
  `SplitBlock`
  `MergeWithPrevious`
  `MoveBlock`
  说明：`IndentBlock`、`OutdentBlock`、`ToggleHeadingCollapse` 保留到后续阶段，不作为 `P0.5` 阻塞项。

- [ ] 复用当前已有的 slash / toolbar / handle / turn into，而不是重写第二遍。
  落点：以现有 spike 行为为基础迁入主页面，再按官方行为微调。
  原则：当前阶段优先“接入”，不是再做一轮自娱自乐式 UI 重构。

- [ ] 定义未支持能力的降级策略。
  当前明确未进入 `P0.5`：
  图片上传、表格、页面引用、块引用、heading collapse、普通块缩进增强
  要求：未支持时要有显式降级，不允许用临时假功能污染正式合同。

- [ ] 建立主编辑器验收口径。
  最低验收应覆盖：
  打开文档
  编辑常用块
  slash 插入块
  turn into 切换块类型
  刷新后结构保留
  再次进入后结构保留
  目的：从现在开始，bug 判断以主编辑器为准，而不是以 spike 页面为准。

## 7. P1 方向

`P1` 只保留方向，不在这一轮继续扩成大 checklist。

`P1` 解决的是“成为正式主编辑器还缺的结构能力”：

- 页面引用 / 块引用
- heading collapse 与树语义对齐
- 最小图片/附件桥接
- 更完整的 Rust save pipeline 与局部更新

其中优先级判断如下：

1. 页面引用 / 块引用
2. heading collapse
3. 最小图片/附件桥接
4. 其它结构增强

## 8. P1.5 方向

`P1.5` 才进入真正的 Wolai 操作层对标。

这一阶段再重新规划下面这些体验增强：

- 手柄行为优化
- `turn into page`
- 普通块缩进体验
- 块菜单分组与文案优化
- 更细的 hover / selection / anchor 行为
- 更接近 Wolai 的块级交互细节

说明：

这些都值得做，但它们不应先于“成为主编辑器”发生。

## 9. P2 方向

`P2` 才处理后置增强与兼容项：

- 表格评估
- 更完整的图片上传链
- Markdown 导入导出回归
- `blocks` 差异校验
- `kode` 组件分层整理
- AI 命令入口

## 10. 当前不进入主线前排的事项

下面这些项不删除，但从主 checklist 前排降级：

- Markdown 导入导出回归
  作用是 compatibility/testing，不直接解锁主编辑器接入。

- `kode` 组件分层参考
  它是实现注记，不是交付里程碑。

- 完整表格
  当前不是高频需求，也不是主编辑器切流前置项。

- 协作与 Tiptap Cloud AI
  与当前 AI-first / Rust-kernel-first 路线不一致。

## 11. 一句话收口

当前正确路线不是继续把 spike 做得更漂亮，而是：

**先把现有 `leptos-tiptap` 编辑器接入主编辑器，并用 Rust 接管正式保存与块真相；等这一步完成后，再系统规划 Wolai 对标体验增强。**
