217 lines
4.8 KiB
Markdown
217 lines
4.8 KiB
Markdown
# [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` 成为第一阶段必须可用的基础能力
|