蓝图

数据模型:Kit Data Model(KDM)

Kit Data Model(KDM):kit 共用的、可合并的数据模型,每个修改都有作者、都有历史。

更新于

在 Kition 里,文档不是一个文件,而是一串带作者、可合并的修改历史。 磁盘上的 .docx、.psd、.kboard 是保存和交换文档的方式,不是文档本身。

kit 的文档都建在同一套数据模型上,叫 Kit Data Model(KDM)。底层是 CRDT 库 Loro,但 kit 只依赖 KDM,不依赖 Loro,以后可以换。

一份 schema 定义一种文档

每个 kit 带一份 schema,写清楚文档由哪些对象、哪些字段组成:

json
{
  "kit": "kit.slide",
  "root": "SlideFile",
  "types": {
    "SlideFile": { "fields": { "pages": { "kind": "list", "of": "Page" } } },
    "Page": { "fields": { "layout": { "kind": "ref", "of": "Layout" }, "shapes": { "kind": "list", "of": "Shape" } } },
    "Paragraph": { "fields": { "text": { "kind": "text", "marks": ["bold", "italic", "color"] } } }
  }
}

(model/schema.json 节选,示意,字段做了简化。)这份 schema 是唯一来源:给 AI 的工具参数、对象模型的类型、校验、一致性测试都从它生成。

字段类型决定合并方式

kit 设计 schema 时要逐个字段回答两个问题:哪些属性会被不同的人同时改?哪些属性必须一起变? 前者拆开,后者放在一起。

每种字段类型怎样合并同时发生的修改
类型用在哪两个人同时改
文字(text)正文、文本框、单元格文字按字合并,两人打的字都保留;格式按区间合并
列表(list)页面、段落、图层、轨道两人插入的都保留;同时移动同一项不会变成两份
树(tree)图形编组、图层组、大纲同时移动不会形成环
映射(map)单元格、样式属性、设置不同的键都保留
单值(数字、字符串、引用、素材)颜色、位置、开关最后写的赢,另一方留在历史里

每个对象有稳定的 ID

  • 每个对象有一个全局唯一的 ID,两台设备同时新建也不会撞。
  • 表格的行和列也是有 ID 的对象,公式按 ID 引用,A1 只是显示。所以两人同时插删行列,公式引用、合并单元格都正确;引用被删的行,在所有副本上都变成 #REF!。

合并之后的修复

两个各自合法的修改,合在一起可能不合法:合并单元格跨过了被删的列,时间线上两个片段重叠了。每个 kit 写一个修复规则:

  • 修复必须是合并后状态的确定函数,每台设备算出一样的结果;
  • 修不了、需要人判断的,变成一个冲突对象,界面提示让人选。

不丢东西

  • 事务先校验再应用:命令失败不会留下半截修改,也不会用“回滚”覆盖别人的修改。
  • 认不出的内容原样保留:导入时不认识的部分存成只读对象,导出时写回。
  • 不认识的字段保留:新版本加的字段,旧版本打开时不动它。

实测

(数字来自 2026 年 10 月的实验,原生 Rust,机器负载很高,是上限。)

  • Rust 和 TypeScript 两个版本的副本逐字节一致(约 80 万个浮点数零差异)。
  • 500 页、每页 20 个形状的幻灯片:打开快照约 1 ms,应用 1,000 个远端修改约 19 ms。
  • 10 万行的表格:打开快照约 7 ms,应用 1,000 个远端修改约 118 ms。
  • 共享的收敛测试:2–5 个副本、中日韩输入法和表情文字、拆分合并段落、重复投递、崩溃恢复、随机测试。

协议本身,Kit Harness Protocol(KHP),在 kitharness.org。