SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pp-figma

pp-figma

编程与开发

查看项目

更新于 10-15 16:39

技能介绍

用途

pp-figma 是一个离线优先、面向智能体的 Figma 命令行工具（figma-pp-cli）。它把 Figma REST API 的每个端点吸收为一个 Cobra 命令，并移植了 GLips 的压缩管线，使画框提取结果能放进 LLM 上下文窗口。它面向需要把 Figma 文件当作数据（而非像素）来推理的智能体或工程师，适用于代码生成提示上下文、设计系统运维、评论卫生与 webhook 迭代等场景。交互式设计工作仍可使用 Figma 桌面应用。

主要能力

智能体原生管线

  • frame extract：将单个画框提取为紧凑的、适合代码生成的载荷，融合简化节点树、作用域内变量、开发资源与 Code Connect 映射。首次调用即可为 AI 智能体提供 Figma 画框上下文，返回可放入上下文窗口的紧凑载荷，而非原始 10MB 文件响应。
  • dev-mode dump：输出可移植的 Markdown 包，融合开发资源链接、作用域内变量、渲染永久链接与 Code Connect 映射，无需桌面配对。
  • webhooks test：拉取 Figma 的 webhook 请求日志，并将存储的载荷（含原始请求头与 HMAC）重放到任意目标 URL，便于在本地服务器上重放昨日失败的投递。

可累积的本地状态

  • comments-audit：跨所有已同步的团队文件聚合未解决评论，支持按时间与分组过滤。
  • orphans：通过连接团队库发布列表与库分析使用数据，查找在指定窗口内零使用的已发布库实体（组件、样式、变量）。
  • tokens diff：以模式感知方式对比两个文件版本的 Figma 变量，输出 Markdown 或 JSON 变更集。
  • fingerprint：生成 Figma 文件令牌、组件与样式表面的稳定哈希；当 --expect 不匹配时以非零退出，可接入 CI。
  • variables explain：列出文件中引用给定变量的每个节点与组件，用于规划变量重命名或弃用前评估影响范围。

使用方式

前置条件

必须先安装 CLI。通过 Printing Press 安装器安装（macOS/Linux 默认二进制目录为 $HOME/.local/bin，Windows 为 %LOCALAPPDATA%\Programs\PrintingPress\bin）：

npx -y @mvanhorn/printing-press-library install figma --cli-only

验证：figma-pp-cli --version。确保安装目录在调用该技能的智能体/运行时的 $PATH 中。

若 npx 安装失败（无 Node、离线等），可回退到直接 Go 安装（需要 Go 1.26.6 或更新版本），安装到 $GOPATH/bin（默认 $HOME/go/bin）：

go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-cli@latest

若 --version 报“command not found”，说明运行时看不到二进制目录，需先解决 $PATH 问题再继续。

认证设置

Figma 支持两种认证模式：个人访问令牌（请求头 X-Figma-Token，前缀 figd_）用于个人/自动化；OAuth 2.0（Authorization: Bearer）用于 /v1/me、/v1/activity_logs 与 /v1/developer_logs。设置 FIGMA_API_TOKEN（PAT）或 FIGMA_OAUTH2（OAuth Bearer），CLI 会自动路由到正确的请求头。运行 figma-pp-cli auth login 进行 OAuth，或通过 figma-pp-cli auth set-token 保存 PAT 到配置文件。运行 figma-pp-cli doctor 验证设置。

智能体模式

在任意命令后加 --agent，展开为：--json --compact --no-input --no-color --yes。特点包括：可管道（stdout 输出 JSON，stderr 输出错误）、可过滤（--select 保留字段子集，支持点路径与数组遍历）、可预览（--dry-run 显示请求而不发送）、离线友好（sync/search 命令在可用时使用本地 SQLite 存储）、非交互（从不提示，所有输入均为标志）、显式重试（--idempotent 与 --ignore-missing）。

响应信封

从本地存储或 API 读取的命令会将输出包装在来源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，.meta.source 判断是实时还是本地。

输出投递

每个命令接受 --deliver <sink>，支持 stdout（默认）、file:<path>（原子写入）、webhook:<url>（POST 输出体）。未知方案会被拒绝并返回结构化错误。

命名配置档

配置档是一组保存的标志值，可跨调用复用。命令包括 profile save/list/show/delete。显式标志优先于配置档值，配置档值优先于默认值。

退出码

0 成功；2 用法错误；3 资源未找到；4 需要认证；5 API 错误；7 速率限制；10 配置错误。

查找命令

当知道要做什么但不知道用哪个命令时，可询问 CLI：figma-pp-cli which "<用自己的话描述的能力>"。退出码 0 表示至少一个匹配，2 表示无自信匹配。

MCP 服务器安装

go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-mcp@latest
claude mcp add figma-pp-mcp -- figma-pp-mcp

验证：claude mcp list。

命令参考（部分）

  • activity-logs：以组织管理员身份获取活动日志。
  • component-sets / components / styles：按 key 获取已发布组件集、组件、样式的元数据。
  • dev-resources：在 Figma Dev Mode 中交互开发资源，支持批量创建与更新。
  • developer-logs：获取组织内 REST API 与 MCP 服务器请求的开发者日志。
  • figma-analytics：管理 Figma 分析，包括库组件/样式/变量的操作与使用数据。
  • files：获取文件 JSON、图像及其他文件相关内容。
  • images：从文件渲染图像。
  • me：返回当前认证用户信息。
  • oembed：获取 Figma 文件与已发布 Make 的 oEmbed 数据。
  • payments：获取社区资源的购买信息。
  • projects：获取团队中的项目与文件信息。
  • teams：管理团队。
  • webhooks：以团队管理员身份交互团队 webhook，支持 delete/get/get-webhookid/post/put。

适用场景

  • 为 AI 代码生成准备 Figma 画框上下文（frame extract、dev-mode dump）。
  • 设计系统运维（orphans、tokens diff、fingerprint）。
  • 评论卫生（comments-audit）。
  • webhook 迭代（webhooks test）。
  • 在 CI 中检测上游 Figma 文件设计系统表面漂移。

限制

  • orphans 命令需要 Enterprise 层级。
  • webhooks test 的 HMAC 重签名尚未接入，处理器必须接受未签名重放以进行测试。
  • 直接 Go 安装需要 Go 1.26.6 或更新版本。
  • 反馈条目默认仅本地存储，除非设置 FIGMA_FEEDBACK_ENDPOINT 且传入 --send 或设置 FIGMA_FEEDBACK_AUTO_SEND=true。
  • 其他未在资料中说明的功能、收费、价格、平台或效果暂未提供。