用途：Figma 的版本历史仅存在于 REST API 中，此技能直接调用 REST 完成三件事——列出文件版本历史（标签、描述、作者、时间戳、版本 id）、在指定 version_id 下快照整个文件或部分节点、对比两个版本（固定做页面结构差异，另可对指定组件做 depth=2 的深度差异）。
主要能力：列出带标签的版本，或用 --autosaves 包含未标注的自动保存；结果自动分页、按最新在前输出 version_id | created_at | author | label。快照用一行 curl 完成，省略 &version= 即取当前 HEAD；历史版本不可变，建议存盘后反复 diff。diff 脚本 scripts/diff-versions.mjs 可输出页面结构差异（2 次调用），传 --components 时对指定节点做深度对比，涵盖子节点增删、componentPropertyDefinitions 变化、名称与描述变化及变量绑定引用变化；--mode 支持 summary、standard（默认）、detailed。使用 current 或省略 --to 即对比 HEAD。
使用方式：需终端与令牌。Figma 连接的 OAuth 登录不授权这些 REST 调用，须自行生成个人访问令牌：Figma 设置 → Security → Personal access tokens，勾选 File content: read（及 File versions: read），然后在 shell 设置 export FIGMA_TOKEN="figd_…"，脚本运行时从环境变量读取，切勿把令牌写入技能文件。文件 key 取自 URL 中 /design/ 或 /file/ 后的路径段。所有请求发往 https://api.figma.com，头部为 X-Figma-Token: $FIGMA_TOKEN；端点参考 references/endpoints.md。运行环境需支持 shell，如 Claude Code、Cursor、Codex、Gemini CLI 等，纯 Claude Desktop 或 claude.ai 聊天界面（无 shell）不可用。
限制：diff 不追踪画布其他位置的组件实例（仅 --components 指定节点）、原始布局属性（hug/fill、未绑定的内边距与宽高、cornerRadius）、未绑定的填充/描边/效果、变量取值变化（Figma REST 从不暴露）以及样式内容，故“无变化”不代表真的没改动；需要逐次编辑的取证式历史可用桌面桥接插件的 figma_get_design_changes。旧 version_id 可能因套餐保留策略被清理，快照返回 404 通常意味着版本过期，需重新列出获取有效 id；403 表示令牌缺少 File versions: Read 权限，需重新签发。分页为游标式，after=<version_id> 返回更旧版本，list-versions.sh 已自动处理。