mnote/design/old/05-editor-mainline/done/rust-block-editor-command-contract-v0.md

# [recycle] Rust Block Editor Command Contract 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-model-v0.md`
> - `/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/command.rs`
> - `/mnt/Data1T/mnote/rust/crates/core-protocol/src/editor/markdown.rs`

## 1. 目的

本文冻结 `task-054` 的第一阶段命令契约：

- editor command 列表
- editor 到 kernel command 的映射边界
- `Markdown import` / `Markdown export` 的责任边界

第一阶段目标不是一次定义所有高级交互，而是先把最小可执行命令面固定下来。

## 2. 第一阶段 command 列表

第一阶段固定以下命令进入 editor command contract：

- `replace_block`
- `insert_block_after`
- `delete_block`
- `split_block`
- `merge_with_previous`
- `move_block`
- `indent_block`
- `outdent_block`
- `toggle_heading_collapse`
- `attach_reference_token`
- `detach_reference_token`

## 3. 命令语义

### 3.1 `replace_block`

用途：

- 替换块的 `block_type`
- 替换块的 `BlockProps`
- 替换块的 `content_nodes`

第一阶段要求：

- 支持单块粒度更新
- 不要求整页重算

### 3.2 `insert_block_after`

用途：

- 在目标块后插入同级块

第一阶段要求：

- Enter 拆块、加号插入、slash 插入都先归一到 `insert_block_after`

### 3.3 `delete_block`

用途：

- 删除目标块

第一阶段要求：

- 支持是否保留子块的最小策略

### 3.4 `split_block`

用途：

- 在指定 `content_node` 位置拆分当前块

第一阶段要求：

- 支持可选 `text_offset`
- 支持指定 trailing block type

### 3.5 `merge_with_previous`

用途：

- 当前块为空或满足合并条件时，把内容合并到上一块

### 3.6 `move_block`

用途：

- 块重排
- 调整父块
- 调整 after block

第一阶段要求：

- 先承接有限移动与局部重排

### 3.7 `indent_block`

用途：

- 调整有限缩进层级

### 3.8 `outdent_block`

用途：

- 回退一层有限缩进

### 3.9 `toggle_heading_collapse`

用途：

- 切换标题折叠状态

### 3.10 `attach_reference_token`

用途：

- 在指定块内容位置挂接引用 token

### 3.11 `detach_reference_token`

用途：

- 移除指定引用 token

## 4. editor command 到 kernel command 的映射

第一阶段固定口径：

- editor command 是人层和 AI/CLI 的直接操作面
- kernel command 仍是系统底层事实变更面

映射原则：

- `replace_block` 优先映射到块 patch / content update 类 kernel command
- `insert_block_after` 映射到 insert / create block
- `delete_block` 映射到 delete block
- `move_block` 映射到 move block
- `attach_reference_token` / `detach_reference_token` 先映射到块内容 patch，而不是单独扩出新的 kernel mutation

第一阶段允许 lossless 或 lossy mapping，但必须显式记录：

- `editor_command`
- `kernel_command_name`
- `lossy`
- `notes`

## 5. `Markdown import`

第一阶段 `Markdown import` 固定只承担：

- Markdown 文本转 editor block document
- 识别标题、列表、待办、引用、代码块
- 可选识别 `[[page]]` 与 `((block))`

第一阶段不强求：

- 完整 HTML block 保真
- 复杂 front matter 管线
- 富文本 mark 全量映射

`Markdown import` 最小选项：

- mode
- flavor
- reference_token_strategy
- boundary

## 6. `Markdown export`

第一阶段 `Markdown export` 固定只承担：

- 把 editor block document 转成可读 Markdown
- 保留标题、列表、待办、引用、代码块
- 尽量保留 `[[page]]` / `((block))`

第一阶段允许：

- 对未知块做 paragraph fallback
- 对暂不支持块做 lossy export，但要记录 warning

`Markdown export` 最小选项：

- mode
- flavor
- reference_token_strategy
- boundary

## 7. 第一阶段采用矩阵 v0

第一阶段命令与转换采用矩阵固定如下：

| 能力 | 第一阶段口径 |
| --- | --- |
| `replace_block` / `insert_block_after` / `delete_block` | 必做 |
| `split_block` / `merge_with_previous` | 必做 |
| `move_block` / `indent_block` / `outdent_block` | 必做 |
| `toggle_heading_collapse` | 必做 |
| `attach_reference_token` / `detach_reference_token` | 必做 |
| `Markdown import` | 必做 |
| `Markdown export` | 必做 |
| AI 专用高阶复合命令 | 后补 |
| 协作命令 | 延期 |

## 8. 结论

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

- 把 `replace_block`、`insert_block_after`、`delete_block`、`split_block`、`merge_with_previous`、`move_block`、`indent_block`、`outdent_block`、`toggle_heading_collapse`、`attach_reference_token`、`detach_reference_token` 冻结成第一阶段 command contract
- 让 editor command 成为人层、CLI、AI 的统一写接口
- 让 `Markdown import` 和 `Markdown export` 成为第一阶段必须可用的基础能力