# [recycle] Rust Block Editor Model v0

> 更新时间：2026-04-18
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/old/05-editor-mainline/process/ai-first-rust-block-editor-baseline-v1.md`
> - `/mnt/Data1T/mnote/design/old/05-editor-mainline/process/rust-block-editor-phase0-baseline-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/edita/edita-core/src/lib.rs`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocks/src/document.rs`
> - `/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/model.rs`

## 1. 目的

本文冻结 `task-053` 的第一阶段 Rust block editor 模型口径。

目标不是一次定义最终全文档系统，而是先确定：

- 首批 Rust block type
- `BlockProps` 的最小字段面
- `reference token` 的表示方式
- `content_node` 的载荷格式
- 哪些内容明确退出对 BlockNote JSON 的长期依赖

## 2. 第一阶段 block type

第一阶段固定以下块类型进入 canonical model：

- `paragraph`
- `heading`
- `bullet_list_item`
- `numbered_list_item`
- `quote`
- `todo`
- `code_block`
- `page_reference`
- `block_reference`

补充说明：

- `paragraph` 是默认文本块。
- `heading` 是标题块，级别收敛到 `BlockProps.heading_level`。
- `bullet_list_item` 与 `numbered_list_item` 先保留为列表项，而不是先做复杂 list container。
- `todo` 用来承接当前 `advancedTodo` 的第一阶段简化版。
- `page_reference` 与 `block_reference` 先作为稳定引用块进入模型。

下面这些不进入第一阶段 canonical model，只保留 placeholder 或 compat：

- `media`
- `progressMeter`
- `mindmap`
- `onlineTable`

## 3. `BlockProps`

第一阶段 `BlockProps` 固定为轻量可扩展对象。

核心字段：

- `indent`
- `heading_level`
- `checked`
- `collapsed`
- `language`
- `reference_target_id`
- `reference_label`
- `reference_token_strategy`
- `extra`

固定口径：

- `indent` 表示有限缩进层级，不承诺长期树协议。
- `heading_level` 只对 `heading` 生效。
- `checked` 只对 `todo` 生效。
- `collapsed` 只对 `heading` 生效，用于折叠标题。
- `language` 只对 `code_block` 生效。
- `reference_target_id` 与 `reference_label` 服务 `page_reference` / `block_reference`。
- `extra` 只用于迁移期兼容字段，不能成为长期语义事实源。

## 4. `reference token` 策略

第一阶段引用 token 固定区分两类：

- `page_reference`
- `block_reference`

第一阶段 token strategy 固定支持三种：

- `double_bracket`
- `double_paren`
- `inline_chip`

对应语义：

- `double_bracket` 对应 `[[page]]`
- `double_paren` 对应 `((block))`
- `inline_chip` 只用于 UI 渲染或迁移期兼容，不作为长期文本事实源

引用 token 最小字段：

- `kind`
- `strategy`
- `target_id`
- `label`
- `raw_token`

## 5. `content_node` 载荷格式

第一阶段 `content_node` 是 block 内内容的最小结构单元。

固定 payload 类型：

- `text`
- `hard_break`
- `reference_token`

### 5.1 `text`

`text` 节点字段：

- `text`
- `marks`

`marks` 第一阶段只支持：

- `bold`
- `italic`
- `underline`
- `strike`
- `code`

### 5.2 `hard_break`

`hard_break` 用于显式换行，不引入复杂段内结构树。

### 5.3 `reference_token`

`reference_token` 节点直接挂稳定 token 对象，而不是把引用仅留在原始文本里。

## 6. 块对象与文档对象

第一阶段 canonical block 结构固定为：

- `block_id`
- `block_type`
- `props`
- `content_nodes`
- `child_block_ids`

第一阶段 canonical document 结构固定为：

- `document_id`
- `root_block_ids`
- `blocks`

设计原则：

- `blocks` 先按稳定数组序列输出，便于命令执行和导入导出。
- `child_block_ids` 先表达父子关系，不强求复杂树索引结构。
- `content_nodes` 替代对 BlockNote inline JSON 的长期依赖。

## 7. 与 BlockNote JSON 的边界

第一阶段固定口径：

- BlockNote JSON 只作为迁移期外部格式
- Rust editor model 才是长期事实层
- `BlockProps`、`content_node`、`reference token` 必须能独立表达核心语义

换句话说：

- 可以保留 `BlockNote JSON -> Rust model` 适配器
- 不能继续把 BlockNote JSON 当作长期 canonical schema

## 8. 第一阶段不解决的事

下面这些明确不在 `task-053` 解决：

- 多人协作状态
- 复杂 mark 树
- 富媒体完整属性系统
- `mindmap` / `onlineTable` 的完整内嵌编辑语义
- 完整批量选择与多块复制粘贴

## 9. 结论

`task-053` 的固定口径是：

- 用首批 `paragraph`、`heading`、`bullet_list_item`、`todo`、`page_reference`、`block_reference` 等块型建立 Rust canonical model
- 用 `BlockProps` 收拢最小块属性
- 用 `reference token` 固定 `[[page]]` / `((block))` 的稳定表示
- 用 `content_node` 承接块内文本与引用
- 从这一阶段开始退出对 BlockNote JSON 的长期依赖