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 成为第一阶段必须可用的基础能力