花了3个月，我们做了一款 AI 版的“飞书文档”

作为一名在AI办公与协同领域深耕多年的创业者，同时也是一名持续探索企业效率工具的创业者，过去一年多我和团队一直在啃一块硬骨头：做一款真正面向开发者、支持私有化部署、原生支持实时协同的AI文档 ------Mindlink 灵语文档。

很多粉丝问我：现在在线文档产品这么多，飞书、腾讯文档、Notion 都已经很成熟了，为什么还要自己做？

答案其实很简单：当我们深入到企业内网部署、垂直业务系统嵌入、深度二次开发这些场景里时，你会发现市面上的产品要么太重太贵，要么根本满足不了「数据不出域、能力可定制、协同不卡顿」的核心诉求。

今天这篇文章，我想从开发者技术视角 和产品创业者视角双重视角，拆解 Mindlink 从底层数据模型到上层服务架构的完整设计思路，也聊聊我们在做这款产品过程中的技术取舍与工程思考。

演示地址：mindlink.turntip.cn

技术文档：mindlink.turntip.cn/doc

文章略长，信息密度较大，建议收藏再看～

一、重新定义文档：从「HTML 字符串」到「块式数据树」

做文档编辑器的第一个灵魂拷问：文档的本质是什么？

传统富文本编辑器的答案是「带样式的 HTML 字符串」。这带来了三个绕不开的问题：

• 语义模糊同样的视觉效果，可能对应无数种 HTML 嵌套结构，跨端渲染一致性极差；
• 协同困难差异计算只能基于字符串做粗粒度比对，很容易出现样式错乱、内容丢失；
• 扩展受限想加入表格、白板、脑图这类复杂结构，就要引入海量嵌套 DOM，维护成本指数级上升。

我们从第一天就放弃了这条路。Mindlink 的核心选择是：文档不是排版字符串，而是一棵由块组成的可寻址结构化数据树。

块式模型的核心定义

在 Mindlink 中，文档的最小单元是「块（Block）」，每一个块都有唯一 ID、明确类型、独立数据和可挂载的工具集：

文档 = 有序块数组块 = { id, type, data, tunes }

我们把块分成了四大类，覆盖了绝大多数文档场景：

• 基础文本型 段落、标题、列表、引用、代码等，内容承载在 data.text 中，支持行内样式标记；
• 复合结构型 表格、图片、附件、高亮块等，data 内嵌子字段，块内部再自建可编辑域；
• 富媒体型 数学公式、思维导图、白板等，由专用可视化面板渲染，编辑数据回写 data；
• 扩展元数据型分割线、锚点、评论工具集等，以工具集的形式挂载，提供跨块协作能力。

为什么块式模型是更优解？

对比扁平 HTML，块式结构的优势是根本性的：

1. 结构稳定，零歧义块携带明确的类型 + 内容 + 工具集，序列化和反序列化不会出现语义偏差，天然适合跨端一致渲染；
2. 差异最小化编辑某块只触碰该块的数据分片，协同同步和增量持久化都能收敛到块粒度，传输量和计算量大幅降低；
3. 能力可组合新增一种块类型，只需要注册一个类型定义；新增一种工具，只需要注册一个 tune，完全不用改动内核代码；
4. 天然支持富媒体嵌套表格、白板、脑图这类需要内部嵌套结构的场景，块模型可以优雅承载，不会陷入 HTML 嵌套地狱；
5. 操作可回放块级的新增、删除、移动、更新就是天然的变更日志，可用于协同合并、操作审计与版本回溯。

这一步选择，是所有后续协同能力、扩展能力、性能优化的根基。

二、协同的本质：CRDT 如何做到「断网也能写，合并不冲突」

多人实时协同是在线文档的核心能力，但绝大多数用户都经历过这些痛点：网络一卡就没法编辑、多人同时写容易丢内容、远端更新过来整页闪烁。

