VS Code实时协作绘图扩展开发：从Monorepo架构到CRDT同步实战

1. 项目概述：在VS Code里实现多人实时协作绘图

如果你和我一样，经常用VS Code写代码、写文档，同时又离不开draw.io来画架构图、流程图，那你肯定也遇到过这个痛点：画好的.drawio文件，想和同事一起讨论修改，要么得导出成图片发来发去，要么就得靠“文件接力”——你改完发给我，我改完再发给你，版本管理一团糟。传统的在线协作工具虽然能解决同步问题，但又得离开熟悉的开发环境，在浏览器和编辑器之间反复横跳，体验割裂。

Draw With You这个项目，瞄准的就是这个缝隙。它不是一个独立的Web应用，而是一个原生集成在VS Code内部的、支持实时协作的draw.io编辑器。它的核心愿景是让技术图的协作像写代码一样自然：在同一个VS Code工作区里，多人能同时编辑一个.drawio文件，每个人的修改都能实时同步，并且所有变更历史、版本差异都清晰可追溯。

这个项目目前还处于早期开发阶段，代码库呈现为一个基于TypeScript的Monorepo（单体仓库），包含了未来扩展的骨架，比如与AI助手（如Codex, Copilot）集成的MCP服务器协议层。虽然完整的协作功能尚未实现，但其架构设计和开发模式已经为我们展示了一个非常清晰的、将复杂图形编辑器深度嵌入IDE的工程路径。对于想要学习如何开发复杂VS Code扩展，或者对实时协作、图形编辑领域感兴趣的朋友来说，这是一个绝佳的研究样本。

2. 项目架构与核心设计思路拆解

2.1 为什么选择Monorepo与TypeScript？

打开项目仓库，第一个映入眼帘的就是package.json里的workspaces配置。这是一个典型的使用npm workspaces的TypeScript Monorepo。这种选择背后有很强的工程考量。

核心优势一：逻辑复用与清晰边界。一个协作绘图扩展，至少包含几个核心部分：VS Code扩展主体（负责注册编辑器、命令）、一个Webview编辑器（渲染draw.io画布）、处理文档模型与差异计算的共享核心库、以及与外部AI服务通信的协议层。如果把这些都塞进一个包，代码会迅速变得臃肿且难以维护。Monorepo允许我们将这些模块拆分成独立的packages/，比如packages/core、packages/extension、packages/editor-webview、packages/mcp-server。它们各自有独立的package.json，但共享顶层的node_modules和构建配置。这样一来，core包里的文档模型可以被extension和webview同时引用，确保了数据一致性，同时模块间的依赖关系一目了然。

核心优势二：统一的开发与构建体验。项目使用顶层的npm run build和npm run build:watch命令。通过turbo或简单的npm workspaces脚本，可以一键构建所有包，或者只构建发生变更的包及其依赖，极大提升了开发效率。TypeScript则为整个项目提供了静态类型检查，这对于涉及复杂数据模型（如图形文档的JSON结构、网络协议）的项目至关重要，能在编码阶段就避免许多低级错误。

实操心得：Monorepo的工具链选择。虽然项目目前可能使用简单的npm脚本，但在规模扩大时，通常会引入像Turborepo或Nx这样的构建系统来优化缓存和任务调度。如果你要搭建类似项目，我建议从一开始就考虑Turborepo，它的缓存机制能让你在多次构建中节省大量时间，特别是当core包未变动时，依赖它的其他包可以直接使用缓存输出。

2.2 理解“VS Code-Native”与自定义编辑器

“VS Code-Native”是这个项目的灵魂。它不是通过一个iframe简单嵌入一个网页版draw.io，而是实现了VS Code的自定义编辑器（Custom Editor）API。

