Composio 集成 Figma 实战指南：认证配置、工具发现与设计 Token 工作流

Figma 是设计师与开发者协作的核心工具，而通过 Composio 的 Figma toolkit，AI Agent 可以直接读取设计文件、提取设计 Token、渲染节点、管理评论与 Webhook。本文基于 Composio 官方知识库文档 docs/kb/articles/toolkits-figma.md，完整讲解 Figma 在生产环境下的认证配置、429 限流处理、废弃 scope 清理、跨认证模式工具发现，以及设计 Token 与组件提取的最佳实践。读完本文，你将能正确配置 Figma 连接、排查常见认证与限流问题，并掌握 FIGMA_EXTRACT_DESIGN_TOKENS 等核心工具的正确用法。

一、配置 Figma 生产环境认证

让 Composio 处理 Bearer 授权

对于 Figma 集成，Composio 的设计原则是：授权头（Bearer authorization）由 Composio 内部处理，客户无需手工创建独立的 Bearer-token 认证方案。

在常规 Figma 工具使用场景下，你只需在 toolkit 的认证模式（auth mode）中提供受支持的凭据或 Token，Composio 会自动在每次 API 调用中注入 Bearer 授权头。这意味着：

• 无需在自定义认证配置中额外定义 Bearer-token scheme；
• 连接建立后，所有 Figma 工具共享同一份凭据管理；
• 凭据轮换、刷新由连接生命周期统一管理。

这一点同样记录在 docs/kb/source/toolkits/figma/public.md 与知识库渲染版 docs/content/kb/guide/toolkits-figma.mdx 中。

两种受支持的认证模式

从仓库的 toolkit 元数据（docs/public/data/toolkits.json 中 slug: "figma" 条目）可以看到，Figma toolkit 声明了两种认证方案：

认证模式	配置名称	说明
OAUTH2	figma_oauth2	默认由 Composio 托管的 OAuth 应用；也支持使用客户自己的 OAuth 应用（需提供 client_id、client_secret）
API_KEY	figma_api_key	个人访问令牌（以 figd_ 开头），在 Figma 的 Settings → Security 中创建

composioManagedAuthSchemes 字段显示 OAUTH2 是 Composio 托管模式，而 API_KEY 需要客户自行提供凭据。

OAuth2 模式字段（创建认证配置时需要）：

• client_id（必填）：OAuth 应用的客户端 ID；
• client_secret（必填）：OAuth 应用的客户端密钥；
• full（必填，默认 https://api.figma.com）：Figma API 基础地址，仅在通过代理路由 Figma 流量时需要修改；
• oauth_redirect_uri（可选，默认 https://backend.composio.dev/api/v1/auth-apps/add）：需要加入 OAuth 应用的重定向白名单；
• scopes（可选）：以逗号分隔的权限列表，默认值为 file_comments:write,webhooks:write,current_user:read,file_content:read,file_comments:read,projects:read,library_assets:read,library_content:read,team_library_content:read,file_metadata:read,file_versions:read,webhooks:read。

API_KEY 模式字段：

• full（必填，默认 https://api.figma.com）：API 基础地址；
• generic_api_key（必填）：Figma 个人访问令牌，创建时需按需勾选 scope，且只在创建瞬间显示一次，务必立即保存。

认证配置的增删改查由 Python SDK 的 AuthConfigs 客户端封装，相关行为可参考 python/tests/test_auth_configs.py（覆盖 list、create、retrieve、update、delete、update_status 等接口）。

二、生产环境下的 429 限流处理

判断 429 的来源

当 Figma 返回 429 状态码时，说明请求被 Figma 侧限流。官方知识库的建议是：

1. 先确认响应确实来自 Figma（而非 Composio 或中间代理层）；
2. 查阅 Figma 官方的限流文档，确认具体的限流窗口与配额；
3. 降低请求频率、加入退避（backoff）逻辑，在提供方限流重置后再重试。

