失败恢复与常见误区

先定位失败发生在哪一层：连接、目标、工具参数、Figma 对象模型、渲染，还是产品需求。错误层级不同，恢复方式也不同。

常见症状与检查顺序

症状	优先检查	合理下一步
ping 不通	MCP 服务与插件是否打开	恢复连接后重新核对目标
写到错误文件	file claim、重名、前台路由	绑定准确 session，再读回文件名
节点不存在	当前文件、页、旧 ID	搜索语义名称并核对父路径
属性类型不兼容	API 返回的属性键、值类型、ID/key	依据实际 API 修正参数
Fill 设不上	是否为 Auto Layout 子项	先修正父子布局关系
文字不出现	字体、填充、可见性、裁切、父层边界	定向读节点并截图
翻牌不触发	实例与主变体 Trigger 冲突	读回两处 reactions
batch 超时	是否部分生效、是否仍有活跃调用	查询已有节点，避免重复创建
Hidden 泄露图案	交换实例是否影响显隐	把显隐职责放到外层容器

实际制作中的三次恢复

变量连接错误：创建 Collection 后，变量调用返回连接失败。先读回变量列表，确认尚未出现变量，继续完成基础组件；连接恢复后，再创建并绑定。最终变量存在由列表和节点绑定读回证明。

批量文字超时：工具报告 sandbox timeout，但文字节点已经建立。通过读回主组件确认，继续组合变体，没有重发整批文字。

实例交换泄露图案：切换 Artwork 后，隐藏状态的图案意外可见。使用父级 Artwork Frame 管理可见性，内部 Symbol 只负责交换；再检查十二张牌和四个变体。

这些记录展示排错方法，不代表当前版本每次都会发生同样故障。

给 AI 的故障报告

预期：Hidden 只显示卡背
实际：设置 Artwork 后可看到星球，Label 仍是“探索”
目标：figma-demo / Card 组件及棋盘实例
已知：State=Hidden；Artwork 使用实例交换
请读回显隐、父层级和属性引用，提出最小修复。
不要解除实例，不要先删掉所有卡牌重建。

什么情况下需要补充用户决策

工具错误通常先查事实；产品约束冲突才需要决定。例如三列卡牌在极窄屏中无法同时满足最小触摸范围和边距，需要比较布局策略。不要把能读取的 nodeId、文件名或现有样式反过来问用户。

练习与检查

选一条故障，把“重试一下”改成有条件的恢复流程：先读什么，什么证据说明可重试，如何避免重复，成功后验证什么。