Mindlink 采用 CRDT + 增量帧 + 房间分片 三件套，从底层解决这些问题。

为什么是 CRDT，不是 OT？

行业内主流的协同方案主要有两种：OT（操作变换）和 CRDT（无冲突复制数据类型）。我们最终坚定选择了 CRDT，核心原因有两个：

第一，CRDT 无中心权威，天然离线友好。 OT 依赖服务器做全局操作排序，服务器是绝对权威，一旦断网或者服务器故障，编辑就会中断。而 CRDT 基于交换律和幂等性，每个终端都可以独立编辑，变更携带逻辑时钟戳与站点 ID，合并时按「因果序」而非「物理时间」排布，无论以什么顺序合并，最终结果都完全一致。

第二，CRDT 避免了「删除复活」类悖论。 很多人应该遇到过：删了一段文字，过一会又莫名其妙出现了。这本质上是 OT 操作顺序错乱导致的。CRDT 的因果保序机制，从根本上杜绝了这类问题。

在 Mindlink 协同AI文档的实现中，我们把每个块的数据分片都暴露成一棵 CRDT 树：键值容器承载块属性，序列容器承载块数组与文本片段。

任何终端发起的写入都是「合并」而不是「覆盖」，两个用户同时编辑同一段落，内容也不会丢失。

增量帧协议：只传「变了什么」，不传「整篇文档」

很多协同编辑器卡顿的根源，是每次编辑都要传输大量冗余数据。Mindlink 设计了紧凑的二进制增量帧协议，具体逻辑如下：

• 每次本地编辑产生的状态更新，被编码成 20~400 字节的二进制帧；
• 帧附带「因果基线版本号」，接收方可以精准知道变更基于哪个版本；
• 服务器只做两件事：把帧转发给房间内其他成员，把增量日志落盘。

一次普通的键盘输入，协同帧典型大小不到 200 字节。哪怕是弱网环境，也能做到秒级同步。

房间分片与离线缓冲

我们按文档做了房间级分片，每个文档对应一个协同房间，内存中保存该文档的 CRDT 快照与在线成员列表。连接建立后通过「基线交换 - 差量补齐 - 持续互推」三步完成同步：

1. 服务器下发当前状态向量，客户端比对本地基线，算出双方缺失的增量；
2. 双向各发一份增量帧，两端对齐到同一版本；
3. 之后每次编辑仅发送新增增量，服务器转发给同房间其他人。

特别值得一提的是离线缓冲机制：网络断开时，本地 CRDT 会持续吸收用户的所有编辑操作，完全不会中断使用；重连后自动走基线交换流程，后台静默补齐所有错过的增量，用户几乎感知不到断网发生过。

端到端渲染一致性：告别「整页闪烁」

远端变更应用到本地时，如果每次都全量重绘 DOM，就会出现光标跳动、整页闪烁的糟糕体验。我们用两个核心优化解决了这个问题：

• 语义指纹 diff对块内容与结构做规范化哈希，比较「意思变了没」，忽略排版细节差异，指纹未变的块直接跳过重绘；
• 位置 + 内容双维度 diff远端更新到达后，识别出「新增 / 删除 / 移动 / 内容变更」四类最小动作，只操作对应 DOM 节点；
• 光标锚定远端块新增或移动时，本地光标锚点跟随对应块移动，不会被插入的段落顶到意外位置。

三、四层架构哲学：解耦到每一层，私有化到每一个组件

技术架构决定了产品的边界。Mindlink 协同AI文档采用了严格的四层分层架构：表现层 → 内核层 → 协同层 → 服务层，层与层之间通过稳定的接口协议对齐，任一层都可以独立替换或降级。

具体架构设计我花了一个架构图，大家感兴趣的可以参考一下：

四层职责划分具体介绍如下：

