Figma Console MCP Cloud Write Relay架构剖析Cloudflare Durable Object如何实现网页AI跨云写入Figma【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcpFigma Console MCP 把 Figma 变成一套可供 AI 调用的设计系统 API而其中的Cloud Write Relay云端写入中继正是它最巧妙的部分借助 Cloudflare Durable Object网页端的 AI 客户端如 Claude.ai、v0、Replit、Lovable无需在你电脑上运行任何 Node.js 进程就能通过一条 WebSocket 隧道把创建组件、改变量、画 FigJam 便签等写操作直接送进你正在打开的 Figma 桌面文件。本文带你完整拆解这条跨云写入链路的架构与关键代码。一条链路串起三方Cloud Write Relay 整体数据流Local 模式下MCP 服务器跑在你本机插件通过ws://localhost:9223–9232直连简单直接。但网页 AI 客户端连不上你的 localhost——这正是 Cloud Write Relay 要解决的问题。整条链路只涉及 5 个环节AI 客户端Claude.ai 等 │ MCP 协议/mcp 端点 ▼ 云 MCP 服务器Cloudflare Worker / Durable Object │ fetch RPC ▼ PluginRelayDO中继 Durable Object │ WebSocketwss:// ▼ Desktop Bridge 插件ui.html → code.js │ figma.* Plugin API ▼ Figma 设计文件读操作走 Figma REST APIOAuth/PAT 鉴权写操作必须经过插件因为 Plugin APIfigma.createVariable()、figma.root等只能在 Figma 桌面环境的插件沙箱里执行。中继 DO 就是那条把云上的 HTTP 请求翻译成桌面上 WebSocket 消息的桥。完整设计说明见 architecture.md模式差异对比见 mode-comparison.md。六字符配对码一次性配对流程全解配对是整个 Cloud Mode 的入口由 AI 工具figma_pair_plugin触发源码在 src/index.ts核心步骤只有 4 步生成配对码调用 generatePairingCode()生成 6 位大写字母数字。字符表刻意排除了0/O/1/I避免用户输错——这种细节在 cloud-relay.test.ts 中有专门断言创建独立中继env.PLUGIN_RELAY.newUniqueId()为该会话创建一个专属 DO 实例KV 落库把pairing:{code} → relayDoId写入 Cloudflare KV5 分钟 TTL、一次性消费用完即删无法重放插件拨入你在 Figma 桌面端打开 Desktop Bridge 插件UI 见 ui.html打开 Cloud Mode 开关、输入配对码、点击 Connect。插件经wss://.../ws/pair?codeXXX拨入Worker 在 KV 中校验并立即删除配对码随后把 WebSocket 升级到对应 DO 上。配对成功后云 MCP 服务器拿到 96 个工具覆盖设计创建、变量 CRUD、组件操作、FigJam、注释、Slides 等写能力。PluginRelayDO 解剖一个 DO三条路由中继 DO 的全部逻辑集中在 cloud-websocket-relay.ts对外只有 3 条路由见 fetch 分发路由方向作用/ws/connect插件 → DOWebSocket 升级入口新连接会挤掉旧连接保证一个 DO 只对一个插件/relay/command云服务器 → DOfetch RPC 入口把命令转发给插件并挂起等待回包/relay/status云服务器 → DO查询插件是否在线、当前文件、待处理命令数其中/relay/command是最有意思的一段handleRelayCommandDO 收到命令后生成relay_{n}_{timestamp}请求 ID通过插件 WebSocket 发出去然后把 HTTP 响应挂起不返回把 resolve 函数存进内存pendingRequests。插件回包到达时webSocketMessage按 ID 找到挂起的请求并兑现 Response超时默认 15 秒则回 504。断线时所有在途命令统一以 502Plugin disconnected收尾不会留下悬挂请求。休眠安全设计为什么空闲时几乎不花钱Durable Object 在没有请求时会自动休眠hibernate而休眠会清空内存。Cloud Write Relay 对此做了三处针对性设计WebSocket 不落内存属性连接句柄不用类属性保存而是每次通过this.ctx.getWebSockets(plugin)重新获取——这是唯一能在 DO 从休眠中被唤醒后仍然拿到 WebSocket 的方式文件信息落 DO Storage插件上报的FILE_INFO文件名、fileKey、当前页写入ctx.storage休眠恢复后依然可读PAGE_CHANGE事件会实时更新它在途请求放心留在内存只要 fetch 还挂着DO 就不会休眠所以pendingRequests无需持久化。这个唤醒即取的模式让 AI 对话中轮次与轮次之间的空窗期几乎零成本是 Serverless 上做长连接中继的关键技巧。CloudWebSocketConnector让工具与传输彻底解耦云端这一侧的连接器是 cloud-websocket-connector.ts 中的CloudWebSocketConnector。它实现统一的IFigmaConnector接口所有方法最终收敛到一个私有sendCommand(method, params, timeoutMs)POST 到https://relay/relay/command等 DO 回包后解出result或抛出error。这套抽象带来两个直接收益工具一致性registerWriteTools()是本地与云端共用的注册函数本地在 src/local.ts 调用云端在 src/index.ts 调用同一批写工具在两种模式下行为一致只是底下换了连接器安全的路由拒绝Cloud Mode 一次只配对一个插件实例因此executeCodeViaUI显式拒绝fileKey参数——宁可报错也不让想写 B 文件却写进了 A 文件这种静默错路由发生见 相关测试。不同命令还有精细的超时策略普通命令 15 秒REFRESH_VARIABLES给到 300 秒CREATE_COMPONENT_SET则按变体数量动态计算实现避免大批量生成组件时超时误报失败、重试又重复创建。安全设计四层防线Cloud Relay 的安全约束写得很克制详见 architecture.md 的 Security 章节配对码一次性6 字符码 5 分钟过期、首次使用即删除防重放会话隔离每次配对创建独立 DO 实例一个插件连一个中继无跨会话泄漏Bearer 绑定配对后DO ID 按relay:{bearerToken}存入 KV24h TTL只有完成鉴权的 AI 客户端会话才能把命令路由到自己的中继不留数据中继只负责转发命令和回包设计数据不落盘全程 TLSwss:// HTTPS。延伸阅读关键文件索引想继续深挖源码建议按这个顺序看文件说明src/core/cloud-websocket-relay.ts中继 Durable Object 全部逻辑约 250 行读完即通src/core/cloud-websocket-connector.ts云端连接器所有写命令的 RPC 封装src/index.tsfigma_pair_plugin工具与/ws/pair端点figma-desktop-bridge/code.js插件侧接收命令并调用 Plugin APIfigma-desktop-bridge/manifest.json插件清单导入 Figma 的入口wrangler.jsoncPLUGIN_RELAYDurable Object 绑定与 v4 迁移声明tests/cloud-relay.test.ts配对码生成与命令转发的单元测试一句话总结Cloud Write Relay 用一次性配对码 专属 Durable Object 休眠安全 WebSocket三件套把云上的 HTTP 世界和你桌面上的 Figma 无缝接在了一起——这正是 Figma Console MCP 能让网页 AI 直接动手改设计文件的核心所在。【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考