这与普通Webview有何不同？普通的Webview可以看作一个独立的浏览器标签页，它与VS Code的交互是异步的、基于消息传递的。而自定义编辑器更进一步，它允许你接管特定文件类型（如.drawio）的整个编辑界面。当你打开一个.drawio文件时，VS Code不会用文本编辑器显示其XML源码，而是将整个标签页的控制权交给你的扩展，由你的扩展来渲染一个完整的图形编辑界面。

技术实现要点：在packages/extension中，你会看到它使用vscode.registerCustomEditorProvider来注册编辑器。这个Provider需要返回一个CustomTextEditor或实现CustomDocument接口。对于draw.io这种基于现有库的编辑器，通常会采用WebviewPanel来承载，但将其包装成符合自定义编辑器API的形态。这样做的好处是，这个编辑器能深度集成VS Code的文件保存、撤销/重做、脏标记（文件未保存时的圆点提示）等生命周期管理，用户体验与原生文本编辑器无异。

注意：实现自定义编辑器时，一个关键陷阱是文件持久化。你需要妥善处理CustomDocument的save、saveAs、revert等回调。draw.io的画布状态是内存中的复杂对象，你需要将其与磁盘上的.drawio（本质是XML）文件进行序列化和反序列化。项目中的packages/core很可能就包含了这部分文档模型的转换逻辑。

2.3 协作与同步的核心：从CRDT到操作转换

虽然当前代码库可能还未实现完整的实时协作，但其架构已经为此铺平了道路。多人同时编辑一个图形，本质是一个分布式实时协同编辑问题。

常见的两种技术思路：

1. 操作转换（Operational Transformation, OT）：Google Docs使用的技术。当两个用户同时进行操作时，系统会将操作进行转换，使得在应用后所有副本最终一致。它对中央服务器的逻辑要求较高。
2. 无冲突复制数据类型（Conflict-Free Replicated Data Types, CRDT）：一种更适合去中心化场景的数据结构。每个操作都是可交换、可结合、幂等的，因此无论以何种顺序接收，最终状态都能收敛一致。像Figma、VS Code Live Share的早期版本都使用了CRDT。

Draw With You的潜在设计：从项目强调“shared core document and diff logic”来看，它很可能在core包中定义了一个与UI分离的文档状态模型。这个模型中的每一个图形元素（形状、连线、文本）都可以被赋予唯一的ID和版本信息。当协作发生时，不再是传输整个图片或文档，而是传输一系列细粒度的操作指令（如“将元素A移动到坐标(x,y)”，“修改元素B的文本为‘Hello’”）。这些操作会经过diff逻辑计算，然后通过OT或CRDT算法处理，确保每个人的视图最终一致。

为什么“diff”逻辑如此重要？因为直接传输完整文档状态效率太低。高效的协作系统只传输差异（delta）。core包中的diff逻辑需要能够比较两个文档状态，生成一组最小化的操作序列。这对于实现离线编辑后的同步、冲突解决以及变更历史查看（如命令面板中的“Show Recent Human Changes”）功能至关重要。

3. 开发环境搭建与初次运行实操

3.1 从零开始：环境准备与依赖安装

要跑起来这个项目，你需要一个基础的Node.js开发环境。我推荐使用nvm来管理Node版本，避免全局版本冲突。

# 1. 确保Node.js版本（参考项目根目录的 .nvmrc 或 package.json 的 engines 字段） # 通常需要Node 18+。使用nvm安装并切换： nvm install 18 nvm use 18 # 2. 克隆项目代码 git clone https://github.com/u9401066/draw-with-you.git cd draw-with-you # 3. 安装依赖 # 使用 npm install 会利用workspaces配置，递归安装所有packages下的依赖 npm install

踩坑预警：网络与依赖问题。由于依赖较多，特别是某些原生模块，国内用户可能会遇到安装缓慢或失败的问题。有条件的可以配置npm镜像。如果遇到node-gyp编译错误（通常与canvas等图形相关原生包有关），你需要确保本地有Python和C++编译环境（在Windows上可能需要安装windows-build-tools）。

3.2 构建项目与启动调试

