205 lines
3.4 KiB
Markdown
205 lines
3.4 KiB
Markdown
|
# [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 结果包含最小审计信息
|