尧图网站建设 
实时同步的幕后mcp_excalidraw的WebSocket广播与浏览器远程渲染图片导出机制【免费下载链接】mcp_excalidrawMCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.项目地址: https://gitcode.com/gh_mirrors/mc/mcp_excalidrawmcp_excalidraw 是一个 MCP Server 与 Claude Code 技能让 AI 智能体以编程方式创建、编辑和导出 Excalidraw 图形。它的核心卖点之一是实时同步画布服务器默认http://127.0.0.1:3000作为状态中心通过WebSocket 广播把每一个元素变更推送到所有打开的浏览器标签页而截图/导出图片这类操作则由服务器远程指挥浏览器完成渲染再把结果传回。本文带你拆解这条链路的每一步。️ 一图看懂整体架构先记住三个角色角色职责所在位置画布服务器Express REST API WebSocket 服务器 内存状态元素、文件、快照默认127.0.0.1:3000驱动端MCP 工具 / CLI 命令 / HTTP 请求统一调用 REST APIsrc/core/canvas-client.ts浏览器画布加载 Excalidraw Web UI监听 WebSocket负责渲染与图片导出frontend/src/App.tsx核心设计原则只有一条写走 REST推走 WebSocket。任何一次创建、更新、删除都会先写入服务器内存再由broadcast()广播给所有已连接客户端。AI 智能体仅凭一句提示词就在 Excalidraw 画布上画出完整架构图4 倍速演示 WebSocket 广播机制从一条消息到所有浏览器连接建立时的全量快照浏览器标签页打开后前端会向服务器发起 WebSocket 连接前端用window.location.host自动拼接ws://或wss://地址见 frontend/src/App.tsx 的connectWebSocket。连接成功的那一刻服务器会立刻做两件事src/server.ts 第 83-103 行发送initial_elements消息——携带当前全部元素和全部图片文件让新打开的标签页瞬间追上画布现状发送sync_status消息——汇报元素数量和时间戳。这就是为什么你可以开着三个浏览器标签页中途关掉再打开也不会少画了一半。前端还有防重连保护如果旧连接还在CONNECTING状态就直接复用避免重复连接导致每条广播被处理两次。14 种消息类型覆盖全部画布事件所有广播消息都带一个type字段完整清单定义在 src/types.ts第 176-189 行共 14 种类别消息类型触发时机全量同步initial_elements、elements_synced、sync_status新连接、前端手动同步增量 CRUDelement_created、element_updated、element_deleted、elements_batch_created对应 REST 写操作文件files_added、file_deleted图片等二进制文件变更控制类canvas_cleared、set_viewport、export_image_request、mermaid_convert清空画布、视口控制、图片导出、Mermaid 转换前端的处理逻辑是一个大的switch分发器frontend/src/App.tsx 第 486 行起收到element_created就把新元素合并进场景收到canvas_cleared就清空场景收到export_image_request就进入导出流程下文详述。broadcast()的健壮细节广播函数本体非常简洁src/server.ts 第 59-74 行服务器用一个SetWebSocket维护所有客户端每次广播把消息JSON.stringify一次然后逐个send。两个值得注意的细节只向readyState OPEN的连接发送避免向半关闭的连接写入发送失败比如客户端已掉线时静默移除该客户端不让一个坏连接拖垮整轮广播。另外服务器在元素更新时还会自动重路由绑定箭头移动一个矩形后所有连在它上面的箭头会跟着重新计算端点并逐条广播src/server.ts 第 377-384 行。所以 AI 调整布局时你看到的是箭头牵着走的流畅效果而不是断开的线。️ 浏览器远程渲染图片导出的完整链路这是本项目最精巧的设计。为什么不能直接在 Node 服务器里导出图片因为 Excalidraw 的字体度量、手绘粗糙度、圆角渲染都依赖浏览器环境的 canvas/SVG 能力。所以服务器选择了一条遥控路线第一步REST 请求挂起等待浏览器回执CLI 的scene exportsrc/cli/commands/scene.ts 第 39-47 行或 MCP 的导出工具最终都调用exportImage(format, background)src/core/canvas-client.ts 第 183 行向POST /api/export/image发起请求。服务器端的处理src/server.ts 第 910-986 行分为四步前置检查如果没有任何浏览器连接clients.size 0直接返回503提示请先在浏览器中打开画布——这也是新手最常遇到的报错答案就是打开http://127.0.0.1:3000这个标签页生成请求号创建requestId把一个 Promise 存入pendingExports映射表并挂上30 秒超时此时 HTTP 响应会一直挂起等待浏览器回执强制对齐状态先广播一次initial_elements把所有标签页包括可能过时的旧标签页刷新到服务器的权威状态避免导出一张半新半旧的图下达渲染指令等待800 毫秒给浏览器留出处理全量刷新的时间后广播export_image_request消息带上requestId、格式png/svg和背景开关。第二步浏览器远程渲染并回传前端收到export_image_request后frontend/src/App.tsx 第 558-648 行调用 Excalidraw 官方导出函数SVG 格式exportToSvg()生成 SVG 元素XMLSerializer序列化为字符串PNG 格式exportToBlob()生成图片 Blob再用FileReader转成 base64 字符串。渲染完成后前端把requestId、格式和数据 POST 回/api/export/image/result。如果渲染中途失败也会带上error字段回传让服务器能明确区分没人应答和渲染报错。第三步多客户端取最大结果服务器收到回执后的策略src/server.ts 第 1001-1027 行相当务实保留最大的数据多个标签页可能同时应答服务器比较各份结果的data.length最大的那份获胜——因为数据量更大意味着承载的画布状态更完整3 秒收集窗口收到第一份结果后启动 3 秒窗口等其余标签页的响应到齐窗口结束就以当前最优结果 resolve 掉挂起的 PromiseHTTP 响应即刻返回容错某个客户端报错不 reject因为其他标签页可能仍然成功只有 30 秒内一份结果都没收到才会以Export timed out失败。于是整条链路闭环MCP/CLI → REST → 挂起 → WebSocket 广播 → 浏览器渲染 → REST 回执 → Promise 兑现 → JSON 返回 base64。 同款模式视口控制与 Mermaid 转换图片导出不是孤例。服务器对需要浏览器执行才能完成的操作统一采用请求-回执模式视口控制set_viewport广播让浏览器平滑滚动到内容/指定元素前端执行后 POST/api/viewport/result回执10 秒超时Mermaid 转换服务器把 Mermaid 源码广播给浏览器由浏览器侧的转换器frontend/src/utils/mermaidConverter.ts解析成 Excalidraw 元素再同步回来——转换依赖浏览器里的 Mermaid 运行时。这种状态在服务器、渲染在浏览器、信令走 WebSocket的分工是实时同步能保持轻量且一致的根本原因。❓ 新手常见问题速答Q导出图片时报 503 No frontend client connected必须有至少一个浏览器标签页连着画布打开http://127.0.0.1:3000即可。Q为什么新开的标签页能立刻看到完整画布因为 WebSocket 建连时服务器会推送initial_elements全量快照之后才是增量事件。Q多个 AI 会话能同时画一张图吗可以。所有驱动端都写同一个服务器状态广播保证所有标签页同步收敛/health接口还会实时报告当前websocket_clients数量。Q如何查看同步状态调用GET /api/sync/status返回元素数量、内存占用和 WebSocket 客户端数src/server.ts 第 1293-1304 行。 关键文件索引文件说明src/server.ts画布服务器REST 路由、broadcast()、导出/视口的请求-回执闭环src/types.ts14 种 WebSocket 消息类型定义frontend/src/App.tsx浏览器端WebSocket 连接、消息分发、远程渲染导出frontend/src/utils/mermaidConverter.ts浏览器侧 Mermaid 转 Excalidraw 元素src/core/canvas-client.tsMCP 与 CLI 共用的 REST 客户端封装含exportImagesrc/cli/commands/scene.tsCLI 的scene export图片导出命令理解了 WebSocket 广播和远程渲染导出这两条链路你就掌握了 mcp_excalidraw 实时同步的全部核心服务器是单一事实来源浏览器是渲染引擎而 WebSocket 是把两者缝合成一块活画布的那根线。【免费下载链接】mcp_excalidrawMCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.项目地址: https://gitcode.com/gh_mirrors/mc/mcp_excalidraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 实时同步的幕后：mcp_excalidraw的WebSocket广播与浏览器远程渲染图片导出机制
实时同步的幕后mcp_excalidraw的WebSocket广播与浏览器远程渲染图片导出机制【免费下载链接】mcp_excalidrawMCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.项目地址: https://gitcode.com/gh_mirrors/mc/mcp_excalidrawmcp_excalidraw 是一个 MCP Server 与 Claude Code 技能让 AI 智能体以编程方式创建、编辑和导出 Excalidraw 图形。它的核心卖点之一是实时同步画布服务器默认http://127.0.0.1:3000作为状态中心通过WebSocket 广播把每一个元素变更推送到所有打开的浏览器标签页而截图/导出图片这类操作则由服务器远程指挥浏览器完成渲染再把结果传回。本文带你拆解这条链路的每一步。️ 一图看懂整体架构先记住三个角色角色职责所在位置画布服务器Express REST API WebSocket 服务器 内存状态元素、文件、快照默认127.0.0.1:3000驱动端MCP 工具 / CLI 命令 / HTTP 请求统一调用 REST APIsrc/core/canvas-client.ts浏览器画布加载 Excalidraw Web UI监听 WebSocket负责渲染与图片导出frontend/src/App.tsx核心设计原则只有一条写走 REST推走 WebSocket。任何一次创建、更新、删除都会先写入服务器内存再由broadcast()广播给所有已连接客户端。AI 智能体仅凭一句提示词就在 Excalidraw 画布上画出完整架构图4 倍速演示 WebSocket 广播机制从一条消息到所有浏览器连接建立时的全量快照浏览器标签页打开后前端会向服务器发起 WebSocket 连接前端用window.location.host自动拼接ws://或wss://地址见 frontend/src/App.tsx 的connectWebSocket。连接成功的那一刻服务器会立刻做两件事src/server.ts 第 83-103 行发送initial_elements消息——携带当前全部元素和全部图片文件让新打开的标签页瞬间追上画布现状发送sync_status消息——汇报元素数量和时间戳。这就是为什么你可以开着三个浏览器标签页中途关掉再打开也不会少画了一半。前端还有防重连保护如果旧连接还在CONNECTING状态就直接复用避免重复连接导致每条广播被处理两次。14 种消息类型覆盖全部画布事件所有广播消息都带一个type字段完整清单定义在 src/types.ts第 176-189 行共 14 种类别消息类型触发时机全量同步initial_elements、elements_synced、sync_status新连接、前端手动同步增量 CRUDelement_created、element_updated、element_deleted、elements_batch_created对应 REST 写操作文件files_added、file_deleted图片等二进制文件变更控制类canvas_cleared、set_viewport、export_image_request、mermaid_convert清空画布、视口控制、图片导出、Mermaid 转换前端的处理逻辑是一个大的switch分发器frontend/src/App.tsx 第 486 行起收到element_created就把新元素合并进场景收到canvas_cleared就清空场景收到export_image_request就进入导出流程下文详述。broadcast()的健壮细节广播函数本体非常简洁src/server.ts 第 59-74 行服务器用一个SetWebSocket维护所有客户端每次广播把消息JSON.stringify一次然后逐个send。两个值得注意的细节只向readyState OPEN的连接发送避免向半关闭的连接写入发送失败比如客户端已掉线时静默移除该客户端不让一个坏连接拖垮整轮广播。另外服务器在元素更新时还会自动重路由绑定箭头移动一个矩形后所有连在它上面的箭头会跟着重新计算端点并逐条广播src/server.ts 第 377-384 行。所以 AI 调整布局时你看到的是箭头牵着走的流畅效果而不是断开的线。️ 浏览器远程渲染图片导出的完整链路这是本项目最精巧的设计。为什么不能直接在 Node 服务器里导出图片因为 Excalidraw 的字体度量、手绘粗糙度、圆角渲染都依赖浏览器环境的 canvas/SVG 能力。所以服务器选择了一条遥控路线第一步REST 请求挂起等待浏览器回执CLI 的scene exportsrc/cli/commands/scene.ts 第 39-47 行或 MCP 的导出工具最终都调用exportImage(format, background)src/core/canvas-client.ts 第 183 行向POST /api/export/image发起请求。服务器端的处理src/server.ts 第 910-986 行分为四步前置检查如果没有任何浏览器连接clients.size 0直接返回503提示请先在浏览器中打开画布——这也是新手最常遇到的报错答案就是打开http://127.0.0.1:3000这个标签页生成请求号创建requestId把一个 Promise 存入pendingExports映射表并挂上30 秒超时此时 HTTP 响应会一直挂起等待浏览器回执强制对齐状态先广播一次initial_elements把所有标签页包括可能过时的旧标签页刷新到服务器的权威状态避免导出一张半新半旧的图下达渲染指令等待800 毫秒给浏览器留出处理全量刷新的时间后广播export_image_request消息带上requestId、格式png/svg和背景开关。第二步浏览器远程渲染并回传前端收到export_image_request后frontend/src/App.tsx 第 558-648 行调用 Excalidraw 官方导出函数SVG 格式exportToSvg()生成 SVG 元素XMLSerializer序列化为字符串PNG 格式exportToBlob()生成图片 Blob再用FileReader转成 base64 字符串。渲染完成后前端把requestId、格式和数据 POST 回/api/export/image/result。如果渲染中途失败也会带上error字段回传让服务器能明确区分没人应答和渲染报错。第三步多客户端取最大结果服务器收到回执后的策略src/server.ts 第 1001-1027 行相当务实保留最大的数据多个标签页可能同时应答服务器比较各份结果的data.length最大的那份获胜——因为数据量更大意味着承载的画布状态更完整3 秒收集窗口收到第一份结果后启动 3 秒窗口等其余标签页的响应到齐窗口结束就以当前最优结果 resolve 掉挂起的 PromiseHTTP 响应即刻返回容错某个客户端报错不 reject因为其他标签页可能仍然成功只有 30 秒内一份结果都没收到才会以Export timed out失败。于是整条链路闭环MCP/CLI → REST → 挂起 → WebSocket 广播 → 浏览器渲染 → REST 回执 → Promise 兑现 → JSON 返回 base64。 同款模式视口控制与 Mermaid 转换图片导出不是孤例。服务器对需要浏览器执行才能完成的操作统一采用请求-回执模式视口控制set_viewport广播让浏览器平滑滚动到内容/指定元素前端执行后 POST/api/viewport/result回执10 秒超时Mermaid 转换服务器把 Mermaid 源码广播给浏览器由浏览器侧的转换器frontend/src/utils/mermaidConverter.ts解析成 Excalidraw 元素再同步回来——转换依赖浏览器里的 Mermaid 运行时。这种状态在服务器、渲染在浏览器、信令走 WebSocket的分工是实时同步能保持轻量且一致的根本原因。❓ 新手常见问题速答Q导出图片时报 503 No frontend client connected必须有至少一个浏览器标签页连着画布打开http://127.0.0.1:3000即可。Q为什么新开的标签页能立刻看到完整画布因为 WebSocket 建连时服务器会推送initial_elements全量快照之后才是增量事件。Q多个 AI 会话能同时画一张图吗可以。所有驱动端都写同一个服务器状态广播保证所有标签页同步收敛/health接口还会实时报告当前websocket_clients数量。Q如何查看同步状态调用GET /api/sync/status返回元素数量、内存占用和 WebSocket 客户端数src/server.ts 第 1293-1304 行。 关键文件索引文件说明src/server.ts画布服务器REST 路由、broadcast()、导出/视口的请求-回执闭环src/types.ts14 种 WebSocket 消息类型定义frontend/src/App.tsx浏览器端WebSocket 连接、消息分发、远程渲染导出frontend/src/utils/mermaidConverter.ts浏览器侧 Mermaid 转 Excalidraw 元素src/core/canvas-client.tsMCP 与 CLI 共用的 REST 客户端封装含exportImagesrc/cli/commands/scene.tsCLI 的scene export图片导出命令理解了 WebSocket 广播和远程渲染导出这两条链路你就掌握了 mcp_excalidraw 实时同步的全部核心服务器是单一事实来源浏览器是渲染引擎而 WebSocket 是把两者缝合成一块活画布的那根线。【免费下载链接】mcp_excalidrawMCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.项目地址: https://gitcode.com/gh_mirrors/mc/mcp_excalidraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考