delta-ot

基于 Quill Delta 的完整协同编辑系统，实现完整的协同编辑解决方案，并且有完整的测试覆盖。但是这个项目是一个研究学习性质的项目，所以不要直接用于生产环境方案，请谨慎使用。

关于项目

这是一个基于 Quill Delta 的 OT（Operational Transformation）协同编辑系统，实现了完整的实时协同编辑功能。项目采用 Monorepo 架构，包含协同算法核心、文档编辑器、服务端通信等完整模块。

💡 协同编辑方案对比：如果你对 CRDT（Conflict-free Replicated Data Type）方案感兴趣，可以查看我的另一个项目 butterfly - 基于 Yjs 的 CRDT 协同编辑实现。两个项目分别展示了 OT 和 CRDT 两种不同的协同编辑技术路线。

项目特色

完整的 OT 算法实现：基于 Quill Delta 的操作转换算法，支持插入、删除、格式变更等所有编辑操作
生产级架构设计：模块化设计，高内聚低耦合，易于扩展和维护
丰富的测试覆盖：包含 50+ 个测试用例，覆盖所有常见的协同编辑场景
完整的文档体系：每个模块都有详细的设计文档和实现说明
实时协同能力：支持多用户实时编辑，自动解决冲突
技术路线对比：与 butterfly 项目形成 OT vs CRDT 的完整技术对比

系统架构

graph TD
    A[Document Editor] --> B[Collaborate Core]
    B --> C[OT Engine]
    B --> D[Session Manager]
    B --> E[Transport Layer]
    E --> F[WebSocket Server]
    F --> G[Database]
    
    H[Common Utils] --> A
    H --> B
    H --> F

包结构详解

`@delta-ot/collaborate` - 协同算法核心

协同编辑的核心算法模块，提供纯逻辑的 OT 实现，无 UI 依赖。

核心功能

OT 引擎：实现操作转换算法，解决并发编辑冲突
会话管理：管理用户编辑会话，处理本地和远程操作
文档模型：基于 Delta 的文档状态管理
传输层：WebSocket 通信封装

目录结构

collaborate/
├── engine/           # OT 引擎核心算法
│   ├── OTEngine.ts   # 操作转换实现
│   └── README.md     # 引擎设计文档
├── session/          # 协同会话管理
│   ├── OTSession.ts  # 会话控制器
│   └── README.md     # 会话设计文档
├── model/            # 文档模型
│   ├── DocumentModel.ts
│   └── README.md
├── transport/        # 传输层
│   ├── WebSocketClient.ts
│   └── README.md
├── tests/            # 测试用例
│   └── engine/       # OT 算法测试
└── utils/            # 工具函数

设计文档

开发命令

cd packages/collaborate
pnpm test          # 运行测试
pnpm test:watch    # 监听模式测试
pnpm build         # 构建包

`@delta-ot/document` - 文档编辑器

基于 Vue 3 + Quill 的现代化文档编辑器，提供完整的协同编辑 UI 体验。

核心功能

Quill 编辑器集成：基于 Quill 2.0 的富文本编辑器
协同编辑 UI：实时显示多用户编辑状态
测试实验室：内置协同编辑测试框架
用户管理：完整的用户登录和权限管理

技术栈

Vue 3 + TypeScript
Quill 2.0 编辑器
Element Plus UI 组件
Tailwind CSS 样式
Pinia 状态管理

目录结构

document/
├── src/
│   ├── components/     # Vue 组件
│   │   ├── Document/   # 文档组件
│   │   ├── Editor/     # 编辑器组件
│   │   └── ListItem/   # 列表项组件
│   ├── controllers/    # 控制器层
│   │   ├── DocumentManager.ts
│   │   ├── CollaborateController.ts
│   │   └── WebsocketController.ts
│   ├── pages/          # 页面组件
│   ├── test-lab/       # 测试实验室
│   └── store/          # 状态管理

开发命令

cd packages/document
pnpm dev          # 启动开发服务器

`service` - 服务端

基于 Node.js + Koa 的协同编辑服务端，提供 WebSocket 通信和 HTTP API。

核心功能

WebSocket 服务：实时协同编辑通信
文档会话管理：多文档并发编辑支持
用户认证：JWT 认证和权限管理
数据持久化：MySQL 数据库存储

技术栈

Node.js + TypeScript
Koa 框架
MySQL + Sequelize ORM
Redis 缓存
WebSocket 通信

目录结构

service/
├── src/
│   ├── controllers/    # 控制器
│   ├── sessions/       # 文档会话管理
│   ├── socket/         # WebSocket 处理
│   ├── db/            # 数据库模型
│   └── middleware/    # 中间件

开发命令

cd packages/service
pnpm dev          # 启动开发服务器

`common` - 通用工具

项目通用工具包，提供日志系统等基础功能。

核心功能

全局日志系统：支持多客户端、多级别的日志管理
工具函数：项目通用的工具函数

设计文档

日志系统设计

快速开始

环境要求

Node.js >= 18
pnpm >= 8
MySQL >= 8.0
Redis >= 6.0

TODO - 协同编辑功能完善计划

