Novu figma-use 技能实战：Figma 插件 API 自动化中的设计结果验证与错误恢复工作流

本文基于 Novu 仓库中 .agents/skills/figma-use/ 技能下的 validation-and-recovery.md 参考文档，系统讲解当 AI Agent 通过 use_figma 工具在 Figma 文件中执行插件 API 脚本时，应如何选择 get_metadata 与 get_screenshot 两种验证手段、如何在 use_figma 报错后安全恢复，以及一份可直接照做的“创建—验证—修复”推荐工作流。读完后，你能够把多步骤的 Figma 自动化写入任务（批量生成组件变体、布局搭建、变量绑定等）组织成可验证、可回退、低成本的执行流程。

背景：figma-use 技能在 Novu 仓库中的位置

在 Novu 仓库的 .agents/skills/figma-use/SKILL.md 中定义了一个名为 figma-use 的 Agent 技能，其核心是通过 use_figma 工具在 Figma 文件上下文中执行 JavaScript（Figma Plugin API）。由于 use_figma 是写操作，每次调用都会改变文件状态，技能文档因此把“验证与恢复”列为与 API 规则同等重要的环节：

• 主技能文件 SKILL.md 第 6 节要求“小步增量执行，每步验证”，第 7 节专门讲错误恢复；
• 本文的参考文档 validation-and-recovery.md 是其中的验证工作流与错误恢复细则，SKILL.md 的 Reference Docs 表格将其定位为“多步写入或错误恢复时加载”的文档；
• 配套参考还有 gotchas.md（全部已知陷阱的 WRONG/CORRECT 对照）、api-reference.md（use_figma 环境中可用/不可用的 API 清单）、common-patterns.md（可运行的脚本骨架）。

需要强调的执行前提：use_figma 环境中 console.log() 的输出对 Agent 不可见，唯一的结果通道是脚本的 return 值；因此“验证”不是脚本内部的断言，而是调用外部只读工具（get_metadata / get_screenshot）对文件状态做外部观测。这也是本文工作流的核心逻辑。

两类验证工具：get_metadata 与 get_screenshot

参考文档给出的总原则是：每次 use_figma 调用后要用“对的工具”验证结果，但不要无差别地每次都调用 get_screenshot——它代价高昂，只应保留给视觉检查。

get_metadata：中间验证的首选

get_metadata 返回一棵包含节点 ID、类型、名称、位置与尺寸的 XML 树。它适合在流程中间做快速、廉价的结构性确认，可用于校验：

• 结构与层级：父子关系是否正确、组件嵌套与分区内容是否符合预期；
• 节点计数：预期创建的变体数量、子节点是否存在；
• 命名：变体属性名是否遵循 property=value 约定（例如 size=md、state=hover）；
• 定位与对齐：x/y 坐标、width/height 是否匹配预期；
• 布局属性：auto-layout 方向、sizing mode、内边距、间距；
• 组件集成员关系：预期变体是否全部位于 ComponentSet 内部。

参考文档给出的典型场景：

示例：创建了一个包含 120 个变体的 ComponentSet 后，
对该 ComponentSet 节点调用 get_metadata，
确认全部 120 个子节点存在且名称、尺寸、位置正确——
无需等待一次完整渲染。

即：在批量创建这类“数量多但结构可预期”的产物时，用 metadata 做计数与命名核对，比渲染截图快得多。

应该调用 get_metadata 的时机：

• 创建/修改节点之后——核对结构、数量、命名；
• 布局操作之后——核对位置与尺寸；
• 合并变体（combine variants）之后——确认所有组件都在 ComponentSet 里；
• 绑定变量之后——核对节点属性（必要时可再用 use_figma 读取已绑定的变量）；
• 多步工作流之间——在第 N+1 步开始前，先确认第 N 步真的成功了。

get_screenshot：每个关键创建里程碑之后

get_screenshot 渲染像素级精确的图片，它是唯一能验证视觉正确性的手段（颜色、文字渲染、效果、变量模式解析结果）。由于它更慢且返回大量数据，参考文档明确要求：不要每调用一次 use_figma 就跟一次截图，但每个重大里程碑之后都要截图，以便尽早发现视觉问题。

应该调用 get_screenshot 的时机：

