块式富文本 CRDT 实时协同 可私有化部署 多端自适应 内嵌白板 & 思维导图 二次开发友好

灵语文档 · 产品技术白皮书

面向团队知识协作、在线文档、结构化写作与共创场景的一体化富文本编辑器。以块式内容模型为骨架、以CRDT 冲突自解引擎为脉搏、以多层可插拔服务架构为承载,让每一次敲击都能被记录、被同步、被回放。

1功能矩阵

围绕"写、排、合、享"四大核心动作,覆盖 12 类高频能力。

块式结构化编辑

段落、标题、列表、引用、代码、公式、表格、图片、附件、高亮块、日期、分割线等 20+ 类型块,每块独立可寻址。

斜杠命令面板

行首输入 "/" 唤起命令中心,支持中文拼音、首字母、关键词模糊匹配,键盘上下选择秒级插入。

Markdown 输入即渲染

实时识别标题、列表、引用、代码块、加粗/斜体、任务项、公式、表格等 GFM 语法,边写边看。

数学公式与科学排版

支持行内 / 块级公式,覆盖 LaTeX 主流语法与可视化输入面板,可键盘与手写混合录入。

多人实时协同

基于 CRDT 的多人同编辑,实时光标、用户头像、内容锁定与冲突自解;网络中断自动重连、离线缓冲。

内嵌白板与思维导图

在文档中直接嵌入无限画布与脑图节点,支持形状、连线、贴图、便签、层级拖拽,随文档一起同步。

层级文档树

支持多级目录、拖拽排序、批量重命名、跨层级移动与防环检测;树结构实时同步给所有协作者。

全局查找替换

跨块的全文检索、大小写与正则开关、批量替换、命中位置高亮,替换操作同样参与协同同步。

评论与批注

块级锚定评论、@ 提及、表情回应、解决 / 未解决状态;评论线程与文档一并同步。

AI 辅助写作

选中文本一键续写、总结、改写、翻译;支持自定义服务商、模型 ID 与提示词模板。

分享与外链权限

链接可配置只读 / 可编辑 / 需要口令 / 有效期;协作者可邮箱或邀请码定向邀请。

深浅主题 & 移动适配

亮色 / 暗色双主题、响应式工具栏、小屏横向滚动、触摸长按调出块操作面板。

2整体架构

四层分工:表现层 → 内核层 → 协同层 → 服务层。层与层之间以接口协议对齐,任一层都可独立替换。

服务层 · Service Layer REST 接口文档 / 用户 / 分享 长连接网关协同帧收发 鉴权中间件Token / 角色 / 权限 持久化嵌入式存储 / 关系库 对象存储图片 / 附件 / 静态 运维监控进程守护 / 日志 协同层 · Collaboration Layer CRDT 引擎冲突自解 · 因果保序 房间与快照按文档分片 · 增量帧 光标与感知在线成员 · 位置广播 离线缓冲断网续编 · 重连补投 变更日志落盘 · 回放 内核层 · Editor Core 块模型 & Schema可寻址内容节点 工具集 (Tunes)删除 / 移动 / 复制 / 上色 命令中心"/" 面板 · 快捷插入 历史与撤销栈语义指纹比较 只读 / 编辑态切换分享预览 · 权限联动 表现层 · Presentation 工作台编辑 / 目录 / 检索 分享预览外链 / 只读 / 口令 管理后台用户 / 权限 / 邀请码 官网 & 文档站SEO 静态页 移动端适配小屏工具栏 / 触摸手势 ▲ 每一层通过稳定协议向下一层解耦,可独立替换或降级
图 2‑1 · Mindlink 编辑器分层架构:四层从下到上,从服务侧一路托到用户指尖。

核心设计原则

内容即数据

文档不是 HTML 字符串,而是一棵由块组成的可寻址树。每块携带类型、内容、工具集状态;结构稳定,序列化简单,天然适合差异同步。

插件化能力

块类型、工具集、命令面板项、导入处理器均通过统一注册接口接入;新增能力零改动内核。

前后端可分离

编辑器内核不假设后端存在,可以完全离线运行;服务层可选、可替换、可私有化。

3内容模型:块式结构化

文档 = 有序块数组;块 = { id, type, data, tunes }。类型可插拔、结构可寻址、差异可比对。