1. 表现层负责工作台、编辑界面、目录、检索、分享预览、管理后台、移动端适配等所有用户可见的部分；
2. 内核层块模型与 Schema、命令中心、历史与撤销栈、工具集、只读 / 编辑态切换，是编辑器的核心计算单元；
3. 协同层CRDT 引擎、冲突自解、房间与快照、增量帧收发、光标感知、离线缓冲、变更日志落盘与回放；
4. 服务层REST 接口、长连接网关、鉴权中间件、权限持久化、存储适配、运维监控。

这种设计带来了两个巨大的优势：

• 前后端可完全分离编辑器内核不假设后端存在，可以完全离线运行；服务层可选、可替换、可私有化。你可以把 Mindlink 当成纯前端组件嵌入业务系统，也可以搭配完整服务端做私有化部署。
• 能力插件化块类型、工具集、命令面板项、导入处理器都通过统一注册接口接入，新增能力零改动内核。

服务侧设计：薄网关、强内聚、可替换

对于企业私有化部署场景，服务端的轻量性和兼容性至关重要。我们坚持「薄网关、强内聚、可替换」的设计原则，如下图所示：

• 所有对外协议集中在两个入口：REST 接口与长连接通道，通过反向代理统一暴露，业务侧只需暴露一个端口；
• 业务模块按领域划分，文档、用户、权限、分享、评论、AI 网关各自内聚，互不耦合；
• 数据访问层做了完整的接口抽象，支持一键切换 SQLite / MySQL / Postgres，默认嵌入式存储，零额外数据库依赖。

这也是为什么 Mindlink 可以做到「单服务器一键部署」：内置反向代理、进程守护、嵌入式数据库，一台 Linux 机器就能跑起来，非常适合中小企业和政企内网快速落地。

四、开发者视角：二次开发友好，不是一句口号

我自己也是开发者出身，深知「SDK 友好」四个字说起来容易，做起来难。很多产品号称支持二次开发，实则接口封闭、文档缺失、改一点东西就要动内核。

Mindlink 从设计之初，就把「二次开发友好」写进了技术底座。我们提供了完整的扩展体系，开发者可以在不修改内核的前提下，深度定制编辑器的能力。

六大扩展能力，覆盖绝大多数定制需求

1. 块类型插件实现「渲染 / 保存 / 校验 / 工具集」四个钩子即可注册新块，支持懒加载。企业可以快速接入自己的业务组件，比如合同字段、工单卡片、数据图表等。
2. 工具集插件可以在块右侧或悬浮面板追加工具，比如「翻译到英文」「生成摘要」「同步到工单系统」等，工具集与块类型正交，任意块都可以组合不同工具。
3. 命令面板扩展 把企业专有动作挂到斜杠命令，比如「插入合同模板」「生成周报骨架」「插入产品组件」，员工通过 / 就能快速调用内部能力。
4. 导入 / 导出管道可自定义数据源处理器，对接 Confluence、Notion、内部 CMS 等系统；导出也支持自定义格式，方便接入业务流程。
5. AI 服务商适配统一封装请求体与流式响应，可在管理后台自由切换服务商与模型 ID。AI 能力默认关闭，启用后所有请求路由由客户自行配置，数据完全不流出企业内网。
6. 主题与样式定制亮 / 暗双主题 + 品牌色覆盖，支持按租户注入自定义 CSS，完美融入企业自有产品的视觉体系。

数据完全开放，不做厂商锁定

我们坚信，好的技术产品应该让数据掌握在用户自己手里。Mindlink 的块数组可以直接输出为标准 JSON Schema，结构清晰、语义明确，开发者可以轻松把文档数据接入任何外部系统。

导入支持 Markdown、HTML；导出支持 PDF、Markdown、HTML、结构化数据。无论是系统迁移还是数据对接，都不会有任何壁垒。

五、创业者复盘：做 ToB 技术产品的几个底层认知

从技术选型到产品落地，踩过无数坑，也有很多思考。站在创业者的角度，我想分享几个关于 ToB 技术产品的底层判断。