• 创建组件集之后——确认变体观感正确、网格可读、没有塌陷或重叠；
• 完成一个布局组合之后——确认整体结构与间距；
• 绑定变量/模式之后——确认颜色与 token 正确解析；
• 任何修复或恢复操作之后——确认修复没有引入新的视觉问题;
• 向用户报告结果之前——作为最终视觉证据。

截图中最容易被漏掉的问题（参考文档特别点名的三类）：

• 文字被裁切——行高或 frame 尺寸切掉了字符的上下延伸部（descenders/ascenders）甚至整行；
• 内容重叠——因尺寸设置错误或缺少 auto-layout，元素彼此叠压；
• 占位文字残留——仍然显示 "Title"、"Heading"、"Button" 等占位文本而非真实内容。

源码级补充：脚本内联的 node.screenshot()

在 SKILL.md 的“Efficient APIs”一节中，use_figma 脚本本身还支持 await node.screenshot(opts?)：在同一个脚本内把某个节点捕获为 PNG 并内联返回，省去一次独立的 get_screenshot 调用。其行为细节包括：

// 在同一脚本内截图验证（图片随工具响应内联返回）
await frame.screenshot()

// 自定义缩放（默认自动缩放：0.5x，且最大边不超过 1024px）
await frame.screenshot({ scale: 2 })

// 包含兄弟节点的重叠内容
await frame.screenshot({ contentsOnly: false })

默认缩放为 0.5x，并自动把最大输出边限制在 1024px 以内；显式传入 { scale: N } 会绕过该上限。图片说明会自动附带节点元数据（如 "Card (300x150 at 0,60).png"），提供空间上下文。结合参考文档的分工原则，可以这样选择：中间步骤用 get_metadata，里程碑验证优先在脚本内 node.screenshot()，跨脚本的独立视觉复查用 get_screenshot。

错误恢复：use_figma 的原子性语义

这是整篇参考文档最重要的事实性前提，原文表述为：

use_figma 是原子的——失败的脚本不会执行。 脚本出错时，文件不会发生任何改变，状态与调用前完全一致。没有部分节点、没有孤儿元素，修复后重试是安全的。

换句话说，use_figma 与“边执行边写盘”的脚本执行器不同：它不是“执行到第 57 行崩了、留下 57 行副作用”，而是要么整体生效，要么整体不生效。这直接决定了恢复策略——不需要写补偿/回滚脚本，只需要修复后重放。

当 use_figma 返回错误时的恢复步骤（参考文档原文的五步流程）：

1. 停下——不要立即改代码重试。 先仔细读错误信息；
2. 理解错误。 多数错误源于：错误的 API 用法、未加载字体、非法属性值、或引用了不存在的节点；
3. 如果错误信息不明确，调用 get_metadata 或 get_screenshot 查看当前文件状态，确认没有任何东西被改动；
4. 根据错误信息修复脚本；
5. 重试修复后的脚本。

常见错误对照表：来自 SKILL.md 的实现级佐证

SKILL.md 第 7 节给出了同一恢复流程之上的“错误信息 → 可能原因 → 修复方式”对照表，正好覆盖参考文档中列出的四类常见错误成因：

错误信息	可能原因	修复方式
"not implemented"	使用了 figma.notify()	删除它——用 return 输出
"node must be an auto-layout frame..."	在 append 到 auto-layout 父节点之前设置了 FILL/HUG	把 appendChild 放在 layoutSizingX = 'FILL' 之前
"Setting figma.currentPage is not supported"	使用了同步页 setter（figma.currentPage = page）	改用 await figma.setCurrentPageAsync(page)——这是切换页的唯一方式
属性值越界	颜色通道 > 1（用了 0–255 而非 0–1）	除以 255
"Cannot read properties of null"	节点不存在（ID 错误、页面错误）	检查页面上下文、核对 ID
脚本挂起/无响应	死循环或未解决的 Promise	检查 while(true) 或漏掉的 await，确保代码可终止
"The node with id X does not exist"	父实例被某个子节点 detachInstance() 隐式分离，导致 ID 变化	从稳定的（非实例）父 frame 重新遍历发现节点

