3.4 KiB
3.4 KiB
[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_afterreplace_blockdelete_blockmove_blockset_block_typeindent_blockoutdent_blocktoggle_heading_collapse
这些 command 必须同时服务 AI 和 CLI，不允许再维护一套“AI 专用 DOM 写入工具”。
4. 输入输出契约
统一输入头：
document_idworkspace_id?request_id?trace_id?actor_idactor_typereason?
统一输出头：
okdocument_idapplied_commandrevision?changed_block_idssnapshot?audit
4.1 insert_block_after
输入：
after_block_id?block
输出：
inserted_block_idchanged_block_ids
4.2 replace_block
输入：
block_idblock
输出：
changed_block_ids
4.3 delete_block
输入：
block_id
输出：
deleted_block_idchanged_block_ids
4.4 move_block
输入：
block_idtarget_parent_id?after_block_id?
输出：
changed_block_ids
4.5 set_block_type
输入：
block_idblock_typeprops?
输出：
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_idscollapsed
5. 安全与约束
- AI 不得假设“当前光标在某处”，必须使用显式
block_id - AI 不得伪造前端已存在的 block id
- CLI 和 AI 都不得绕过 command 直接写原始内容 JSON
- 若命令需要目标 block，但目标不存在，必须返回结构化错误
- 若缩进、移动会破坏树结构，必须拒绝执行
6. 审计
每次 command 至少记录：
request_idtrace_idactor_idactor_typedocument_idcommand_nametarget_block_id?changed_block_idsreason?
7. CLI 对齐
CLI 必须与 AI 共用同一组 command 名称与输入结构。
最低要求：
- CLI 能直接调用上述 command
- CLI 返回与 AI 一致的结构化结果
- CLI 可输出变更后的最小
snapshot
8. 验收标准
满足以下条件即可视为 v0 可用：
- AI 写链不再依赖 DOM 模拟
- CLI 与 AI 共用同一批 command 名称
insert_block_afterreplace_blockdelete_blockmove_blockset_block_typeindent_blockoutdent_blocktoggle_heading_collapse都有明确输入输出字段- command 结果包含最小审计信息