技能介绍

为什么需要这一步提取

在 Figma 到代码的迁移流水线里，最容易出问题的不是生成阶段写不出代码，而是前端该还原什么，从一开始就没有一份权威记录。设计文件的节点树、变量定义和素材资源分散在 Figma API 的不同端点里，如果靠截图、口述或零散的 Markdown 传递信息，下游每一步——token 映射、素材重建、代码评审——都会把误差放大一遍。因此，第一步应当是把文件 URL 加授权变成一份确定、可审查的磁盘快照，让后续原子都基于它工作。

提取过程的核心逻辑

输入保持最小：一个 Figma 文件 URL 或 node-id，加上用户提供的 OAuth token。token 通过 connector 式授权流程传递，不写入任何本地持久化存储。启动后，atom 做四件事：

拉取并遍历 REST 树：按 API 读取文件的节点树，建立 figma/tree.json，它是下游 token-map、generate、critique 各阶段的唯一事实来源。
提取设计变量：把文件中的变量与样式定义整理为 figma/tokens.json，供 token 映射阶段消费。
栅格化素材：将支持的图像类资源栅格化后写入 assets/ 目录，交给 generate 阶段的媒体环节。
登记不支持的节点：无法处理的节点类型不会被静默丢弃，而是记入 meta.json 的 unsupportedNodes[]，供人工审计缺口。

收敛条件是机械可验的：figma/tree.json 存在且非空、节点数至少为 1。文件为空或授权过期时直接报错终止，不做任何猜测式兜底。

适用边界与注意点

这个技能只负责迁移前半程的提取，不承诺覆盖整个迁移过程。几条红线值得注意：授权路径失败时，严禁拿截图"反推"节点树，伪造输入是下游污染最严重的来源；组件实例不能当作重复内容删除，componentRef 链接必须保留，让 token 映射阶段在正确的边界上做去重；交付前还要复核素材的来源与授权范围，遇到越权请求先停止，再给出合规的替代方案。