这张表与参考文档形成闭环：前一步“理解错误”时查这张表定位成因；“错误不明确”时按第 3 步用 get_metadata/get_screenshot 观测文件状态；最后修复重放。更多具体陷阱的 WRONG/CORRECT 代码对照可查阅 gotchas.md，例如新节点默认落在 (0,0) 互相叠压、颜色必须用 0–1 范围、addComponentProperty 返回的是字符串键等——这些正是“错误信息不清楚”时最容易反复踩的坑。

脚本成功但结果不对时的处置

参考文档与 SKILL.md 一致地补充了“成功 ≠ 正确”的分支流程：

1. 调用 get_metadata 检查结构正确性（层级、数量、位置）；
2. 调用 get_screenshot 检查视觉正确性，重点找文字裁切与元素重叠；
3. 定位差异性质——是结构性问题（层级错误、节点缺失）还是视觉问题（颜色错误、布局破损、内容被裁）；
4. 写一个只修复坏掉部分的定向脚本——不要推倒重建。

推荐工作流：创建—验证—修复的标准循环

参考文档最后给出的推荐工作流（原文流程）：

1. use_figma  →  创建/修改节点
2. get_metadata     →  验证结构、计数、命名、位置（快、廉价）
3. use_figma  →  修复发现的结构性问题
4. get_metadata     →  复核修复结果
5. ... 按需重复 ...
6. get_screenshot   →  每个重大里程碑之后做视觉检查

⚠️ 任何一步出错时：
   a. 仔细阅读错误信息
   b. get_metadata / get_screenshot  →  若错误不明确，检查文件状态
   c. 根据错误修复脚本
   d. 重试修复后的脚本（安全——失败的脚本不会修改文件）

这套循环的设计意图是成本分层：结构核对用廉价的 metadata，视觉核对用昂贵的截图，且只在里程碑触发；出错时则利用原子性把“恢复”简化为“读错—查表—修复—重放”。

与增量工作流规则的衔接

该工作流并非孤立存在，SKILL.md 第 6 节“Incremental Workflow”为其提供了配套约束，两者合起来才是一个完整的多步写入规范：

• 单次 use_figma 调用最多 10 个逻辑操作（一个“逻辑操作”= 创建节点 + 设置属性 + 挂到父节点下）；要建 20 个节点就拆成 2–3 次调用；
• 自顶向下、先占位后填充：先建顶层结构并对各分区设 placeholder = true，再逐次调用填充内容并清除占位；
• 每次调用必须 return 所有创建/变更的节点 ID（如 return { createdNodeIds: [...], mutatedNodeIds: [...] }）——这些 ID 是后续调用做验证与修复的引用基础，也是参考文档中“多步工作流之间先确认第 N 步”得以成立的前提；
• 先检查再创建：动手前先跑只读脚本盘点文件里已有的页面、组件、变量与命名约定，让自己的产出匹配既有约定。

SKILL.md 还给出了一张分步验证矩阵，可与参考文档的“何时用哪个工具”对照使用：

完成后...	用 get_metadata 查	用 get_screenshot 查
创建变量	集合数、变量数、模式名	—
创建组件	子节点数、变体名、属性定义	变体可见、未塌陷、网格可读
绑定变量	节点属性反映绑定	颜色/token 正确解析
组合布局	实例节点有 mainComponent、层级正确	无裁切文字、无重叠元素、间距正确

小结

validation-and-recovery.md 的价值在于把“AI Agent 驱动 Figma 自动化”这一高风险场景收敛为三条可操作原则：

1. 验证要分层：结构问题用 get_metadata（快、廉价、每步都做），视觉问题用 get_screenshot（慢、昂贵、里程碑才做），node.screenshot() 内联截图可作为脚本内的折中手段；
2. 恢复要基于原子性：use_figma 失败即整体不生效，恢复动作是“读错 → 查表定位 → 修复 → 重放”，不存在需要清理的半成品状态；
3. 循环要标准化：创建 → metadata 验证 → 修复 → 复核 →（里程碑）截图，出错则进入四步恢复支线。

结合 SKILL.md 的单次调用 10 操作上限、强制 return 节点 ID 与先检查后创建等规则，即可把批量变体生成、布局搭建、变量绑定这类多步写入任务控制在“每一步都可验证、出错每一步都可安全重试”的节奏内。