pp-figma

Figma — Printing Press CLI

前置条件：安装 CLI

此技能使用 figma-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

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

2. 验证：figma-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果通过 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。该方式会将文件安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录添加到 $PATH：

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

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。验证成功之前，请勿运行此技能中的命令。

此 CLI 是离线优先、面向 Agent 的 Figma 操作工具。它将每个 REST 端点封装为一个 Cobra 命令，移植了 GLips 的压缩流程，让帧提取内容能够放入大模型上下文窗口，并添加了其他工具都未整合的分析原语：跨文件评论审计、过时组件孤立项查找、不同文件版本间的语义令牌差异比较、用于 CI 的确定性文件指纹，以及 Webhook 投递重放。

何时使用此 CLI

当 Agent 或工程师需要将 Figma 文件作为数据（而非像素）进行分析时，请使用 figma-pp-cli。它特别适用于代码生成提示词上下文（frame extract、dev-mode dump）、设计系统运维（orphans、tokens diff、fingerprint）、评论管理（comments audit）和 Webhook 调试（webhooks test）。进行交互式设计时，Figma 桌面应用就足够了；figma-pp-cli 涵盖了 Figma REST API 提供的所有功能，并额外提供了仪表板未展示的跨文件分析命令。

独特功能

这些功能在此 API 的其他工具中都不可用。

面向 Agent 的基础设施

• frame extract — 将单个帧提取为精简、可用于代码生成的载荷，其中整合了简化的节点树、作用域内变量、开发资源和 Code Connect 映射。

  当 AI Agent 需要 Figma 帧上下文来生成代码时，首先调用此命令。它会返回可放入上下文窗口的精简载荷，而不是原始的 10MB 文件响应。

  figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json
  

• dev-mode dump — 生成可移植的 Markdown 文件包，其中整合了开发资源链接、作用域内变量、渲染永久链接，以及单个节点的 Code Connect 映射。

  当 Agent 或工程师需要将单个帧的完整 Dev Mode 上下文汇总到一个 Markdown 块中时使用，无需配对桌面端。

  figma-pp-cli dev-mode dump abc123 --node 1234-5678 --format md
  

• webhooks test — 获取 Figma 的 Webhook 请求日志，并将已存储的载荷（含原始标头和 HMAC）重放到任意目标 URL。

  在调试新的 Webhook 处理程序时使用——将昨天失败的投递重放到本地服务，无需重新触发上游事件。

  figma-pp-cli webhooks test wh_abc --replay-failed --target-url https://localhost:3000/figma
  

会不断积累的本地状态

• comments-audit — 汇总所有已同步团队文件中的未解决评论，并支持按时间和分组筛选。

  在周一早晨设计评审前运行此工具——找出团队中所有长期未解决的讨论串。

  figma-pp-cli comments-audit --older-than 14d --group-by file,author --json
  

• orphans — 将团队库发布列表与库分析使用数据关联，查找在指定时间段内使用次数为零的已发布库实体（组件、样式、变量）。

  季度设计系统清理的第一条命令——返回可安全弃用的实体列表。

  figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
  

• tokens diff — 对比两个文件版本中的 Figma 变量，支持按模式感知差异；输出 Markdown 或 JSON 格式的变更集。

  在合并设计令牌 PR 前运行，查看自上次发布以来 Figma 中实际发生的变更。

  figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
  

• fingerprint — 为 Figma 文件的令牌、组件和样式表面生成稳定哈希；如果 --expect 不匹配，则以非零状态码退出。

  将此工具接入 CI，当上游 Figma 文件的设计系统表面偏离已提交的快照时，让构建失败。

  figma-pp-cli fingerprint abc123 --expect sha256:a1b2c3...
  

• variables explain — 列出文件中引用指定变量的所有节点和组件。

  规划变量重命名或弃用时的首个调用——在动手前查看影响范围。

  figma-pp-cli variables explain abc123 --variable color/brand/primary --json
  

命令参考

activity-logs — 以组织管理员身份获取活动日志。

• figma-pp-cli activity-logs — 返回活动日志事件列表

component-sets — 获取已发布组件集的信息。

• figma-pp-cli component-sets <key> — 根据键获取已发布组件集的元数据。

components — 获取已发布组件的信息。

• figma-pp-cli components <key> — 根据键获取组件的元数据。

dev-resources — 在 Figma Dev Mode 中与开发资源交互。

• figma-pp-cli dev-resources post — 在多个文件中批量创建开发资源。
• figma-pp-cli dev-resources put — 在多个文件中批量更新开发资源。

developer-logs — 获取组织中 REST API 和 MCP 服务请求的开发者日志。

• figma-pp-cli developer-logs — 返回组织内发出的 REST API 和 MCP 服务请求的开发者日志条目列表。

figma-analytics — 管理 Figma 分析

• figma-pp-cli figma-analytics get-library-component-actions — 按请求的维度拆分，返回库分析中的组件操作数据列表。
• figma-pp-cli figma-analytics get-library-component-usages — 按请求的维度拆分，返回库分析中的组件使用数据列表。
• figma-pp-cli figma-analytics get-library-style-actions — 按请求的维度拆分，返回库分析中的样式操作数据列表。
• figma-pp-cli figma-analytics get-library-style-usages — 按请求的维度拆分，返回库分析中的样式使用数据列表。
• figma-pp-cli figma-analytics get-library-variable-actions — 按请求的维度拆分，返回库分析中的变量操作数据列表。
• figma-pp-cli figma-analytics get-library-variable-usages — 按请求的维度拆分，返回库分析中的变量使用数据列表。

files — 获取文件 JSON、图片及其他文件相关内容。

• figma-pp-cli files <file_key> — 将由 file_key 标识的文档作为 JSON 对象返回。