安装完依赖后，第一步是编译TypeScript代码。

# 一次性构建所有workspace中的包 npm run build # 或者，在开发时使用监听模式，任何源码更改都会触发增量编译 npm run build:watch

运行build:watch后，终端会保持监听状态。这时，你就可以打开VS Code进行调试了。

调试VS Code扩展的标准流程：

1. 在VS Code中打开本项目根文件夹。
2. 按下F5或点击“运行和调试”侧边栏的绿色三角按钮。这将会运行你在.vscode/launch.json中配置的启动任务（通常是“Draw With You: Extension Host”）。
3. 此时，一个新的VS Code窗口会弹出来，这个窗口叫做“扩展开发主机”。它加载了你当前开发的这个扩展（Draw With You），而不是你原本的VS Code。
4. 在这个新窗口里，按照项目指引，打开examples/smoke-workspace/sample.drawio文件。

关键验证点：如果一切正常，这个.drawio文件不应该以文本形式展示其XML内容，而应该呈现一个完整的draw.io图形编辑界面，包含画布、左侧图形库、顶部工具栏等。这意味着你的自定义编辑器已经成功注册并接管了该文件类型。

3.3 手动冒烟测试：验证核心功能

仅仅打开文件还不够，我们需要验证一些核心交互是否工作。项目提供了一个非常实用的手动检查清单：

1. 基础渲染与编辑：在打开的图形编辑器中，尝试拖动一个图形，或者修改一下文字。然后保存文件（Ctrl+S）。去文件系统中用文本编辑器打开那个sample.drawio文件，你应该能看到XML内容发生了变化。这说明编辑器的“编辑-保存”闭环是通的。
2. 扩展命令集成：这是验证VS Code扩展与Webview通信是否正常的关键。
   • 按下Ctrl+Shift+P打开命令面板，输入并执行Draw With You: Show Active Diagram State。你应该能看到一个输出面板或者弹窗，里面显示了当前图形的内部状态（JSON格式）。这个数据是从Webview编辑器发回给扩展主进程的。
   • 同样，执行Draw With You: Show Active Selection Context，然后选中画布上的一个图形，看看输出的JSON是否包含了选中图形的信息。
   • 执行Draw With You: Show Recent Human Changes，做一些修改，看看它是否能列出你的操作历史。

如果文件仍然以文本形式打开？这是一个常见问题，原因和解决方案如下：

• 没在正确的窗口操作：确保你是在F5启动的“扩展开发主机”新窗口里操作，而不是在原项目窗口。
• 文件关联问题：VS Code可能还记忆着之前的打开方式。可以尝试：
  • 在资源管理器中对文件右键，选择“打开方式”，然后强制选择“Draw With You Diagram”。
  • 如果文件已经是文本形式打开了，在标签页上右键，选择“重新打开编辑器为...”，再选择“Draw With You Diagram”。
• 扩展未激活：某些扩展是按需激活的。确保你打开的确实是.drawio后缀的文件。项目也提示了，对于.xml、.drawio.xml等变体后缀，可能需要通过命令Draw With You: Open Diagram来手动触发。

4. 深入核心包：文档模型与协议解析

4.1packages/core：一切数据的基础

core包是这个项目的大脑，它不包含任何UI代码，只负责处理最核心的数据逻辑。理解它，就理解了整个应用的数据流。

文档模型（Document Model）：这里定义了一个与draw.io图形一一对应的内部数据结构。这个结构可能是一个大的JSON对象，包含了页面（Page）、图层（Layer）、单元格（Cell，对应图形、连线、文本等）的树形或图状关系。每个单元格会有位置、大小、样式、文本内容、连接关系等属性。这个模型的设计目标是与draw.io的底层MXGraph库兼容，同时又要便于进行差异计算（Diff）和序列化/反序列化。

