SuperAPI AI 工具集

figma-blame-node

设计与创作

查看项目

更新于 10-16 01:24

技能介绍

用途:类似 git blame,但针对 Figma。给定一个节点和一个目标(componentPropertyDefinitions 的键,或某个后代子节点 id),定位首次引入该目标的版本,返回该版本的 version_id、label、user_handle、created_at,以及 attribution_certainty 和 probes_made。

主要能力:利用目标存在性的单调性做二分查找,约 log2(N) 次 API 调用,例如 200 个版本约 8 次探测,而非 200 次,对 Figma REST 的按令牌限流更友好。

使用方式:需终端与令牌。该技能运行 shell 命令,适用于 Claude Code(含 Claude Desktop 的 Code 标签页)、Cursor、Codex、Gemini CLI,不能在纯 Claude Desktop 或 claude.ai 聊天中运行。Figma 连接器的 OAuth 登录不授权这些 REST 调用,须自备个人访问令牌:Figma 中 Settings → Security → Personal access tokens,生成时勾选 File content: read(以及 File versions: read),然后 export FIGMA_TOKEN="figd_…"。脚本运行时从环境变量读取,切勿把令牌写入技能文件。所有请求使用 X-Figma-Token: $FIGMA_TOKEN 访问 https://api.figma.com。

文件 key 推导:FILE_KEY=$(echo "$FILE_URL" | sed -E 's#./(design|file)/([A-Za-z0-9]+).#\2#')

工作流:先确定节点与目标。node_id 通常是 COMPONENT_SET;目标为 --property '<key>'(如 Disabled#1:2)或 --child '<node_id>'(应出现在 node_id 下的后代节点 id)之一。可先用 ../figma-version-history/scripts/list-versions.sh ABC123def456 --autosaves 列出并核对版本。运行:node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --property 'Disabled#1:2';或 --child 695:340;也可加 --start 4096800000 --max 100 --no-autosaves 限定回溯范围与起始版本。

结果解读:attribution_certainty 为 exact 表示真实可归属版本引入;system_attributed 表示引入版本是系统自动保存(user 为 Figma),可用 --no-autosaves 重跑以对齐最近的带标签版本;exists_at_lookback_horizon 表示目标在扫描到的最旧版本中已存在,真实引入更早,需增大 --max;metadata_unavailable 表示在 --start 处引入但版本列表回溯范围内未找到作者元数据,引入真实但无法从 REST 归属用户。

限制与注意:二分查找假设目标只被添加一次且从未移除,若添加、移除后又重新添加,报告的可能为后一次重新添加。--start 必须包含目标,即搜索要求目标在起始版本(默认 HEAD/当前)存在;要追踪已被移除的内容,需选一个它仍存在的 --start。默认包含自动保存以获得更细归属,多数自动保存携带真实人类用户;--no-autosaves 仅保留人工标签归属。搜索中途出现 404 通常表示探测的 version_id 已被保留策略清理,可重跑,搜索会容忍并跳过缺失节点。