用途
本技能用于 Figma REST API 的深度调试，针对标准错误处理无法解决的复杂问题：间歇性失败、非预期的响应结构、速率限制边界情况以及大型文件超时。适用于同步任务“随机失败”、小文件正常但设计系统文件出错、以及需要向 Figma 支持升级问题等场景。
主要能力
- 详细请求检查：使用
curl -v捕获完整 HTTP 请求/响应轨迹，并通过-w输出 DNS 解析、连接、TLS 握手、首字节时间（TTFB）、总耗时与响应体大小、状态码等耗时分解信息。 - 响应结构校验：提供 TypeScript 校验函数，检查 document 根节点缺失、页面为空、文件名为空、version 字段缺失、nodes 中为 null 的节点（在列表与获取之间被删除或不可见）、images 渲染失败（url 为 null）等问题。
- 速率限制边界测量：Figma 的速率限制按用户、按分钟计算，但确切限制未公开且随套餐层级与席位类型变化。技能提供测量函数，对只读端点（如
https://api.figma.com/v1/me）循环请求直至返回 429，记录已发请求数、首次触发限流的请求序号以及 Retry-After 值。 - 大型文件调试：大型 Figma 文件（1000+ 组件）可能导致响应超时（超过 30 秒）、内存问题（100+ MB JSON）以及重复重试引发的限流。技能提供按页面分块获取策略：先用
depth=1获取仅含页面的元数据，再逐页调用/v1/files/{key}/nodes?ids={page.id}并在页面之间保持请求间隔。 - 支持升级模板：提供向 Figma API 支持提交工单的模板，包含账号邮箱、套餐层级、端点、文件 key（非敏感）、问题描述、复现步骤、HTTP 状态、响应头（尤其是速率限制相关）、响应时间、出现频率、脱敏后的请求/响应以及环境信息（Node.js 版本、操作系统、区域、是否使用代理）。
使用方式
先通过 curl -v 与 -w 获取请求时序与状态信息，定位问题发生在网络层还是响应层；再用校验函数检查返回结构；若怀疑限流，则运行速率限制测量函数；若问题与文件体积相关，改用 depth=1 加逐页 /nodes 调用；最后按模板整理诊断数据提交支持工单。示例中通过 curl -sv ... | grep -E '^< (HTTP|retry-after|x-)' 发现失败并非随机，而是每小时整点集中出现（cron 惊群），并通过 -w '%{size_download}' 发现 48 MB 的完整树导致大文件失败。
前置条件
- 可访问应用日志
- 带详细模式的 curl 用于网络检查
- 用于测试的 Figma API 凭证
输出
- 捕获的详细请求/响应追踪
- 识别出的响应结构问题
- 实测的速率限制行为
- 通过页面级分块处理的大型文件
- 含诊断数据的支持工单
限制与说明
Figma 速率限制的确切数值未公开，且随套餐与席位类型变化，只能实测。资源方面技能引用 Figma 开发者论坛、Figma 支持与 Figma 状态页，具体 URL 未在资料中提供。后续进行负载测试时，资料指向 figma-load-scale 技能。本技能的收费、价格与平台可用性暂未提供。