用途：作为 Figma 转代码工作流的测量数据源。截图只描述某一个渲染状态，而节点 JSON 暴露该状态的几何、变换、可见性和图层不透明度，本工具据此提供可追溯的数值测量。
主要能力与流程：
- 定义状态与目标：从 Figma URL 解码文件 key，收集所在 frame 或 component-set id、各状态/变体 id、目标图层映射，以及重建动画时所需的有序原型边。URL 中的 node-id=123-456 解码为 123:456。可通过 Figma MCP 元数据工具枚举组件集，或对 component-set 节点用 REST nodes 端点加 depth=1 发现直接变体子节点。按结构路径加名称映射对应图层，名称重复时附加同级索引。
- 在对话外部认证：从进程环境读取 FIGMA_TOKEN，需 file_content:read 权限及目标文件访问权。密钥不得出现在对话、文件、命令输出或提交中。
- 有界批量获取节点 JSON：可一次请求全部 id，过大则分批并固定同一 Figma 版本；用 depth 避免拉取无关后代，仅在需要矢量路径数据时加 geometry=paths。示例命令保留原样：curl --fail-with-body --silent --show-error -H "X-Figma-Token: $FIGMA_TOKEN" --get "https://api.figma.com/v1/files/$FILE_KEY/nodes" --data-urlencode "ids=$IDS" "${DEPTH_ARGS[@]}" --output "$CACHE_PATH"。将响应存入受限权限临时文件，校验为 JSON，记录返回版本，nodes 中 null 视为节点缺失而非空节点。
- 规范化几何与可见性：递归遍历 document 子树，记录 id、名称、类型、结构路径、本地 x/y/width/height、rotation（省略默认 0 度）、absoluteBoundingBox 与 absoluteRenderBounds、relativeTransform、visible 与节点 opacity（省略默认 1）。absoluteBoundingBox 是页面空间轴对齐包围盒，已反映祖先缩放与旋转，但不是节点自身的有向矩形。CSS 边界处 Figma 正角度方向与 CSS rotate() 相反，需取负，并保留变换原点、翻转、倾斜和矩阵数据。有效图层不透明度为祖先链上节点不透明度的乘积，任一祖先不可见则标记隐藏；它不等于最终像素 alpha，因为绘制 alpha、蒙版、混合模式和效果仍会改变渲染结果。
- 选择基准后再转换坐标：以节点本地或所在 frame 坐标系中的像素值为规范实现值，并记录每个值的基准。仅在 frame 与目标在同一坐标基准且轴对齐时，才可用左/上百分比公式换算；旋转、倾斜、翻转的 frame 须先经变换矩阵表达。百分比是响应式实现选择，不证明像素精度。
- 将 Smart Animate 重建为过渡段：从原型反应构建状态图，按结构路径与名称映射对应图层，记录源/目标本地几何、变换、可见性和有效不透明度，原样记录过渡类型、时长、缓动、触发和延迟，每条边表示一个过渡段，仅在需要合并时间线时由累计时长推导关键帧偏移；弹簧等非 cubic-bezier 过渡须用支持弹簧的实现保留或标注为近似。
输出：紧凑表格，含文件 key 与 Figma 版本、状态、节点 id、名称、类型、结构路径、本地几何与变换字段、页面空间 absoluteBoundingBox 与可选渲染边界、可见性与有效图层不透明度，以及假设、缺失字段和不支持的变换或动画情形；动画工作额外为每个有序过渡段增加一行。
限制：需有效 Figma 令牌与文件访问权限；依赖 REST API 返回数据，缺失或 null 字段需明确标注；不将百分比视为像素精度证明，不将 Smart Animate 等同于把包围盒差异直接转为关键帧。