本项目当前是一个研究学习性质的项目，以下是将其发展为实用的协同编辑系统需要完成的核心功能清单。

协同编辑体验优化（最高优先级）

协同功能增强

富文本编辑器增强

用户体验提升

界面优化

交互体验

快捷键

系统优化

性能优化

安全加固

日志系统

文档管理功能（后期完善）

文档管理

用户权限管理

优先级

第一阶段（编辑器基础能力保障）

撤销重做系统优化
复制粘贴系统完善
剪贴板管理基础设施
选择操作优化

💡 开发建议：

撤销重做系统：协同编辑环境下的撤销重做需要特殊处理，确保操作一致性
复制粘贴系统：需要处理复杂的格式转换，建立完善的剪贴板管理基础设施
剪贴板管理：作为复制粘贴的基础设施，需要支持多种格式和跨应用兼容
选择操作：优化文本选择和跨元素选择，提升编辑体验

第二阶段（协同体验优化）

实时光标显示和用户状态
Markdown语法支持
高级内容格式（表格、图片、视频、代码块）
编辑器插件和智能功能

💡 开发建议：

用户在线状态：基于现有WebSocket架构，技术难度适中，用户体验提升明显
Markdown支持：现代文档编辑器标配，建议开发Quill插件实现语法转换
表格功能：优先实现基础表格编辑，再逐步添加格式化功能
图片处理：支持拖拽上传、基础调整，为后续高级功能打基础

第二阶段（界面体验）

界面改进（响应式、深色模式）
移动端适配
快捷操作（快捷键、右键菜单）
协同反馈优化

💡 开发建议：

响应式设计：优先适配桌面端不同分辨率，再考虑移动端
深色模式：使用CSS变量实现主题切换，与现有Tailwind CSS集成
快捷键系统：建立统一的快捷键管理机制，支持自定义配置
协同反馈：在现有光标同步基础上，添加操作状态和网络状态提示

第三阶段（系统完善）

性能优化（大规模文档支持）
日志完善
安全加固

💡 开发建议：

性能优化：基于现有100+测试用例，识别性能瓶颈，优先优化高频操作
日志系统：扩展现有Logger系统，添加操作审计和错误追踪功能
安全加固：在现有JWT认证基础上，添加操作权限验证和数据加密

第四阶段（管理功能）

文档版本管理
基础权限控制
文档导入导出
链接分享功能

💡 开发建议：

版本管理：基于现有数据持久化架构，实现增量版本存储
权限控制：建立细粒度权限模型，支持文档级别的访问控制
导入导出：优先支持Markdown格式，再扩展其他格式
分享功能：实现安全的链接分享机制，支持权限控制

🚀 立即开始建议

推荐第一个功能：撤销重做系统优化

为什么选择这个功能：

✅ 基础能力保障：撤销重做是编辑器的基础功能，直接影响用户体验
✅ 协同编辑特殊性：协同环境下的撤销重做需要特殊处理，确保操作一致性
✅ 技术挑战适中：基于现有OT算法，需要扩展操作历史管理
✅ 用户需求强烈：撤销重做是用户最常用的基础操作之一

技术实现要点：

操作历史管理：记录和追踪所有编辑操作
协同撤销重做：确保多用户环境下的操作一致性
操作合并：智能合并连续的撤销重做操作
状态同步：在协同编辑中同步撤销重做状态

推荐第二个功能：复制粘贴系统完善

为什么选择这个功能：

✅ 基础能力保障：复制粘贴是编辑器的核心功能，需要处理复杂格式
✅ 技术挑战重要：需要建立完善的剪贴板管理基础设施
✅ 跨应用兼容：需要处理来自不同应用的格式转换
✅ 用户体验关键：复制粘贴的流畅性直接影响编辑效率

技术实现要点：

剪贴板数据解析：处理HTML、纯文本、图片等多种格式
格式转换器：在不同格式间进行转换
跨应用兼容：支持从Word、浏览器等应用复制内容
剪贴板历史：管理剪贴板历史记录

推荐第三个功能：用户在线状态

为什么选择这个功能：

✅ 技术基础扎实：基于现有WebSocket架构，开发难度适中
✅ 用户体验提升明显：用户能看到谁在线、谁在编辑，增强协同感
✅ 为后续功能打基础：为权限管理、实时通知等功能做准备
✅ 开发周期短：预计1-2周可完成MVP版本

技术实现要点：

服务端：扩展WebSocket消息类型，维护在线用户列表
前端：创建在线用户列表组件，实时更新用户状态
状态管理：在Pinia store中管理在线用户状态

推荐第二个功能：Markdown语法支持

为什么选择这个功能：

✅ 现代编辑器标配：提升编辑器的实用性和竞争力
✅ 用户需求强烈：Markdown是文档编辑的主流格式
✅ 技术实现清晰：可开发Quill插件实现语法转换
✅ 渐进式开发：先实现基础语法，再逐步完善

技术实现要点：

Quill插件开发：Markdown语法解析和转换
实时预览：支持边写边预览模式
快捷键支持：常用Markdown语法的快捷键

推荐第三个功能：表格编辑

为什么选择这个功能：

