figma-version-history

figma-version-history — 列出、快照和比较 Figma 版本

版本历史记录仅存在于 Figma 的 REST API 中，因此此技能会使用个人访问令牌（PAT）直接调用 REST API。它可以完成三项操作：

1. 列出文件的版本历史记录（标签、描述、作者、时间戳、版本 ID）。
2. 快照文件（或仅快照部分节点），还原其在指定 version_id 时的状态。
3. 比较两个版本 — 始终提供轻量级的页面结构差异，还可选择深入比较各个组件，使用 depth=2。

设置 — 需要终端和令牌。 此技能会运行 shell 命令，因此可在 Claude Code（包括 Claude Desktop 内的“Code”标签页）、Cursor、Codex 或 Gemini CLI 中使用 — 但无法在普通 Claude Desktop 或 claude.ai 聊天中运行（没有 shell）。Figma 连接器的 OAuth 登录无法授权这些 REST 调用，因此你必须提供自己的 Figma 个人访问令牌：在 Figma 中前往 Settings → Security → Personal access tokens，生成一个具有 File content: read（以及 File versions: read）范围的令牌，然后在 shell 中设置：export FIGMA_TOKEN="figd_…"。脚本会在运行时从环境变量中读取令牌 — 切勿将令牌放入技能文件中。

设置和技能边界

• 所有请求都会发送到 https://api.figma.com，并附带标头 X-Figma-Token: $FIGMA_TOKEN。
• 端点参考：references/endpoints.md。

提取文件键

文件键是 Figma URL 中 /design/ 或 /file/ 后面的路径段：

FILE_URL="https://www.figma.com/design/ABC123def456/My-File"
FILE_KEY=$(echo "$FILE_URL" | sed -E 's#.*/(design|file)/([A-Za-z0-9]+).*#\2#')
echo "$FILE_KEY"   # ABC123def456

工作流

1. 列出版本，找到你需要的 version_id。运行 scripts/list-versions.sh：

   ./scripts/list-versions.sh ABC123def456              # labeled versions only (default)
   ./scripts/list-versions.sh ABC123def456 --autosaves  # include unlabeled auto-saves
   

   脚本会自动分页（按时间从新到旧），并输出 version_id | created_at | author | label。 默认会过滤掉没有标签的自动保存记录；传入 --autosaves 可保留这些记录。

2. 使用一行 curl 命令快照某个版本（快照当前版本/HEAD 时省略 &version=）。将结果保存到磁盘，这样就能反复比较，而无需重新获取 — 过去的版本不可变：

   # Whole file at a past version (depth=1 keeps it small for orienting)
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY?version=4096761871&depth=1" \
     > /tmp/v-4096761871.json
   
   # Just specific nodes at that version (much smaller payload)
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=695:313&version=4096761871&depth=2"
   
   # Current / HEAD — omit the version param entirely
   curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/$FILE_KEY?depth=1"
   

3. 使用 scripts/diff-versions.mjs比较两个版本。它会获取两个快照，计算页面结构差异（轻量级，只需调用 2 次），并且 — 如果传入 --components — 深入比较深度为 2 的各个节点（子节点的添加/移除、名称/描述更改、COMPONENT_SET 的 componentPropertyDefinitions 更改，以及 boundVariables 差异）：

   # Page-structure diff only (2 API calls)
   node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to current
   
   # Deep diff of specific component sets (2 calls per node), detailed verbosity
   node scripts/diff-versions.mjs --file ABC123def456 --from 4096761871 --to 4096800000 \
     --components 695:313,420:88 --mode detailed
   

   使用 current（或省略 --to）可将版本与 HEAD 比较。--mode 可以是 summary（仅显示数量）、 standard（显示名称和数量，默认值）或 detailed（显示完整的属性/绑定详情）。

差异会追踪和不会追踪的内容

差异报告会如实说明自身的盲点 — 不要将“没有更改”理解为“什么都没变”：

• 会追踪： 页面结构（页面的添加/移除/重命名）；指定节点上的子节点添加/移除、componentPropertyDefinitions（添加/移除/类型/默认值更改）、名称和描述更改，以及变量绑定引用。
• 不会追踪： 放置在画布其他位置的组件实例（仅追踪通过 --components 传入的节点）、原始布局属性（hug-vs-fill、未绑定的内边距/宽度/cornerRadius）、未绑定的填充/描边/效果、变量值更改（Figma REST API 从不公开这些值），以及样式内容。若要获取包含原始属性更改在内的逐次编辑历史以供取证，实时 Desktop Bridge 插件的 figma_get_design_changes 可作为补充工具。

注意事项

• Figma 的版本分页采用游标方式：after=<version_id> 会返回时间上更早的版本（列表按时间从新到旧）。list-versions.sh 会为你处理这些细节。
• Figma 可能会根据套餐级别的保留政策清理旧的 version_id — 快照时出现 404 通常表示该版本已超出保留期限，而非键有误。请重新列出版本以获取有效 ID。
• 这些端点返回 403 表示你的 PAT 缺少 File versions: Read 范围 — 请重新签发令牌。