mnote/design/old/05-editor-mainline/done/rust-block-editor-adoption-matrix-v0.md

# [recycle] Rust Block Editor Adoption Matrix v0

> 更新时间：2026-04-18
>
> 目标：
> - 冻结 task-050 的参考层采用矩阵
> - 明确 `edita-core`、`blocks`、`kode`、`leptos-tiptap` 的采用边界
> - 说明哪些是采用，哪些是不采用，哪些是部分采用

## 1. 总结结论

第一阶段主线结论：

- `edita-core`：采用
- `blocks`：采用
- `kode`：部分采用
- `leptos-tiptap`：部分采用

同时明确：

- `edita` 的现成 UI 壳：不采用
- `leptos-tiptap` 作为长期主编辑 runtime：不采用

## 2. 采用矩阵

| 参考层 | 结论 | 采用依据 | 不采用或限制依据 | 第一阶段落点 |
| --- | --- | --- | --- | --- |
| `edita-core` | 采用 | `edita-core/src/lib.rs` 已提供 `Editor / Block / Command` 无头抽象，适合承接 Rust command 主链 | 泛型过于宽松，仍需补 `mnote` 自己的 block schema 与 command enum 胶水 | 作为 editor core 命令容器参考 |
| `blocks` | 采用 | `src/block.rs`、`document.rs`、`converters.rs`、`history.rs`、`diff.rs`、`sanitizer.rs` 已覆盖块模型、导入导出、历史、diff/merge | 自定义块型仍需补扩展映射，不能直接原样承载全部 `mnote` 宿主块 | 作为文档模型、转换、history 基线 |
| `kode` | 部分采用 | `kode-core` 提供 buffer/selection/history，`kode-leptos` 提供 `MarkdownEditorComponent` 与 `TreeWysiwygEditor`，`kode-doc` 提供结构树思路 | 自带 doc tree 语义较重，不适合整套替换 `mnote` 事实层 | 作为块内输入器、光标、输入规则参考 |
| `leptos-tiptap` | 部分采用 | `src/api/component.rs`、`use_tiptap_editor.rs`、`runtime/bridge.rs` 对 Leptos 接成熟 runtime 很有参考价值 | 仍基于 Tiptap/JS runtime，不符合 Rust-native 主线 | 仅作 fallback 接缝与 SSR/CSR 接入参考 |

## 3. 采用

### 3.1 `edita-core`：采用

采用理由：

- `Editor<Node, State, Input>` 明确区分状态、块解析、命令执行。
- `Command<State>` 模式非常适合把当前分散在 UI 事件里的块命令抽到 Rust 侧。
- 没有 DOM 依赖，没有 Leptos 依赖，没有 JS runtime 依赖。

建议采用范围：

- `Editor`
- `Block`
- `Command`
- `process_nodes(...)` 体现的“按块处理输入”思路

不直接照搬的部分：

- 直接使用其 UI 示例
- 直接复用其泛型输入节点定义

原因：

- `mnote` 需要的是稳定块命令与文档模型，不是直接拿一个演示型 editor state。

### 3.2 `blocks`：采用

采用理由：

- 当前第一阶段最需要的不是花哨 UI，而是稳定文档模型与格式收口。
- `blocks` 已经提供：
  - `BlockType`
  - `Document`
  - JSON / Markdown / HTML / Plain Text 转换
  - `HistoryManager`
  - `DocumentDiffer`
  - sanitizer

建议采用范围：

- `Block` / `BlockType` 风格的块定义
- `Document` 容器
- converters
- history
- diff / merge
- sanitizer

保留胶水的原因：

- `pageReference`
- `blockReference`
- `advancedTodo`
- `progressMeter`
- `mindmap`
- `onlineTable`

这些都不是 `blocks` 原生块型，需要 `mnote` 自己补扩展层。

## 4. 部分采用

### 4.1 `kode`：部分采用

部分采用理由：

- `kode-core`
  - 可借鉴 text buffer、selection、history、编辑原语
- `kode-leptos`
  - 可借鉴 Leptos 下的编辑组件组织方式
- `kode-doc`
  - 可借鉴结构化树与 token position 思路

适合采用的部分：

- 块内文本输入器
- 光标与选择处理
- `[[`、`#`、`Tab`、`Backspace` 一类输入规则
- Leptos 组件和 editor handle 组织

不直接整套采用的原因：

- `kode-doc` 自身已经是一套更完整的文档树抽象
- `mnote` 当前主线已经有 tree-first kernel，不能再引入第二套事实层

### 4.2 `leptos-tiptap`：部分采用

部分采用理由：

- 它很好地展示了：
  - Leptos 组件如何包第三方编辑器
  - handle 如何暴露命令
  - runtime bridge 如何在 Rust / TS 间对齐
  - SSR / CSR 双模式如何落地

适合采用的部分：

- 组件边界
- handle 设计
- readiness / on_change / on_selection_change 这类信号组织
- fallback runtime 接法

限制：

- 只能作为接缝参考
- 不能作为第一阶段长期事实层

## 5. 不采用

### 5.1 `edita` UI 壳：不采用

不采用原因：

- 当前需要的是 Rust command 核，不是另一个现成 UI。
- `mnote` 已有自己的文档页、阅读态、宿主块与资源系统。
- 直接套 UI 只会引入新的迁移成本。

### 5.2 `leptos-tiptap` 主线路线：不采用

不采用原因：

- 它仍把主事实层放在 Tiptap runtime。
- 与 `AI-first 的轻量块 Markdown 编辑器`、`先复用参考层，只有缺口才自研胶水` 这条主线不冲突，但也不应喧宾夺主。
- 它适合作为 fallback，不适合作为默认长期方案。

## 6. 与当前仓库现状的对应关系

当前仓库的现实情况决定了为什么要这样分：

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/schema.ts`
  - 当前 BlockNote 自定义块已经不少，不能再继续把核心命令绑死在 BlockNote schema。
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocknote-editor.tsx`
  - 现在写链深度耦合 BlockNote、保存接口、重型宿主块副作用。
- `/mnt/Data1T/mnote/wolai-frontend/src/lib/blocks/block-ops-adapter.ts`
  - 当前真正进入稳定工具链的只有 `paragraph` 和 `heading`，说明需要把模型与命令层重新收口。

因此第一阶段最务实的做法是：

1. 采用 `edita-core` 的无头命令组织
2. 采用 `blocks` 的文档模型与格式转换
3. 部分采用 `kode` 的输入与光标处理
4. 部分采用 `leptos-tiptap` 的 Leptos runtime bridge 经验

## 7. 最终冻结

最终冻结口径：

- `edita-core`：采用
- `blocks`：采用
- `kode`：部分采用
- `leptos-tiptap`：部分采用
- `edita` UI 壳：不采用
- `leptos-tiptap` 主线路线：不采用

这份矩阵的作用不是追求“全都用上”，而是保证第一阶段优先复用成熟参考层，只在 `mnote` 特有语义和 kernel 接缝处补最小胶水。