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 接缝处补最小胶水。