Document (文档) title · blocks[] · meta · version BlockArray (有序块) [ b0, b1, b2, ... ] 位置稳定 · id 唯一 Paragraph · Heading · List · Code · Quote 基础文本型:内容承载在 data.text,支持行内样式标记 Table · Image · Attachment · Alert / HighBlock 复合结构型:data 内嵌子字段,块内部再自建可编辑域 Math Formula · Mermaid · Mindmap · Whiteboard 富媒体型:由专用可视化面板渲染,编辑数据回写 data Embed · Divider · Anchor · Comment (Tunes) 扩展 / 元数据型:跨块协作能力以工具集挂载 Tunes (工具集) · 每块可选开启 MoveUp / MoveDown · Delete · Duplicate · ColorBackground · Align · AnchorComment · DragHandle 工具集与块类型正交:任何块可以组合不同工具集;删除 / 移动操作对整棵子树生效
图 3‑1 · 块式内容模型:文档是一棵可寻址、可差异化的块树。

为什么选择"块"而非"扁平 HTML"

4多人协同实现原理

协同的本质:让多个终端各自编辑同一份数据,最终所有终端看到的完全一致,且中间不出现"丢失对方的编辑"。Mindlink 采用 CRDT + 增量帧 + 房间分片 三件套实现。

4.1 · CRDT:为什么冲突可以自动消解

传统"锁 + 中央写"要求同一时刻只有一人写,用户体验差;"OT 操作变换"依赖服务器权威排序,服务器一旦故障难以恢复。CRDT(Conflict-free Replicated Data Type,无冲突复制数据类型) 的两大特性让它成为离线友好场景的首选:

编辑器内核把每个块的数据分片暴露成一棵 CRDT 树;键值容器承载块属性、序列容器承载块数组与文本片段,任何终端发起的写入都能被"合并"而不是"覆盖"。

终端 A 基线: "Mindlink 是" 变更: + " 一款协同编辑器" 站点=α · 时钟=7 终端 B 基线: "Mindlink 是" 变更: + " 一款开放平台" 站点=β · 时钟=9 协同中枢 房间快照 + 增量帧路由 不落内容 · 只转发因果 按 docId 分片 合并结果 (所有终端最终一致) "Mindlink 是 一款协同编辑器一款开放平台" 按站点 ID + 时钟戳排序 · 交换两次合并顺序结果一致 · 无覆盖 / 无丢失 ▲ A 与 B 各自看到对方变更时, 本地 CRDT 直接吸收合并, 无需再询问服务器
图 4‑1 · CRDT 合并示意:并发变更通过逻辑时钟与站点 ID 排序,任何顺序合并都得到同一结果。

4.2 · 增量帧协议:只传"变了什么",不传"整篇文档"

每次本地编辑产生的状态更新 (state-vector diff)被编码成紧凑的二进制帧,附带"从哪个版本出发"的因果基线。服务器只做两件事:把帧转发给房间内的其他成员,并把增量日志落盘。

type docId siteId clock / sv payload (varint 长度) ops · 编辑操作集合 (增量) 帧结构 · 单帧典型 20 ~ 400 字节,同一次敲入仅传输被改动片段 生命周期时序 连接建立 鉴权握手 同步基线 增量互推 感知广播 断线补投 open auth sync/step1 sync/step2 · update awareness resync
图 4‑2 · 增量帧协议:紧凑编码 + 基线对齐 + 断线自恢复。

4.3 · 房间分片与在线感知

每个文档对应一个协同房间,房间内存中保存该文档的 CRDT 快照与在线成员列表。当客户端连接建立后:

  1. 基线交换:服务器下发当前状态向量 (state-vector);客户端比对本地基线,把"我缺的"和"你缺的"分别算出来。
  2. 差量补齐:双向各发一份增量帧,两端对齐到同一版本。
  3. 持续互推:之后每次编辑仅发送"新增的那一部分",服务器转发给同房间其他人。
  4. 感知广播:光标位置、选区范围、成员头像等"瞬时状态"走独立通道,不落盘、不进历史。
  5. 离线缓冲:网络断开时本地 CRDT 继续吸收编辑;重连后走"基线交换"分支,自动补齐错过的增量。
协同房间 docId 分片 CRDT 快照 终端 A α · 编辑中 终端 B β · 只读 终端 C γ · 移动 终端 D δ · 离线 变更日志 → 落盘
图 4‑3 · 协同网络拓扑:房间按文档隔离,客户端与房间直连;离线成员在重连时走基线交换补齐。

4.4 · 端到端渲染一致性:让"整页闪烁"不再发生

远端变更应用回内核后,如果每次都全量重绘 DOM,用户会看到光标闪烁与整页抖动。Mindlink 使用语义指纹 + 块级 diff 策略:

5服务与数据分层

服务侧坚持"薄网关 · 强内聚 · 可替换":所有对外协议集中在两个入口(REST 与长连接),业务模块以领域划分,存储层做接口化以便切换数据库。

