对齐 Wolai 侧栏体验并收拢设计入库

design/old/05-editor-mainline/process/rust-block-editor-model-v0.md

@@ -0,0 +1,192 @@
+# [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 的长期依赖