# [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
- 缺口

当前文档已满足这些项。