浏览器 / 客户端 编辑器 SPA 反向代理网关 TLS · 路由 · 静态托管 REST 路由 · /api 长连接 · /collab 静态 · /editor · /doc · /uploads 业务模块 (Domain Modules) 文档 · 目录树 用户 · 权限 · 邀请码 分享 · 口令 · 有效期 附件 · 对象存储 评论 · 批注 · 提及 AI 网关 · 服务商适配 数据访问层 (Repository / ORM) 嵌入式存储 (默认 · 零配置) 关系型数据库 (可选) 对象存储 · 图片/附件 变更日志 · 快照 缓存 (可选) 运维侧 · 进程守护 · 日志分级 · 灰度发布 · 数据备份 · SSL 续期 · 指标监控 · 一键部署脚本 ▲ 静态站点、REST、长连接三通道共用一台反向代理,业务侧仅需暴露一个端口 ▲ 所有环境配置集中在 .env,一行切换 SQLite / MySQL / Postgres;私有化部署友好
图 5‑1 · 服务分层与请求路径:网关 → 业务模块 → 数据访问层。

典型请求:一次"保存文档"经过哪些层

  1. 浏览器:编辑器把块数组序列化为结构化数据,产生本地 CRDT 变更;同时把快照 POST 到 REST。
  2. 反向代理:TLS 卸载 → 命中 /api/* 前缀 → 转发到服务进程。
  3. 鉴权中间件:解析 Token → 校验文档归属与读写权限 → 命中失败返回 401/403。
  4. 业务模块:接收快照 → 与协同房间快照对齐 → 写入变更日志与主档。
  5. 数据访问层:以事务形式落盘,主键冲突 / 版本落后时返回"需要 rebase"提示。
  6. 长连接:另一路 CRDT 增量帧被推给同房间其他在线成员,完成实时同步。

6安全、权限与私有化

从认证到细粒度授权,从传输加密到存储加密;数据完全留在客户自己的服务器。

身份与令牌

密码采用带盐单向散列存储;会话令牌使用签名机制,含签发时间、过期时间与角色字段,服务端可随时吊销。

角色与权限

内置管理员 / 编辑者 / 只读访客三类;文档、目录、附件各自可设 ACL。分享链接可绑定读写意图与口令。

邀请码准入

注册可开启邀请码校验,控制用户来源;管理员后台一键派发 / 停用邀请码。

协同鉴权双通道

长连接建立时先握手鉴权,加入房间时再校验成员身份;REST 与 WS 权限模型一致,避免"接口能进、协同不能进"的错配。

传输与证书

强制 HTTPS 与 WSS;证书独立目录存放,续期只需替换文件;支持主流 CA 与自签证书。

私有化零依赖

默认嵌入式存储,无需额外数据库服务;对象存储以本地磁盘为默认,可平滑切换为云厂商。

数据留域 (Data Residency)

7导入、导出与扩展

把"外部内容进来"和"内部内容出去"都做成可插拔管道,覆盖常见格式;同时留出编程接口给二次开发。

导入

  • Markdown / GFM:标题、任务列表、表格、代码块、公式、内嵌 HTML 白名单
  • Word (.docx) / OpenDocument:解析为块结构,图片走对象存储
  • PDF:抽取文本与图像,映射为块数组
  • HTML:DOM → 块的适配器,保留样式与语义

导出

  • PDF:分页保真,支持水印与目录书签
  • Markdown:结构化反解,保留公式、表格、代码块
  • HTML:语义化标签,可二次渲染或邮件嵌入
  • 结构化数据 (JSON Schema):块数组直接输出,方便接入外部系统

扩展接口 (面向二次开发)

块类型插件

实现"渲染 / 保存 / 校验 / 工具集"四个钩子即可注册新块;支持懒加载。

工具集插件

在块右侧或悬浮面板追加工具,例如"翻译到英文"、"生成摘要"。

命令面板项

把企业专有动作挂到斜杠命令,例如"插入合同模板"、"生成周报骨架"。

导入 / 导出管道

可自定义数据源处理器,接入 Confluence / Notion / 内部 CMS。

AI 服务商适配

统一封装请求体与流式响应,可在管理后台切换服务商与模型 ID。

主题与样式

亮 / 暗变量 + 品牌色覆盖;支持按租户注入 CSS。

8典型应用场景

块式结构 + 实时协同 + 可私有化 = 覆盖多套行业场景。

团队知识库 / Wiki

层级目录承载产品文档、开发手册、运营 SOP;全局检索 + 评论 + 版本回溯,让团队"知识资产"沉淀下来。协同能力允许两人在同一篇文档同时修订,不丢失任何一方。

结构化写作 / 报告

用块模型代替 Word 排版;公式、代码、图表、白板混排,一次写作多端发布。可导出为 PDF / Markdown / JSON,用于内部流转或对外发版。

在线教育 / 教研协作

老师在协同房间批改作业,学生实时看到批注;数学公式与代码块支持理工科教学场景;评论锚定到具体块,讨论不漂移。

政企内网文档

可完全部署在客户内网,数据不出域;邀请码 + 角色权限 + 审计日志满足合规;支持自签证书与本地对象存储。

产品需求 / 头脑风暴

内嵌白板与思维导图,让"讨论 → 结论 → 交付物"在同一个文档完成;协同光标让远程会议更高效。

跨企业联合编辑

通过分享链接 + 口令 + 有效期,让上下游同事或供应商临时参与,无需注册;到期自动失效,不留残余访问。

9性能工程

让"打开一篇大文档、多人在场、敲键不卡"成为默认体验。

< 100ms
块插入端到端响应
< 30KB
首屏静态资源 (gzip)
< 500ms
千块文档打开耗时
< 200B
单次敲键协同帧 (典型)

核心优化点

懒加载与代码分割

编辑器主包只保留内核与常用块;白板 / 脑图 / 公式面板 / 富媒体按需加载。

块级虚拟滚动

长文档仅渲染可视区附近的块,滚动时按需替换;即便十万块也不卡。

语义指纹 diff

协同回环避免全量重绘,只更新真发生变化的块;杜绝"整页闪烁"。

增量帧传输

编辑操作以二进制帧紧凑编码;一次敲键典型 200 字节以内。

持久化旁路

CRDT 变更先落日志,主档定时快照合并;写放大低、崩溃可回放。

静态资源长缓存

构建产物携带哈希,浏览器与 CDN 命中率高;入口 HTML 单独 no-cache 保证灰度。

10与传统方案对比

把 Mindlink 与"在线 Word 类"和"纯本地 Word 桌面"两类典型形态作横向比较。

维度Mindlink 编辑器传统在线 Word 类桌面办公软件
内容模型块式结构 · 可寻址 · 差异同步富文本流 · 段落边界模糊二进制文档
多人协同CRDT · 无中心权威 · 离线友好OT 或锁 · 依赖服务端仲裁需另接服务
结构化嵌入 (公式 / 白板 / 脑图)原生块类型 · 统一协同部分支持支持但不协同
Markdown 输入边写边渲染 · GFM 完整不支持不支持
可私有化单文件数据库 · 一键部署重服务依赖 · 成本高桌面端为主
二次开发块 / 工具集 / 命令 / AI / 主题全开放SDK 有限受生态约束
移动体验响应式 · 触摸手势 · 小屏工具栏部分适配不适用
审计 / 权限角色 · 分享口令 · 邀请码 · 变更日志基础依赖外部

11常见问题

摘取选型、部署、集成、演进四类高频疑问。

Q1 · 协同规模能到多大?

单房间推荐 20 人以内在场,服务端按 docId 分片;跨房间水平扩容只需增实例。若需要"上百人围观 + 少数人编辑",可走"编辑者协同 + 观看者快照订阅"降级方案。

Q2 · 网络断了还能编辑吗?

能。本地 CRDT 会持续吸收编辑,重连后走"基线交换"分支自动补齐;对用户体验无阻断。

Q3 · 支持哪些部署形态?

标准 Linux 服务器一键部署 (内置反向代理 + 进程守护);容器化部署 (前后端分离镜像);纯静态 + 外接 API 模式 (编辑器仅作为组件嵌入已有门户)。三种形态共用同一份前端产物。

Q4 · 数据能迁移或对接已有系统吗?

可以。块模型直接序列化为 JSON Schema;提供 Markdown / Word / PDF / HTML 导入;导出可输出 PDF / Markdown / 结构化数据;也可通过块级插件自定义渲染目标。

Q5 · 编辑器能拿来做"非文档"场景吗?

可以。块式结构 + 可插拔类型 + 协同房间的组合,非常适合合同协作、课件编辑、菜谱库、工单模板、SOP 编辑器等垂直场景,只需要注册对应块类型即可。

Q6 · AI 是必须模块吗?

不是。AI 是完全可选的外挂,可在管理后台开关;关闭后编辑与协同不受任何影响,也不会向外部服务商发送内容。

Q7 · 是否支持多语言 UI?

支持。编辑器所有文案与提示通过集中式 i18n 词条管理,接入方可以注入自己的语言包。