Figma设计助手(免费版)

本工具帮助用户通过Figma REST API与设计文件交互，实现结构读取、图层导出与评论查看等核心功能。免费版聚焦个人使用场景，提供完整的查阅与单次导出能力。

概述

Figma已成为现代设计协作的事实标准，但在Agent工作流中直接读取设计文件往往需要复杂的API封装。本工具将常用操作封装为简洁命令，让Agent能够按需读取设计结构、导出指定图层、追踪协作评论，从而支撑设计审查、素材提取、标注获取等典型任务。

免费版定位于个人用户的日常查阅需求，不限制使用次数，仅在批量处理与高级缓存方面做出能力边界，以保障服务稳定性。

核心能力

能力	说明	免费版可用
文件结构读取	获取页面、画板、图层层级	是
图层导出	导出为PNG/JPG/SVG/PDF	是(单次)
评论查看	列出文件最近评论	是
批量导出	一次性导出多个图层	否
高级缓存	结构缓存与增量更新	否
团队协作	多人评论聚合分析	否
技术实现要点：核心能力基于`input_params`参数与`output_format`配置实现,支持创建/查询/修改/删除等操作模式,通过`config_options`进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Figma、导出图层、查看评论的免费体、适合个人设计稿查、设计助手、是一款面向设计师、与开发协作的、文件交互工具、REST、API、实现文件结构读取、图层导出与评论查、看等核心能力、文件的页面、图层层级结构、按需导出指定图层、查看文件最近评论、支持协作沟通追踪、提供安全可靠的、Token、管理方式等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：开发者获取设计素材

前端开发者收到设计稿链接后，需要快速了解图层结构并导出关键切图。通过文件结构读取命令定位目标图层ID，再用导出命令按指定格式与倍率输出素材，避免在Figma客户端中手动操作。

场景二：产品经理审查设计评论

产品经理希望在Agent工作流中汇总设计稿的近期评论，了解设计师之间的讨论脉络。通过评论查看命令获取评论列表，结合上下文判断设计决策的合理性。

场景三：设计师远程查阅

设计师在移动设备或非主力工作站上希望快速浏览设计文件结构，确认版本一致性。通过结构读取命令获取层级概览，无需启动完整客户端。

不适用场景

以下场景Figma设计助手(免费版)不适合处理：

3D建模和动画制作
照片级写实渲染
手绘原创插画

触发条件

需要设计创作、UI设计、海报制作、品牌视觉时使用。不适用于非本工具能力范围的需求。

快速开始

本工具属于中等复杂度工具，预计120秒内可完成首次调用。

Step 1：配置访问令牌

在Figma个人设置中生成Personal Access Token(PAT)，并通过环境变量配置：

# macOS / Linux
export FIGMA_TOKEN="你的个人访问令牌"
# ...
# Windows PowerShell
$env:FIGMA_TOKEN="你的个人访问令牌"

安全提示：令牌等同于账户访问凭证，请勿提交到代码仓库或分享给他人。建议使用环境变量或密钥管理工具存储。

Step 2：读取文件结构

获取文件的页面、画板与图层信息：

python （请参考skill目录中的脚本文件） get-file <file_key>

其中file_key可从Figma文件URL中提取，格式为https://www.figma.com/file/<file_key>/...。

Step 3：导出目标图层

根据结构中的节点ID导出图片：

python （请参考skill目录中的脚本文件） export <file_key> \
  --ids <id1>,<id2> \
  --format png \
  --scale 2

Step 4：查看文件评论

获取文件最近的协作评论：

python （请参考skill目录中的脚本文件） get-comments <file_key>

示例

环境变量配置

# 推荐方式：环境变量
FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxxxxxxxxxx

导出参数说明

参数	类型	必填	默认值	说明
file_key	string	是	-	Figma文件唯一标识
--ids	string	是	-	节点ID列表，逗号分隔
--format	enum	否	png	png/jpg/svg/pdf
--scale	number	否	1	1/2/3/4倍率
--svg_include_id	bool	否	false	SVG是否包含节点ID

最佳实践

实践一：先读结构再导出

避免盲目导出导致资源浪费。先调用get-file获取完整结构，定位到目标节点的ID后，再执行精确导出。这种方式能显著降低API调用次数与等待时间。

实践二：按需选择导出格式

PNG：适用于位图素材与设计预览
JPG：适用于照片类内容，体积更小
SVG：适用于图标与矢量图形，可无损缩放
PDF：适用于打印或文档嵌入

实践三：合理使用倍率

移动端高清屏建议使用2倍或3倍导出，Web端默认1倍即可。过高的倍率会显著增加文件体积与导出耗时。

实践四：令牌安全管理

定期在Figma设置中轮换令牌
为不同用途创建独立令牌
发现令牌泄露立即撤销并重新生成

常见问题

Q1：提示401未授权怎么办？

A：检查FIGMA_TOKEN环境变量是否正确设置，令牌是否过期或被撤销。可在Figma设置中重新生成令牌。

Q2：导出图片为空白？

A：确认--ids参数指向的是可见图层。部分被隐藏的图层导出后可能为空白，建议先在结构中确认图层可见性。

Q3：file_key从哪里获取？

A：从Figma文件URL中提取。例如https://www.figma.com/file/abc123/Design中，abc123即为file_key。

Q4：导出SVG时文字丢失？

A：SVG导出对字体依赖较强，若查看端缺少对应字体会显示异常。建议对含文字的图层使用PNG导出，或确保字体已 outline。

已知限制

A：免费版不限制使用次数，但批量导出(一次超过10个图层)与高级缓存功能需使用专业版。

当前为免费版本,如需完整功能请升级到付费版获取全部能力

错误处理

错误场景(现象)	可能原因	解决方案
401 Unauthorized	令牌无效或过期	重新生成并配置FIGMA_TOKEN
404 Not Found	file_key错误	核对URL中的file_key
429 Too Many Requests	触发速率限制	降低调用频率，间隔执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
导出超时	图层过大或网络延迟	降低scale倍率或分批导出
结构为空	文件无访问权限	确认令牌有该文件访问权

免费版限制

本免费体验版限制以下高级功能：

批量导出(单次超过10个图层)
高级缓存策略(结构缓存与增量更新)
团队协作分析(多人评论聚合)
自定义导出模板与命名规则
优先技术支持

解锁全部功能请使用专业版：figma-tw-designer-pro

依赖说明

运行环境

Agent平台：支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
操作系统：Windows / macOS / Linux
Python：3.8+(用于运行figma_tool.py脚本)

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供
Python	运行时	必需	python.org官方下载
requests库	Python包	必需	`pip install requests`
Figma REST API	外部API	必需	需Figma账户与个人访问令牌

API Key 配置

Figma Personal Access Token：通过环境变量FIGMA_TOKEN配置
生成路径：Figma → Settings → Security → Personal access tokens
安全要求：禁止在SKILL.md或脚本中硬编码令牌，禁止提交到版本控制

可用性分类

分类：MD+EXEC(纯Markdown指令，部分功能需要exec命令行执行能力)
说明：基于Markdown的AI Skill，通过自然语言指令驱动Agent执行Figma文件交互任务

输出格式

{
  "success": true,
  "data": {
    "result": "Figma设计助手(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "figma tw designer"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

Figma Tw Designer Free

安装到 Tokeny（自动）

SKILL.md