FAQ 文档 docs/content/toolkits/faq/figma.md 补充说明：429 意味着 Figma 对该请求做了 rate limit，应确认响应来源、减少请求量、添加 backoff，并在提供方限额重置后重试。

生产环境应使用客户自有凭据

Composio 的默认 Figma 应用适用于快速测试，但生产流量建议使用客户自己的 Figma 凭据，理由包括：

• 避免共享应用的压力（shared-app pressure）：多个客户共用默认应用时，任何一方的突发流量都可能影响整体配额；
• 自主控制 scope 范围：按业务需要申请最小权限；
• 自主控制流量模式与限流暴露面：使用独立凭据后，限流配额与你的真实流量一一对应，便于容量规划。

三、清理废弃 scope：file_read

如果 Figma 认证配置中包含了已废弃的 file_read scope，需要：

1. 从认证配置中移除该 scope；
2. 重新发起一次新的连接（initiate a new connection），使新 scope 生效。

废弃 scope 的残留可能影响工具调用或导致权限校验异常，因此在变更 scope 后务必重建连接，而不是复用旧连接。这一点在源文档 docs/kb/source/toolkits/figma/public.md 中同样有明确记录。

四、跨认证模式发现并运行 Figma 工具

Figma 工具应当与连接方式无关地正常工作，无论连接使用的是：

• Composio 托管的 OAuth（managed OAuth）；
• 自定义 OAuth 应用（custom OAuth app）；
• Token / API-Key 认证。

如果找不到某个工具，官方建议的排查路径是：

1. 动态拉取可用工具列表（fetch available tools dynamically），确认工具是否存在于当前 toolkit 版本中；
2. 检查该工具所要求的认证 scope，确认当前连接的凭据是否覆盖这些 scope。

从 docs/public/data/toolkits.json 的 Figma 条目看，当前版本（20260721_00）共包含 53 个工具，覆盖注释、Webhook、变量、组件、样式、库分析（library analytics）、图片渲染等能力；工具缺失时，也可通过 Composio 的工具请求入口提交需求。

五、设计 Token 与组件工作流

核心工具组合

针对 Figma 设计 Token 与组件工作流，官方推荐使用以下三个工具：

工具	作用	关键参数
FIGMA_EXTRACT_DESIGN_TOKENS	提取设计 Token（样式 + 变量 + 节点值）	file_key、include_variables
FIGMA_DESIGN_TOKENS_TO_TAILWIND	将设计 Token 转换为 Tailwind CSS 配置	tokens（前一步提取的 DesignTokens 对象）
FIGMA_GET_FILE_NODES	按节点 ID 获取文件 JSON，避免整文件载荷过大	file_key、ids、depth

FIGMA_EXTRACT_DESIGN_TOKENS 的取值逻辑：只捕获编码为 Figma 样式（styles）或变量（variables）的值，未编码为样式/变量的设计值会被静默忽略；完整的输出依赖 file_variables:read scope 以及支持变量的 Figma 套餐。若变量提取为空，可补充调用 FIGMA_GET_LOCAL_VARIABLES。

FIGMA_DESIGN_TOKENS_TO_TAILWIND 是两步工作流：

1. 先用 FIGMA_EXTRACT_DESIGN_TOKENS 配合 file_key 提取设计 Token；
2. 再将返回的 DesignTokens 对象传给本工具的 tokens 参数。

它会生成 tailwind.config.ts/js（含主题扩展），并可选择生成带字体导入的 globals.css。阴影颜色支持两种格式：字符串形式（如 "rgba(15, 110, 110, 0.32)"）或字典形式（如 {"r": 0.059, "g": 0.431, "b": 0.431, "a": 0.32}）。

FIGMA_GET_FILE_NODES 用于在已知目标节点 ID 时按需获取节点 JSON，规避整文件 JSON 的载荷上限；快速发现阶段建议使用 depth=1。

废弃工具：FIGMA_GET_COMPONENT