差异逻辑（Diff Logic）：这是实现协作、撤销重做、历史追踪的基石。diff函数会比较两个文档模型（oldDoc和newDoc），并生成一个操作列表（Patch）。这个操作列表需要是最小化且可逆的。例如，不是记录“整个文档变成了B”，而是记录“在页面1的图层0中，添加了ID为‘shape_123’的矩形，其属性为...”。这种细粒度的操作是高效同步的前提。

实操中的难点：图形文档的diff比文本diff复杂得多。移动一个图形，可能同时改变了它的位置属性和它与其他图形的连接线。一个高效的diff算法需要识别出这种“语义操作”，而不是仅仅对比JSON属性的变化。项目可能借鉴了draw.io本身的一些内部机制，或者采用了一种基于操作记录（在编辑时直接记录操作，而非事后全量对比）的方式。

4.2packages/protocols：通信的契约

在Monorepo中看到一个独立的protocols包（或类似命名的包），这通常是一个非常好的实践。它定义了前后端、进程间、甚至与外部服务通信的接口契约。

里面通常有什么？主要是TypeScript的interface和type定义。

• Webview协议：定义VS Code扩展主进程与Webview编辑器之间通过postMessage传递的消息格式。例如：{ command: 'UPDATE_SHAPE', payload: { id: 'xxx', x: 100, y: 200 } }。
• MCP协议：定义与Model Context Protocol服务器通信的数据结构。MCP是一个新兴的、用于AI助手（如Codex, Copilot）与工具交互的标准化协议。这里可能定义了AI可以“读取图表”、“修改图形”、“查询元素”等工具（Tools）的输入输出格式。
• 共享类型：一些在core、extension、webview中都会用到的通用类型定义，比如Diagram,Shape,Point等。

为什么单独一个包？这保证了所有使用这些协议的地方，其数据类型都是一致的。无论是扩展发送给Webview的消息，还是MCP服务器返回给AI的数据，都遵循同一套定义。这从根源上避免了因拼写错误或类型误解导致的通信bug。在构建时，其他包只需将此协议包作为依赖引入即可。

5. 与AI助手集成：MCP服务器探秘

5.1 MCP是什么？为什么需要它？

MCP（Model Context Protocol）可以理解为AI助手的“插件标准”。它允许像Codex、Copilot这样的AI模型，在用户的授权和控制下，安全地调用外部工具、访问外部数据。对于Draw With You来说，集成MCP意味着：你可以用自然语言让AI助手帮你修改图表。

想象这些场景：

• “把图中所有‘服务器’形状的颜色改成蓝色。”
• “在‘用户’和‘API网关’之间添加一条箭头连线。”
• “总结一下当前架构图中第三页的所有组件。” 如果没有MCP，AI模型对这些请求无能为力，因为它无法“操作”你的绘图程序。有了MCP，Draw With You可以暴露出一系列安全的“工具”（Tools），例如change_shape_color、add_connection、list_components。AI模型在得到用户指令后，可以决定调用哪个工具，并生成符合协议格式的参数，最终由Draw With You来执行实际操作。

5.2 项目中的MCP服务器实现现状

根据项目描述，packages/mcp-server目录已经存在，并且包含了“工具/会话层和读取路径测试”。这意味着核心的MCP工具逻辑和权限会话管理已经搭建好了。

当前缺口：项目明确指出，它还没有暴露一个独立的、可供Codex连接的网络传输端点（HTTP/SSE）。你可以这样理解：发动机（工具逻辑）已经造好了，但还没有安装方向盘、油门和对外接口（网络服务器）。因此，目前你还无法在Codex中配置并实际使用它。

未来的连接方式：一旦这个传输层实现，配置起来会像项目示例中那样简单。你需要在Codex的配置文件中（如~/.codex/config.toml）添加这个MCP服务器。

[mcp_servers.drawWithYou] url = "http://127.0.0.1:7777/mcp" # 假设Draw With You的MCP服务器运行在本机7777端口

或者在命令行中执行：

codex mcp add drawWithYou --url http://127.0.0.1:7777/mcp

