mcpField
F
figma-blame-node

figma-blame-node

github.com/southleft设计与 UI94120 次安装10 周前更新
代码仓库

关于 figma-blame-node

figma-blame-node 是一款基于命令行的技能，通过二分搜索找出 Figma 版本历史中首次出现某个组件属性或后代节点的版本。它返回版本及作者信息，并标示归因确定性。

主要功能

  1. 01二分搜索版本历史
  2. 02追踪组件属性或子节点
  3. 03返回版本标签、作者和时间戳
  4. 04提供归因确定性和探测次数
  5. 05选择包含或排除自动保存版本

适用场景

  1. 01查找组件属性的添加时间
  2. 02定位引入子节点的版本
  3. 03检查归因是否确切或受搜索范围限制
  4. 04选择是否搜索自动保存版本

MCP 相关

这是一个技能而非 MCP 服务；README 介绍了通过命令行使用个人访问令牌调用 Figma REST API。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/southleft/figma-console-mcp-skills --skill figma-blame-node

安装后在 Claude Code 中输入/figma-blame-node确认已加载。

附带文件scripts/blame-node.mjs

详细介绍

figma-blame-node — 通过二分搜索查找某项变更是在哪个版本引入的

类似于 git blame，但针对 Figma。给定一个节点和目标（componentPropertyDefinitions 键或后代子节点 ID），此工具会定位首次引入该目标的版本，并返回该版本的标签、作者账号和时间戳。

设置 — 需要终端和令牌。 此技能会运行 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_…"。脚本会在运行时从环境变量中读取该令牌——切勿将令牌放入技能文件中。

为什么使用二分搜索

朴素的遍历方式会在每个版本中获取节点——N 个版本需要调用 API N 次。目标是否存在具有单调性（添加后会一直存在于后续所有版本，直到 HEAD），因此我们使用二分搜索：探测中间版本，检查目标是否存在，然后缩小到较旧或较新的半区。只需 约 log2(N) 次调用——例如，200 个版本只需约 8 次探测，而不是 200 次。这种方式对速率限制更友好：Figma REST API 按令牌限流，而旧快照不可变，因此探测次数越少越好。

设置与技能边界

  • 所有请求都使用 X-Figma-Token: $FIGMA_TOKEN，目标地址为 https://api.figma.com。

推导文件键

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

工作流

  1. 确定节点和目标。 node_id 通常是 COMPONENT_SET。目标只能是以下其中一项：

    • --property '<key>' — componentPropertyDefinitions 键，例如 Disabled#1:2，或
    • --child '<node_id>' — 应当出现在 node_id 下的后代节点 ID。

    如果要限定搜索范围或检查 ID 是否合理，请先列出版本：

    ../figma-version-history/scripts/list-versions.sh ABC123def456 --autosaves

  2. 运行 blame 搜索，使用 scripts/blame-node.mjs：

    # When was a component property first added?
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --property 'Disabled#1:2'

# When was a child node first added under a component set?
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --child 695:340

# Bound the lookback and start from a specific version instead of HEAD
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --property 'Size#9:0' \
  --start 4096800000 --max 100 --no-autosaves

    脚本会输出 JSON：引入该目标的版本（version_id、label、user_handle、created_at）、attribution_certainty，以及 probes_made 计数，便于查看调用次数有多低。

解读结果

attribution_certainty 表示结果的可信程度：

  • exact — 目标由一个真实且可归属的版本引入。
  • system_attributed — 引入目标的版本是系统自动保存版本（user = "Figma"）。使用 --no-autosaves 重新运行，以定位包含此变更的最近一个带标签版本。
  • exists_at_lookback_horizon — 在扫描的最早版本中也存在该目标，因此真正的引入时间早于搜索范围。请增大 --max。
  • metadata_unavailable — 目标在 --start 版本中首次出现，但在回溯查询版本列表时未找到作者元数据。该引入确实发生过；只是无法通过 REST 确定用户身份。

注意事项与限制

  • 单调性假设： 二分搜索假设目标只添加一次，之后不会移除。如果目标先被添加、再移除、之后又重新添加，报告的引入位置可能是后一次添加。
  • --start 必须包含目标。 你要查询的是“此目标何时引入”，因此搜索要求目标在起始版本中存在（默认为 HEAD/current）。要追踪已移除的内容，请选择仍包含该内容的 --start 版本。
  • 默认包含自动保存版本，以便更准确地归属变更（多数自动保存版本会记录真实用户）。只想归属到由人类标记的版本时，请使用 --no-autosaves。
  • 搜索过程中出现 404，通常表示探测到的 version_id 已因保留策略而被清除——请重新运行；搜索会容忍并跳过缺失的节点。

评论

支持 Markdown