旧的 FIGMA_GET_COMPONENT 动作已标记为 deprecated，应改用 FIGMA_GET_FILE_NODES 获取组件数据。工具清单中标注为 "Get component (Deprecated)"，说明文字明确写道："DEPRECATED: Use FIGMA_GET_FILE_NODES instead."。此外，获取已发布组件元数据时还可使用 FIGMA_GET_COMPONENT2 与 FIGMA_GET_COMPONENT_SET。

include_variables 的套餐限制与 FAQ 细节

FIGMA_EXTRACT_DESIGN_TOKENS 在启用 include_variables 时可能失败，原因是：

• 该工具会调用 Figma 的 local variables 端点，要求连接账户具备 file_variables:read scope；
• 若 Figma 返回 403 并提示端点需要 file_variables:read，则需要用能够授予该 scope 的 Figma 凭据重新连接；
• Figma 仅对 Enterprise 组织成员开放 file_variables:read scope（见 docs/content/toolkits/faq/figma.md）。

两个务实的处理路径：

1. 确认套餐/API 访问权限：检查当前 Figma 套餐是否支持变量相关 API；
2. 降级绕过：如果不需要 Figma 变量，将 include_variables 设为 false。此时工具仍可从本地样式（local styles）与节点中提取 Token，只是不再调用 variables 端点。

相关工具横向参考

围绕设计资源，同一 toolkit 中还提供了一系列与 Token/组件工作流配套的工具，便于构建完整的"设计 → 代码"流水线：

• 资源发现：FIGMA_DISCOVER_FIGMA_RESOURCES 可从任意 Figma URL（/file/、/design/、/board/、/proto/、/slides/）解析出 file_key，并支持 team → projects → files → nodes 的发现流程；
• 文件读取：FIGMA_GET_FILE_JSON（自动简化，CSS 风格属性名、去重变量、体积缩减 70%+）、FIGMA_GET_FILE_METADATA、FIGMA_GET_FILE_STYLES；
• 变量与样式：FIGMA_GET_LOCAL_VARIABLES、FIGMA_GET_PUBLISHED_VARIABLES（仅 Enterprise 组织正式成员可用）、FIGMA_CREATE_MODIFY_DELETE_VARIABLES、FIGMA_GET_STYLE；
• 渲染与下载：FIGMA_RENDER_IMAGES_OF_FILE_NODES（PNG/JPG/SVG/PDF，节点图 URL 有效期 30 天，单图上限 32 兆像素）、FIGMA_DOWNLOAD_FIGMA_IMAGES；
• 组件库：FIGMA_GET_FILE_COMPONENTS、FIGMA_GET_COMPONENT_SET、FIGMA_GET_TEAM_COMPONENTS、FIGMA_GET_TEAM_STYLES。

六、排查清单速查

症状	排查方向
工具调用报 403，提示需要 file_variables:read	确认 Figma 套餐（该 scope 仅 Enterprise 成员可用），或设置 include_variables=false 绕过
返回 429	确认响应来自 Figma，降低请求量、加退避重试；生产环境切换为客户自有凭据
找不到某个 Figma 工具	动态拉取工具列表，检查工具所需 scope 是否在连接凭据中，或通过工具请求入口提交
认证配置含废弃 file_read scope	移除 scope 后重新发起新连接
FIGMA_GET_COMPONENT 不可用	该工具已废弃，改用 FIGMA_GET_FILE_NODES

总结

Composio 的 Figma toolkit 将认证、限流与工具发现封装成了可复用的能力：Composio 内部处理 Bearer 授权，客户只需在认证模式中提供凭据；生产环境建议使用自有 Figma 凭据以独立控制 scope 与限流配额；设计 Token 工作流以 FIGMA_EXTRACT_DESIGN_TOKENS → FIGMA_DESIGN_TOKENS_TO_TAILWIND 为主线，用 FIGMA_GET_FILE_NODES 按需取节点数据，并注意 include_variables 依赖 Enterprise 级 file_variables:read scope。掌握了这些要点，你就能在 Agent 应用中稳定、安全地打通"Figma 设计 → 代码 Token"的自动化链路。