figma-vault

figma-vault

English · Русский

只需拉取一次 Figma 画板。之后，Claude Code、Codex 或任何 MCP Agent 都可以随时读取：离线使用，无需 Figma 令牌，也没有速率限制。

• 一次性批量请求 Figma，之后 Agent 查看多少次都不会产生额外请求。同一文件中的多个屏幕会共享结构读取和图像渲染批次。
• 图标无需任何成本。 一个实际屏幕有 141 个图标，而且没有产生额外请求。
• 提交知识库后，团队就无需访问 Figma。 无需许可证，也无需令牌。

30 秒即可试用。这个过程不需要 Figma 令牌：

npm i -g figma-vault
figma-vault init && figma-vault demo && figma-vault check

工作方式：拉取时会规范化画板并将其写入磁盘。之后，Agent 通过 MCP 读取它。

one developer:      figma-vault add <link>  →  vault  →  git commit
the rest of the team:  the agent reads it over MCP, no Figma token needed

问题

Figma 的 MCP 服务和 REST API 都有速率限制，有些账号的限制还非常低。构建 UI 时，Agent 会不断回看设计，检查边距、颜色或字体大小。一次会话中可能因此产生数十次调用。很快就会触及限制，工作也会停下来。

使用 figma-vault 后，Figma 调用次数不会随 Agent 的操作而变化。每个设计的调用次数固定，只在拉取时调用一次。

	Figma Dev Mode MCP	figma-vault
谁调用 Figma	Agent 在工作过程中调用	CLI 调用一次
调用次数	随 Agent 的工作量增加	每个设计固定
每位读取者都需要令牌吗	需要	不需要
支持离线使用吗	不支持	支持

这还带来一个额外好处：设计会成为仓库中的一个文件。没有 Figma 文件访问权限的开发者（没有许可证、权限或令牌）也能看到完整设计。

对比方式

其他项目也在解决同样的问题。Framelink Exporter 插件可以将设计导出为 zip 文件以供离线使用，Framelink 的 Figma MCP 也有缓存分支。figma-vault 采用了不同的方法：

• 知识库就是为提交到仓库而设计的。 一个人拉取设计，整个团队都可以从 git 读取。其他人无需访问 Figma。
• 图标不产生请求。 矢量路径随节点树一起提供，SVG 在本地构建。通过 Figma 渲染图标会占用图像渲染限额。
• 格式固定且经过验证。 doc.json 遵循明确的规范，严格的验证器会检查每个文件。

安装

需要 Node.js 22+。

npm i -g figma-vault

选项 1：按项目安装

figma-vault init

这会创建 .figma-vault/，在项目的 .mcp.json 中注册服务（其他条目会保留），将 .env 添加到 .gitignore，并为 Claude Code 安装 /figma 斜杠命令。

使用 --no-command 可跳过 /figma 命令，让 Agent 只能使用只读的 vault_* 工具。

选项 2：不在仓库中添加任何内容

figma-vault init --global

知识库位于 ~/.figma-vault/，服务则注册在 Agent 的用户配置中。项目仓库完全不会知道这个工具的存在。当你无法向项目添加配置或依赖项时，可以使用此选项。

用法

figma-vault add "https://figma.com/design/KEY/Project?node-id=127-4532"
# Export several selections together; links from the same file share requests:
figma-vault add "<frame link 1>" "<frame link 2>"
# Keep the node trees if image rendering is unavailable:
figma-vault add "<frame link 1>" "<frame link 2>" --no-assets
# A SECTION/CANVAS link can expand into its frames (up to 20 by default):
figma-vault add "<section link>" --expand --max-screens 20

要获取链接，请在 Figma 中右键点击一个画板，然后选择 Copy link to selection。

figma-vault limits "<frame link 1>" "<frame link 2>" # probe access before pulling
figma-vault list              # what has been pulled so far
figma-vault check             # verify the whole chain works
figma-vault demo              # add a demo design, no token needed