images — 管理图片

• figma-pp-cli images <file_key> — 渲染文件中的图片。

me — 管理个人信息

• figma-pp-cli me — 返回当前已通过身份验证的用户信息。

oembed — 获取 Figma 文件和已发布 Make 的 oEmbed 数据。

• figma-pp-cli oembed — 按照 [oEmbed 规范](https://oembed. 获取 Figma 文件或已发布 Make 站点 URL 的 oEmbed 数据。

payments — 获取 Community 资源的购买信息。

• figma-pp-cli payments — 有两种方法可查询用户在插件、小组件或 Community 文件上的付款信息。

projects — 获取团队中的项目和文件信息。

styles — 获取已发布样式的信息。

• figma-pp-cli styles <key> — 根据键获取样式的元数据。

teams — 管理团队

webhooks — 以团队管理员身份与团队 Webhook 交互。

• figma-pp-cli webhooks delete — 删除指定的 Webhook。此操作无法撤销。
• figma-pp-cli webhooks get — 如果存在，则返回与所提供上下文或计划对应的 Webhook 列表。
• figma-pp-cli webhooks get-webhookid — 根据 ID 获取 Webhook。
• figma-pp-cli webhooks post — 创建新的 Webhook，在事件触发时调用指定端点。
• figma-pp-cli webhooks put — 根据 ID 更新 Webhook。

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接询问 CLI：

figma-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信的匹配项，此时可回退到 --help 或使用范围更窄的查询。

示例

为 AI 代码生成提示词提取帧

figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json --select 'simplifiedNodeCount,nodes,variables,devResources'

杀手级命令。返回精简的 JSON，包含简化后的节点树、所有作用域内的变量、所有开发资源链接，以及显示压缩比的节点数量——直接粘贴到 Claude 或 Cursor 即可。

查找超过两周仍未解决的评论

figma-pp-cli comments-audit --older-than 14d --group-by file,author --json --select 'file,author,count,oldest_at'

同步后，遍历评论表并按文件和作者汇总。通过 jq 处理，即可生成可直接发到 Slack 的 Markdown。

清理团队库中的孤立项

figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json

将团队库发布列表与 30 天使用情况分析进行关联；输出已发布但使用次数为零的实体列表——这些就是待弃用对象。需要 Enterprise 层级。

比较两个文件版本之间的设计令牌

figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md

解析版本 ID，分别获取各版本的变量快照，并输出 Markdown 变更集，列出新增、移除、重命名或值已更改的令牌。在合并设计令牌 PR 前运行。

将失败的 Webhook 投递重放到本地服务

figma-pp-cli webhooks test wh_abc --replay-failed --target-url http://localhost:3000/figma

通过 /v2/webhooks/{id}/requests 获取请求日志，筛选状态码 >= 400 的请求，并将每次投递连同捕获的载荷和原始标头重放到你的本地 URL。（目前尚未接入 HMAC 重新签名——用于测试时，你的处理程序必须接受未签名的重放请求。）

身份验证设置

Figma 支持两种身份验证模式：用于个人或自动化用途的个人访问令牌（标头 X-Figma-Token，前缀 figd_），以及适用于 /v1/me、/v1/activity_logs 和 /v1/developer_logs 的 OAuth 2.0（Authorization: Bearer）。设置 FIGMA_API_TOKEN（PAT）或 FIGMA_OAUTH2（OAuth Bearer）；CLI 会自动选择正确的标头。运行 figma-pp-cli auth login 进行 OAuth 身份验证，或通过 figma-pp-cli auth set-token 将 PAT 保存到配置文件。Doctor 会显示响应标头中的 X-Figma-Plan-Tier 和 X-Figma-Rate-Limit-Type。

运行 figma-pp-cli doctor 验证设置。

Agent 模式

对任意命令添加 --agent。该选项会展开为：--json --compact --no-input --no-color --yes。

• 可管道处理 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐项遍历。对于响应冗长的 API，这对于控制上下文大小至关重要：

  figma-pp-cli activity-logs --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 支持离线使用 — 有本地 SQLite 存储时，同步和搜索命令可以使用它

• 非交互式 — 从不显示提示，每项输入都通过标志提供

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

从本地存储或 API 读取数据的命令会将输出封装在一个来源信息对象中：

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

通过 .results 解析数据，并通过 .meta.source 确认数据来自实时接口还是本地存储。只有当 stdout 连接到终端，且未设置任何机器可读格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于人类阅读的 N results (live) 摘要输出到 stderr——管道或 Agent 消费者以及显式指定格式的运行都会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

figma-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
figma-pp-cli feedback --stdin < notes.txt
figma-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.local/share/figma-pp-cli/feedback.jsonl。除非设置了 FIGMA_FEEDBACK_ENDPOINT，且传入了 --send 或 FIGMA_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅在本地保存。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这才是能够不断累积价值的部分。

输出传递

每个命令都接受 --deliver <sink>。输出会发送到指定的接收端，同时也会输出到 stdout（或替代 stdout），因此 Agent 无需手动管道传递即可路由命令结果。支持三种接收端：

接收端	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（--compact 时为 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝请求，并返回包含受支持方案列表的结构化错误。Webhook 请求失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用间重复使用。如果定时 Agent 每次运行都以相同配置调用同一命令，就可以使用它——这是 HeyGen 的“Beacon”模式。

figma-pp-cli profile save briefing --json
figma-pp-cli --profile briefing activity-logs
figma-pp-cli profile list --json
figma-pp-cli profile show briefing
figma-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，供 Agent 在运行时发现。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 figma-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add figma-pp-mcp -- figma-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which figma-pp-cli 如果未找到，提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   figma-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，查看子命令帮助：figma-pp-cli <command> --help。