# [recycle] Rust Block Editor AI/CLI Tool Contract v0

> 更新时间：2026-04-18

## 1. 目标

这份文档用于冻结 AI 与 CLI 调用 Rust block editor 的最小工具契约。

核心原则只有一条：

- AI 和 CLI 必须调用统一 Rust editor command
- 禁止 AI 再模拟 DOM、鼠标、键盘或前端临时 UI 状态

本 contract 只覆盖文档正文编辑命令层，不覆盖页面壳、阅读态 UI、评论、协作和浏览器事件。

## 2. 边界

调用方分成两类：

- `AI`：页面 AI agent、离线 agent、后端任务
- `CLI`：`mnote-cli editor *` 与后续批处理入口

统一约束如下：

- 文档真相只能通过 Rust editor command 修改
- command 输入必须显式给出 `document_id`
- block 级命令必须显式给出 `block_id`
- selection、焦点、hover 不作为长期真相输入
- 前端 DOM 位置、浏览器 range、contenteditable 状态不进入工具层

## 3. 最小工具面

第一批冻结的 command 如下：

- `insert_block_after`
- `replace_block`
- `delete_block`
- `move_block`
- `set_block_type`
- `indent_block`
- `outdent_block`
- `toggle_heading_collapse`

这些 command 必须同时服务 AI 和 CLI，不允许再维护一套“AI 专用 DOM 写入工具”。

## 4. 输入输出契约

统一输入头：

- `document_id`
- `workspace_id?`
- `request_id?`
- `trace_id?`
- `actor_id`
- `actor_type`
- `reason?`

统一输出头：

- `ok`
- `document_id`
- `applied_command`
- `revision?`
- `changed_block_ids`
- `snapshot?`
- `audit`

### 4.1 `insert_block_after`

输入：

- `after_block_id?`
- `block`

输出：

- `inserted_block_id`
- `changed_block_ids`

### 4.2 `replace_block`

输入：

- `block_id`
- `block`

输出：

- `changed_block_ids`

### 4.3 `delete_block`

输入：

- `block_id`

输出：

- `deleted_block_id`
- `changed_block_ids`

### 4.4 `move_block`

输入：

- `block_id`
- `target_parent_id?`
- `after_block_id?`

输出：

- `changed_block_ids`

### 4.5 `set_block_type`

输入：

- `block_id`
- `block_type`
- `props?`

输出：

- `changed_block_ids`

### 4.6 `indent_block`

输入：

- `block_id`

输出：

- `changed_block_ids`

### 4.7 `outdent_block`

输入：

- `block_id`

输出：

- `changed_block_ids`

### 4.8 `toggle_heading_collapse`

输入：

- `block_id`

输出：

- `changed_block_ids`
- `collapsed`

## 5. 安全与约束

- AI 不得假设“当前光标在某处”，必须使用显式 `block_id`
- AI 不得伪造前端已存在的 block id
- CLI 和 AI 都不得绕过 command 直接写原始内容 JSON
- 若命令需要目标 block，但目标不存在，必须返回结构化错误
- 若缩进、移动会破坏树结构，必须拒绝执行

## 6. 审计

每次 command 至少记录：

- `request_id`
- `trace_id`
- `actor_id`
- `actor_type`
- `document_id`
- `command_name`
- `target_block_id?`
- `changed_block_ids`
- `reason?`

## 7. CLI 对齐

CLI 必须与 AI 共用同一组 command 名称与输入结构。

最低要求：

- CLI 能直接调用上述 command
- CLI 返回与 AI 一致的结构化结果
- CLI 可输出变更后的最小 `snapshot`

## 8. 验收标准

满足以下条件即可视为 v0 可用：

- AI 写链不再依赖 DOM 模拟
- CLI 与 AI 共用同一批 command 名称
- `insert_block_after`
- `replace_block`
- `delete_block`
- `move_block`
- `set_block_type`
- `indent_block`
- `outdent_block`
- `toggle_heading_collapse`
  都有明确输入输出字段
- command 结果包含最小审计信息