✅ 实用性高：表格是文档编辑的重要需求
✅ 技术挑战适中：基于Quill的表格模块扩展
✅ 协同效果好：多用户同时编辑表格的协同体验
✅ 为复杂功能打基础：为后续图片、视频等功能积累经验

📋 开发原则

1. 模块化开发

保持现有的模块化架构
每个新功能都应该是独立的模块
遵循高内聚低耦合的设计原则

2. 测试驱动

为新功能编写测试用例
确保现有测试覆盖率不降低
在测试实验室中添加新功能的测试场景

3. 渐进式增强

先实现核心功能，再逐步添加高级特性
保持向后兼容性
避免过度复杂化

4. 用户体验优先

优先实现用户感知明显的功能
注重交互细节和视觉反馈
保持界面的一致性和简洁性

5. 基础能力优先

优先保障编辑器的基础功能（撤销重做、复制粘贴等）
确保基础功能的稳定性和一致性
在基础能力完善后再进行功能扩展

安装依赖

# 安装 pnpm
npm install -g pnpm

# 克隆项目
git clone https://github.com/hzjswlgbsj/delta-ot.git
cd delta-ot

# 安装依赖
pnpm install

数据库配置

# 导入数据库结构
mysql -u root -p < delta_ot_document.sql

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接信息

启动服务

# 启动服务端
cd packages/service
pnpm dev

# 启动前端（新终端）
cd packages/document
pnpm dev

测试与验证

OT 算法测试

项目包含完整的 OT 算法测试套件，覆盖所有协同编辑场景：

cd packages/collaborate
pnpm test

测试用例分类

基础操作测试：插入、删除、格式变更
冲突解决测试：并发编辑冲突处理
复杂场景测试：多用户、多操作组合
边界情况测试：特殊位置和格式处理

详细测试用例说明：transform-cases.md

协同编辑测试实验室

前端内置了完整的协同编辑测试框架：

访问 /test-lab 页面
选择测试用例
观察多客户端协同编辑效果
验证最终一致性

测试实验室说明：测试实验室文档

学习资源

API 文档

Postman 集合：Delta Document API

📧 访问说明：Postman 集合需要提供邮箱联系我手动邀请。如需访问，请联系我：联系页面

核心概念

技术路线对比

OT 方案：本项目 - 基于 Quill Delta 的操作转换算法
CRDT 方案：butterfly - 基于 Yjs 的无冲突复制数据类型

各模块职责说明

测试指南

开发指南

项目结构

delta-ot/
├── packages/
│   ├── collaborate/    # 协同算法核心
│   ├── document/       # 文档编辑器
│   ├── service/        # 服务端
│   └── common/         # 通用工具
├── Architecture.md     # 架构设计文档
├── delta_ot_document.sql # 数据库结构
└── README.md          # 项目说明

建议顺序

理解架构：阅读 Architecture.md 了解整体设计
学习算法：从 OT 算法原理开始
运行测试：执行测试用例验证理解
修改代码：基于需求进行开发
添加测试：为新功能添加测试用例

代码规范

使用 TypeScript 进行类型安全开发
遵循模块化设计原则
为每个模块编写详细的设计文档
保持测试覆盖率

相关命令请直接查看各模块的 package.json 文件的 scripts 字段。

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
packages		packages
.gitignore		.gitignore
Architecture.md		Architecture.md
README.md		README.md
delta_ot_document.sql		delta_ot_document.sql
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

delta-ot

关于项目

项目特色

系统架构

包结构详解

@delta-ot/collaborate - 协同算法核心

核心功能

目录结构

设计文档

开发命令

@delta-ot/document - 文档编辑器

核心功能

技术栈

目录结构

开发命令

service - 服务端

核心功能

技术栈

目录结构

开发命令

common - 通用工具

核心功能

设计文档

快速开始

环境要求

TODO - 协同编辑功能完善计划

协同编辑体验优化（最高优先级）

协同功能增强

富文本编辑器增强

用户体验提升

界面优化

交互体验

快捷键

系统优化

性能优化

安全加固

日志系统

文档管理功能（后期完善）

文档管理

用户权限管理

优先级

第一阶段（编辑器基础能力保障）

第二阶段（协同体验优化）

第二阶段（界面体验）

第三阶段（系统完善）

第四阶段（管理功能）

🚀 立即开始建议

推荐第一个功能：撤销重做系统优化

推荐第二个功能：复制粘贴系统完善

推荐第三个功能：用户在线状态

推荐第二个功能：Markdown语法支持

推荐第三个功能：表格编辑

📋 开发原则

1. 模块化开发

2. 测试驱动

3. 渐进式增强

4. 用户体验优先

5. 基础能力优先

安装依赖

数据库配置

启动服务

测试与验证

OT 算法测试

测试用例分类

协同编辑测试实验室

学习资源

API 文档

核心概念

技术路线对比

各模块职责说明

测试指南

开发指南

项目结构

建议顺序

代码规范

相关项目

`@delta-ot/collaborate` - 协同算法核心

`@delta-ot/document` - 文档编辑器

`service` - 服务端

`common` - 通用工具

Packages