CLI 输出、错误和 MCP 工具说明默认使用英语；它安装的 /figma 命令也使用英语。README.ru.md 仅翻译了文档。

运行 init 后，Claude Code 有一个命令：

/figma <frame link> [more frame links...]

它会拉取设计，通过 MCP 读取设计，并遵循项目约定构建 UI。

在 Figma 中拉取一次会消耗多少请求

REST API 限额取决于令牌、套餐和席位类型。节点读取和图像渲染都属于 Tier 1 端点。figma-vault limits "<link>" [more links...] 每个文件会消耗一次浅层节点读取，以及最多 ceil(S/40) 次画板渲染请求。它会跳过将 SECTION 和 CANVAS 选区渲染为整张图像；不会探测其中的子画板。探测成功并不能保证完整拉取：渲染资源可能需要额外请求。

对于包含 S 个选中画板和 R 个不重复栅格资源的文件，如果每个画板上的栅格资源少于 40 个，成功拉取通常会使用：

	请求数
选中节点树（/v1/files/:key/nodes）	每个文件 1 次
截图和栅格资源（/v1/images，每批 40 个 ID）	每个文件 ceil((S + R) / 40) 次
带有本地几何信息的图标	0

例如，一个文件中的两个画板有三个不重复的栅格资源，如果五个 ID 能放入同一批次，则需要一次节点读取和一次图像渲染。单个画板上的栅格资源达到 40 个或更多时，截图会分别渲染。--expand 会先使用 depth=1 探测容器，每个文件至少会增加一次节点请求。SVG 回退渲染、失败的请求和重试都可能增加调用次数。在一个真实的 332 节点设计中，141 个图标无需渲染调用。 拉取完成后，Agent 不会再调用 Figma。

对照设计检查结果

figma-vault verify 会将 Agent 构建的页面与设计进行比较。该软件包不附带浏览器：快照使用项目现有的工具（Playwright、DevTools、Agent 的浏览器工具）生成。

1. 使用 data-figma-node-id="<root node id>" 标记页面的根元素，并使用节点 ID 标记主要区块。
2. figma-vault verify <docId> --snippet 会打印一段脚本。在页面上运行该脚本，并将返回内容保存到文件。
3. figma-vault verify <docId> --snapshot <file> 会检查该文件：
   • 文本： 设计中的每段可见文本都必须出现在页面上；
   • 几何信息： 每个已标记区块的位置和尺寸都必须与设计一致，默认容差为 2 px（--tolerance）。

结果为 PASS（退出代码 0）、FAIL（退出代码 1，并列出不一致之处）或 INCOMPLETE（退出代码 2，未标记任何元素，无法检查几何信息）。如果项目中有浏览器，/figma 命令会自行运行此步骤。

无需 Figma 令牌即可试用

只有拉取新设计时才需要令牌。读取设计无需令牌，除了负责拉取的人之外，其他人通常都采用这种配置。因此，无需创建令牌即可测试完整的安装：

figma-vault init && figma-vault demo && figma-vault check

check 会将真正的 MCP 服务作为子进程启动，并通过协议与之通信。出现实际故障时，它会以代码 1 退出，因此可用于 CI。

令牌

在 Figma 中，依次前往 Settings → Security → Personal access tokens → Generate new token。 该令牌只需要一个作用域：File content → Read-only。

在运行 CLI 的目录中，将令牌放入 .env 文件，作为一行 FIGMA_TOKEN=figd_...，或将其设为环境变量。如果两者都已设置， 则以环境变量为准。

Agent 获取的内容

MCP 服务提供六个只读工具：

工具	返回内容
vault_list	知识库中的设计
vault_get_doc	设计的节点树；maxDepth 用于限制深度
vault_get_node	单个节点的子树
vault_search	按名称或文本找到的节点
vault_get_tokens	颜色、字体排版、效果
vault_get_asset	图像或图标

树结构经过了标准化：