1. 私有化不是加分项，是企业级的入场券

现在越来越多的政企、金融、制造业客户，对「数据不出域」有硬性要求。SaaS 模式的在线文档再好用，也过不了合规这一关。

我们做私有化的思路不是「把 SaaS 搬下来」，而是从架构层面就为私有化设计：最小化依赖、一键部署、配置集中化、支持离线环境。默认单文件数据库，不需要额外部署中间件，普通运维人员就能搞定。

2. 结构化是未来，纯排版的时代过去了

过去的文档是「排版工具」，未来的文档是「信息载体」。公式、代码、思维导图、白板、甚至业务组件，都会成为文档的一部分。

只有块式结构，才能优雅地承载这些异构内容。这也是为什么我们坚定走块式路线，而不是在传统富文本上修修补补。

3. 性能是底线，不是卖点

很多产品喜欢把「高性能」当卖点，但在我看来，性能是及格线。打开一篇大文档要等好几秒、敲个字卡半天，功能再多也没用。

我们给自己定了几个硬指标：

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

通过懒加载、块级虚拟滚动、语义指纹 diff、持久化旁路等一系列工程优化，我们最终都达成了这些目标。

4. 不做「全家桶」，做「好底座」

市面上很多文档产品越做越重，最后变成了大而全的平台。但 Mindlink 的定位很清晰：我们不做完整的文档平台，我们做最好的协同编辑器底座。

开发者可以基于 Mindlink 快速搭建知识库、产品文档系统、工单编辑器、课件系统、合同管理系统...... 我们把底层的编辑、协同、存储做好，上层的业务场景交给开发者去发挥。

六、场景与未来：块式协同的想象力远不止文档

基于块式结构 + 实时协同 + 私有化部署的特性，Mindlink 已经能很好地覆盖很多垂直场景：

• 团队知识库 / Wiki层级目录承载产品文档、开发手册、运营 SOP，全局检索 + 评论 + 版本回溯，多人同时修订不冲突；
• 结构化写作 / 技术报告公式、代码、图表、白板混排，一次写作多端导出，非常适合技术团队、科研机构；
• 政企内网文档完全部署在内网，数据不出域，邀请码 + 细粒度权限 + 审计日志，满足合规要求；
• 产品需求 / 头脑风暴内嵌白板与思维导图，从讨论到结论到交付物，全部在同一个文档完成；
• 跨企业联合编辑通过分享链接 + 口令 + 有效期，让上下游临时参与协作，到期自动失效，不留权限残余。

但这些还只是开始。未来块式协同的想象力，远不止「在线文档」这一种形态。

接下来我们的几个核心方向：

1. 继续深耕块式模型，拓展更多垂直场景的专用块类型；
2. 深化 AI 与块模型的结合，不止是续写改写，更要做结构化的内容生成与整理；
3. 完善生态，提供更多开箱即用的插件与模板，降低开发者接入成本；
4. 持续优化私有化部署体验，支持更丰富的企业级集成能力。

写在最后

从最初的一行行代码，到现在完整的产品落地，这一路踩过很多坑：CRDT 合并的各种边界 case、大文档的性能瓶颈、移动端适配的兼容问题...... 但我们始终相信，一款好的技术产品，应该是「底层足够扎实，上层足够灵活」。

做企业级工具是一条慢路，但也是一条足够深的路。我们不追风口，不卷概念，只想把协同编辑这件事做透、做扎实，给开发者和企业提供一个真正好用、可控、可信赖的块式协同编辑器底座。

如果你也在做协同办公、知识库、企业内容管理相关的产品，或者对私有化协同编辑器有需求，欢迎交流探讨。

演示地址：mindlink.turntip.cn

技术文档：mindlink.turntip.cn/doc

也欢迎大家学习研究 Mindlink，给我们提提宝贵意见。