mnote/design/old/05-editor-mainline/process/rust-block-editor-blocks-spike-v0.md

[recycle] mnote Rust Block Editor Blocks Spike v0

更新时间：2026-04-18

1. 目标

本 spike 聚焦 blocks 参考层是否适合承担：

• Markdown
• round-trip
• history
• diff
• merge

以及哪些地方存在 缺口。

2. 参考入口

• /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/document.rs
• /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/block.rs
• /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/converters.rs
• /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/history.rs
• /mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/diff.rs

3. 适配性结论

3.1 Markdown

blocks 最适合直接借的是 Markdown 相关思路。

原因：

• 已有文档模型
• 已有 converter facade
• 方向上天然适合 Markdown import/export

这意味着第一阶段不应该自己先写一套新的 Markdown parser 胶水。

3.2 round-trip

Markdown -> blocks -> Markdown round-trip 是 blocks 最容易先验证的一条链。

对 mnote 的价值：

• 可以快速检查标题、列表、待办、引用、代码块的稳定性
• 可以给 task-057 的导入导出提供直接参考

3.3 history

blocks 的 history 适合直接借思路，不建议第一阶段重写。

至少在 undo / redo 的双栈组织上，它比从零发明更稳。

3.4 diff / merge

blocks 的 diff / merge 很适合做 AI-first 和 CLI-first 后续阶段的基础参考。

第一阶段不要求完整采用，但必须明确后续方向，否则 AI 重写链会缺审计基础。

4. 主要缺口

4.1 文档模型仍偏扁平

当前 blocks::Document 是 Vec<Block> 为主。

而 mnote 要的不是简单扁平列表，而是：

• 块树
• children
• 自定义 BlockProps
• 引用 token
• 字符串 ID

这就是第一大 缺口。

4.2 BlockType 与 mnote 目标不完全一致

blocks 的 BlockType 更偏通用编辑器，不直接覆盖：

• page_reference
• block_reference
• media_placeholder
• progress_placeholder

因此不能直接拿来当最终枚举。

4.3 默认 ID 体系不适合

blocks 用 Uuid。

但 mnote 当前更适合：

• DocumentId = String
• BlockId = String

因为要跟现有页面、引用、CLI、AI 命令保持统一可读标识。

5. Spike 结论

blocks 的定位应固定为：

• 采用：Markdown 思路
• 采用：round-trip 参考
• 采用：history 思路
• 采用：diff / merge 思路
• 不直接采用：最终 block model
• 不直接采用：最终 ID 体系

6. 建议落地方式

建议在 mnote-editor-core 中这样接：

• 自定义 EditorDocument
• 自定义 EditorBlockNode
• 自定义 EditorBlockType
• 用 blocks 作为后续 markdown/history/diff/merge 参考或局部依赖

不要反过来把 mnote 的核心模型强行塞进 blocks。

7. 第一阶段保留判断

第一阶段可接受的保守做法：

• 先不把 blocks 作为正式依赖
• 但在文档中冻结：后续 Markdown、history、diff、merge 优先复用其思路

若到 task-057 时验证表明 blocks 已足够稳定，再引正式依赖。

8. 完成判定映射

task-052 的完成判定要求本文显式包含：

• Markdown
• round-trip
• history
• diff
• merge
• 缺口

当前文档已满足这些项。