• 自动布局会转换为带有 gap 和 padding 的 mode: row|column；
• 坐标以父节点为基准；
• 样式、渐变和文本都采用一致且可预测的结构，其中包括同一文本内颜色不同的片段（text.runs）；
• Figma 中隐藏的节点会保留，并标记为 hidden: true。默认情况下 Agent 不会获取这些节点，但父节点会报告省略的节点数量（hiddenOmitted）。如果要构建一个在当前屏幕上关闭了可选插槽的可复用组件，请传入 includeHidden: true。

原始 Figma 响应会保存到旁边的 raw.json 中，供调试使用。

在一个真实设计中，标准化后的树缩小了约 7 倍：

raw.json   1.9 MB   raw Figma response
doc.json   256 KB   what the agent reads

这不只是节省磁盘空间。读取 256 KB 而不是 2 MB 的 Agent，重建 UI 的准确度会明显更高。

知识库布局

<vault>/
  index.json                 list of designs
  <docId>/
    doc.json                 normalized tree, the main artifact
    raw.json                 raw Figma response
    screenshot.png           render of the whole frame
    assets/                  icons and images

docs/CONTRACT.md（俄语）中介绍了 figma-vault/doc@1 模式。严格验证器会对其进行检查。使用 0.1.0（doc@0）拉取的知识库仍可照常读取，无需重新拉取。

doc.json 可独立使用：MCP 服务绝不会读取 raw.json，也不会访问网络。

已知限制

这是一个 MVP。目前还无法做到以下几点。

• 速率限制。 节点读取和图像渲染都属于 Tier 1。任一端点都可能返回 429，且限制可能持续数天。图标现在不再依赖渲染，但画框截图和光栅图像仍然依赖渲染。客户端最多重试三次，并遵循 Retry-After，等待时间不会超过一分钟。如果 Figma 要求等待数天，拉取操作会保留节点树，将原因记录为警告，而不会失败。拉取前请运行 figma-vault limits。
• 文本内片段只保留颜色和字重。 文本部分内容上的渐变、不同字体或下划线都会丢失。
• 组件变体较多的设计会生成较大的 doc.json。 现在会保留隐藏插槽。在一个包含 332 个节点的屏幕上，这增加了 3,400 个隐藏节点，文件也从 444 KB 增长到 5 MB。默认情况下 Agent 获取的内容仍约为 100 KB，但该文件会进入你的 git。

测试方式

仓库中的测试夹具是合成数据：共 29 个节点，足以安装工具并确认整个流程正常运行，无需 Figma 令牌。

我们另外使用两个内容未在此公开的真实设计检查了准确性。一个包含 332 个节点、深度为 15 层的产品屏幕测试结果如下：

检查项	结果
重建后的标记中包含的设计文本	41 项中的 41 项
图标	15 项中的 15 项，0 个失效链接
所需占位符	1 个（光栅头像）
较早一次已测量拉取中的 Figma 请求数	3 次（合并渲染之前）
doc.json 是否符合契约	通过

未检查： 像素级匹配。我们通过 npm run dev → /compare/<name>，将结果与 Figma 的参考渲染进行目视比较。figma-vault verify 会检查文本和标记区块的几何信息，但不会检查颜色、字体或像素。

有意不提供的功能

它不是 SaaS、Figma 替代品，也不支持实时同步。它没有身份验证、账单、团队或用户功能，也没有服务端。MCP 服务以子进程的形式在开发者的机器上运行，由 Agent 启动，并通过 stdio 通信。没有任何内容需要部署。

更多文档（俄语）

• docs/INTEGRATION.md：如何在团队中推广、无痕模式，以及无需 Figma 令牌进行检查。
• docs/ADAPT.md：如何使工具适配项目的设计系统。

开发

npm install
npm test          # 85 tests
npm run typecheck
npm run dev       # local preview of rebuilt markup and comparison with the design

两个 AI Agent 遵循 AGENTS.md 中的协议并行编写此项目：划分独立的代码区域、使用任务看板和共享日志。 每次提交都标注作者。

许可证

MIT