配置成功后，当你下次在Codex聊天框中输入“帮我把图中的数据库图标放大”，Codex就能理解你的意图，并通过MCP协议调用Draw With You提供的resize_shape工具来完成操作。

5.3 安全与权限考量

让AI操作你的图表，安全是首要问题。一个设计良好的MCP服务器必须包含：

1. 会话隔离：每个AI对话会话应该是独立的，不能互相干扰。
2. 操作确认：对于高风险操作（如删除图形），可能需要用户二次确认。
3. 权限范围：AI可能只能操作当前打开的、用户指定的图表，而不能访问文件系统中的其他无关文件。packages/mcp-server中的“session layer”正是为了处理这些问题而设计的。

6. 扩展测试与调试进阶技巧

6.1 单元测试与集成测试策略

对于一个如此复杂的项目，健全的测试体系是保证代码质量的生命线。虽然README里没细说，但我们可以推测其应有的测试结构。

• packages/core单元测试：这是测试的重中之重。需要大量测试diff逻辑：给定两个文档状态，是否能正确生成预期的操作序列？测试序列化/反序列化：把一个复杂的图形模型转成XML再转回来，是否还能保持一致性？这些测试应该不依赖VS Code环境，可以单独用jest或mocha运行。
• packages/extension集成测试：这部分测试需要启动一个VS Code扩展测试运行环境。VS Code官方提供了@vscode/test-electron包来辅助。测试案例可能包括：扩展是否能正确激活？自定义编辑器是否能针对.drawio文件注册成功？命令是否能在命令面板中触发并得到预期响应？
• packages/editor-webview的模拟测试：Webview的UI测试比较棘手，因为它运行在浏览器环境中。一种策略是将UI逻辑与渲染逻辑分离，对核心的UI状态管理（如处理来自扩展的消息、管理图形选中状态）进行单元测试。对于与draw.io库的集成部分，可能需要进行基于真实DOM的集成测试，或者使用JSDOM进行模拟。

实操建议：在项目根目录运行npm test，看看是否已经配置了统一的测试脚本。观察各个子包package.json中的scripts，通常会有test:unit、test:integration等命令。

6.2 利用VS Code调试能力

开发VS Code扩展，必须熟练掌握其调试工具。

• 调试扩展主进程：这和你平时调试Node.js程序一样。在launch.json中配置好“Extension Host”启动后，你可以在扩展的TypeScript代码中（比如extension.ts）打上断点。当你在扩展开发主机中触发某个命令时，执行流就会停在你原项目窗口的断点处。
• 调试Webview内容：这是另一个关键技巧。Webview本质上是一个独立的浏览器实例。要调试它，你需要：
  1. 在扩展开发主机中，打开你的绘图编辑器。
  2. 按下Ctrl+Shift+P，输入并执行Developer: Open Webview Developer Tools。
  3. 这时会弹出一个类似于Chrome开发者工具的窗口！你可以在这里查看Console日志、检查DOM元素、设置断点调试Webview中运行的JavaScript（也就是你的editor-webview包的代码）。这对于解决Webview与扩展主进程通信问题、排查draw.io库的集成问题至关重要。

6.3 性能分析与优化点

图形编辑器在浏览器中运行，性能是一个挑战。当图表元素非常多（成百上千个）时，操作可能会变卡顿。

潜在优化方向：

1. 虚拟化渲染：只渲染视口内的图形元素。这对于大型图表至关重要。draw.io的MXGraph库本身可能有一些优化，但作为集成者，我们需要关注在Webview中传递大量数据时的性能。
2. 操作批处理：在协作场景下，如果用户快速连续操作（比如拖动图形），不应该每一个mousemove事件都触发一次完整的差异计算和网络同步。应该进行防抖（debounce）或节流（throttle），并将一段时间内的多个操作合并为一个批量操作进行同步。
3. Webview通信优化：Webview和扩展主进程之间的postMessage通信是异步且有一定开销的。应避免频繁发送小消息，可以合并状态更新。项目中的“Active Diagram State”命令，可能就是通过一次性请求整个状态，而不是监听无数个细粒度事件来实现的。

