SuperAPI AI 工具集

verify-figma-mcp-transports

测试与质量

查看项目

更新于 10-15 20:30

技能介绍

用途:Figma MCP 工具可通过 REST(个人访问令牌)和 WebSocket(Figma 插件)两条路径回答同一问题。只修一条路径仍能通过类型检查,漂移是静默的。本技能要求两条路径都运行并机械比对,发现差异。两路径在本包何处分叉,见 packages/mcp/AGENTS.md。重要:本技能须在主线程运行,第三阶段是等待人工操作的硬性停止点,子代理无人可问会自行通过。

前置条件:已设置 FIGMA_PERSONAL_ACCESS_TOKEN,否则在阶段 0 停止并索取;已安装 Figma 桌面应用;被测工具已在探测脚本的 PROBES 中注册,未注册需先注册(见该文件头部注释)。

阶段 0:自行推导检查标准,阅读刚做的 diff,确定涉及的边界情况,再向人索取能覆盖这些情况的图层,而非让人凭空发明标准。用 AskUserQuestion 索取图层 URL(parseFigmaUrl 可直接从 URL 取出文件 key 与节点 id)。若同文件跨运行复用,可将 key 放入 SEED_MCP_PROBE_FILE_KEY,之后只传 --node-id。

阶段 1:仅 REST,无需他人。脚本调用与工具处理器相同的辅助函数,不要绕过它直接调 REST API。命令:bun packages/mcp/scripts/probe-transports.ts --probe <tool> --transport rest --file-key <key> --node-id <id>。失败时不要进入 WebSocket 准备阶段。

阶段 2:准备 WebSocket,构建插件(bun --filter figma-mcp build),后台启动中继(bun packages/mcp/bin/index.mjs socket),等待 WebSocket server running on port 3055。端口被占用时询问是否复用,不要杀掉非自己启动的进程。

阶段 3:交给人工(硬停止)。确认插件 dist 已重建、中继监听 3055、阶段 1 通过后,用 AskUserQuestion 询问,并给出三选项:就绪、演示如何重载插件、停止。

阶段 4:先检查中继日志出现 New client connected,再双路运行比对:bun packages/mcp/scripts/probe-transports.ts --probe <tool> --transport both --file-key <key> --node-id <id>。退出码决定是否有差异(0 表示所有比较字段一致),1 打印分歧,再按下表分类后判断是否为 bug。需运行阶段 0 选定的每个节点。

阶段 5:逐节点报告通过/失败,记录所用文件与节点,仅终止自己在阶段 2 启动的中继。

四种分歧分类:必须一致(默认,差异即 bug);仅传输独有(加入探测的 ignore);词汇不同(同一事物命名不同,如页面对插件 API 是 PAGE、对 REST 是 CANVAS,须报告、绝不 ignore);同字段不同渲染(两侧都返回该字段但值不同,须报告交人判断,不要归一化后比较,一次观察不等于规则)。

禁止:猜测 WebSocket 结果、复用早前运行或从 REST 回填;把“读代码看着对”当作验证;未获人工答复就进入阶段 4;一开始就把失败称作环境问题。查找时按符号搜索(PROBES、sendCommandToFigma、broadcastToChannel、local-default)。