7. 从零开始贡献与项目演进思考

7.1 如何为这个项目贡献代码？

如果你对这个项目感兴趣，想参与进去，可以遵循以下路径：

1. 熟悉代码库：首先按照前面的步骤，把项目在本地跑起来，通过冒烟测试。然后，花时间阅读DRAW_WITH_YOU_SPEC.md文件，这是项目的权威规划，理解整体的架构蓝图和未来方向。
2. 寻找切入点：查看GitHub仓库的Issues页面，寻找标记为good first issue或help wanted的标签。这些通常是相对独立、难度适中的任务，比如修复某个特定命令的bug、完善某个包的测试、或者实现一个协议中已定义但未实现的小工具。
3. 理解开发流程：项目可能使用了特定的Git分支策略（如Git Flow）或提交信息规范（如Conventional Commits）。在贡献前，最好先查看是否有CONTRIBUTING.md文件。
4. 动手实现：以实现一个简单的MCP工具为例。假设你想增加一个get_diagram_summary工具，让AI能获取图表摘要。
   • 首先，在packages/protocols中定义这个工具的输入输出类型。
   • 然后，在packages/mcp-server中实现这个工具函数，它需要调用core包的能力来分析当前文档模型，生成摘要文本。
   • 接着，将这个工具注册到MCP服务器的工具列表中。
   • 最后，在packages/extension中，确保当MCP服务器被请求时，能将当前活动的文档模型传递给MCP工具层。
5. 编写测试：为你新增的功能编写单元测试和集成测试。确保你的修改不会破坏现有功能。

7.2 技术选型的延伸思考

Draw With You的技术栈选择（TypeScript + VS Code API + Webview）是当前实现这类IDE集成工具的主流方案。但我们可以进一步思考其边界和替代方案。

• 为什么不是Electron独立应用？如果做成独立应用，就失去了与VS Code生态（如文件树、Git集成、终端、其他扩展）无缝集成的最大优势。用户需要来回切换应用，体验割裂。
• Webview的性能瓶颈与未来：Webview虽然是当前唯一选择，但它是一个独立的浏览器实例，内存和性能开销相对较大。未来，如果VS Code提供更底层的、基于WebGPU或原生Canvas的渲染API，图形编辑器的性能可能会有质的飞跃。
• 协作后端的选择：项目目前似乎聚焦于前端（编辑器）和协议。要实现真正的实时协作，必然需要一个后端服务来处理房间管理、操作转发、冲突解决等。这个后端可以用Node.js、Rust、Go等任何语言实现，通过WebSocket与前端通信。Draw With You的core包定义的协议，将成为前后端通信的基石。

7.3 可能遇到的挑战与应对

在开发或使用此类项目的早期版本时，要有心理准备迎接一些挑战：

• draw.io库的集成复杂度：draw.io是一个功能极其庞大的库，其API可能并不完全为外部集成设计。深入集成可能需要直接修改或封装其内部模块，这需要对其源码有较深的理解。
• 协作状态同步的难题：实现一个玩具级别的同步演示和实现一个生产级可用的同步引擎，难度天差地别。需要考虑网络断线重连、离线编辑合并、操作历史压缩、垃圾回收（删除元素的同步）等一系列复杂问题。
• 扩展的兼容性与性能：VS Code扩展运行在一个相对受限的沙盒环境中。当图表非常复杂时，Webview的内存占用和CPU使用率可能会很高，影响VS Code整体的流畅度。需要进行精细的内存管理和操作优化。

这个项目为我们打开了一扇门，让我们看到深度集成开发工具与专业领域工具的巨大潜力。它的实现思路，不仅适用于绘图，也可以借鉴到文档协作、数据库管理、API测试等任何需要与IDE深度交互的场景。