figma-context-parser

将 Figma REST API 导出的 figma-full.json 转换为适合 AI/LLM 检索和还原页面的紧凑 Design Context。

解析器面向超大 JSON、递归节点、流式处理和多文件输出设计。核心解析只需要一份已经导出的 Figma JSON；图片、矢量路径和 Figma 合成图属于可选的在线增强能力。

主要能力

• 支持 Node.js 20+，核心 fcp 命令可用于 macOS、Windows 和 Linux。
• 流式解析超过 100MB 的 Figma JSON，不把整个文件一次性载入内存。
• 将 Page、Section、Screen、Component 和 ComponentSet 拆成可独立检索的文件。
• 保留层级、组件引用、Instance 属性、Variant、约束、布局、样式和混合文本。
• 生成 search.json、分类目录和 O(1) 节点 ID 索引。
• 自动生成 Screen Plan、复杂度分析和不可遗漏清单。
• 支持 geometry=paths 矢量 SVG、图片填充和 Figma 合成渲染兜底。
• 生成给 AI 阅读的 AGENTS.md 和独立完整命令手册 FCP.md。
• 使用缓存、文件指纹、锁、临时目录和事务性提交，构建失败不会覆盖旧的有效产物。

安装

要求 Node.js 20 或更高版本。

发布到 npm 后可全局安装：

npm install -g figma-context-parser

在源码目录测试未发布版本时，使用打包副本安装，避免全局命令链接到正在编辑的源码：

cd figma-context-parser
npm install
npm pack --ignore-scripts
# 将下行的文件名替换为 npm pack 输出的 filename
npm install -g ./<npm-pack 输出的 filename>

验证命令：

fcp --help

快速开始

1. 初始化 Design Context 目录

fcp init ./design-context \
  --url https://api.figma.com/v1/files/FILE_KEY

init 不访问网络，会生成：

design-context/
├── config.json
├── AGENTS.md
├── FCP.md
├── README.md
├── actions.json
└── .gitignore

• config.json：Figma 地址和运行配置，macOS/Linux 下自动设置为 600 权限。
• AGENTS.md：AI 必读的安全、低 Token 和复杂页面还原规则。
• FCP.md：给 AI 使用的完整 FCP 命令、权限和故障恢复手册。
• actions.json：不含凭证的声明式安全命令入口。

除非明确要重置已有配置，否则不要使用 fcp init --force。

2. 设置 Token

FCP 支持把 Token 直接写在 config.json，也支持从环境变量读取。两个字段可以同时保留：

{
  "figma": {
    "url": "https://api.figma.com/v1/files/FILE_KEY",
    "token": "",
    "tokenEnv": "FIGMA_TOKEN"
  }
}

解析优先级为 token > tokenEnv：

• token 非空时，直接使用 JSON 中的 Token。
• token 为空时，才从 tokenEnv 指定的环境变量读取。
• xxx、YOUR_TOKEN 等占位符不是有效 Token，必须替换或留空。

直接写入 JSON 的示例：

{
  "figma": {
    "url": "https://api.figma.com/v1/files/FILE_KEY",
    "token": "figd_your_real_token",
    "tokenEnv": "FIGMA_TOKEN"
  }
}

如果 token 已填写，无需再设置环境变量。如果要使用环境变量，将 token 保持为空字符串。

macOS/Linux：

export FIGMA_TOKEN="your-token"

Windows PowerShell：

$env:FIGMA_TOKEN = "your-token"

Windows CMD：

set FIGMA_TOKEN=your-token

无论使用哪种方式，FCP 都不会把 Token 写入日志或生成的 Design Context。config.json 默认加入 .gitignore，AI 也被禁止读取它。

3. 首次生成

fcp run ./design-context

第一次运行且 .source 不存在时，FCP 会下载 Figma 文件并生成完整上下文。默认请求 geometry=paths，然后生成 Screen Plan、下载图片填充、按需获取复杂节点合成图并执行完整性校验。

4. 日常使用

fcp run ./design-context

FCP 优先使用 .source/figma-full.geometry.json，其次使用 .source/figma-full.json。当本地源文件指纹与现有有效产物一致时，会返回：

mode: cached
networkRequested: false

此时不会重新下载、解析或生成页面，也不会重新下载图片和合成图。

如果必须保证完全不联网：

fcp run ./design-context --offline

从本地缓存强制重建：

fcp run ./design-context --offline --rebuild

5. Figma UI 更新后

只有用户明确说明 Figma UI、页面或文件已经更新时，才执行：

fcp run ./design-context --refresh

不得为了“确认是不是最新”主动刷新线上 Figma。

运行进度

fcp run 默认将带耗时的阶段进度写入 stderr：

[fcp 0.0s] start: Checking the project, configuration, and local cache...
[fcp 0.1s] fingerprint: Fingerprinting the local source without loading it into memory...
[fcp 0.3s] cache-hit: Cache is valid; skipping download, parsing, and asset enrichment.
[fcp 0.3s] complete: Done (cached, no network requested).

最终机器可读 JSON 单独写入 stdout，不会被进度信息污染。需要逐页和资源级日志时使用：

fcp run ./design-context --verbose

FCP 命令

fcp init <directory>

初始化项目目录，不访问网络。

• --url <figma-url>：设置原始 Figma REST File API 地址。
• --force：覆盖已有模板和配置，属于高风险操作。

fcp run <directory>

生成最大还原度的 Design Context，并优先复用本地缓存。

• --refresh：下载最新 Figma 文件后重建，只能在用户确认 UI 更新后使用。
• --offline：禁止任何网络请求，要求本地已有 .source。
• --rebuild：忽略有效产物缓存，从本地源重新解析。
• -v, --verbose：显示逐页和资源级详细进度。

--refresh 和 --offline 不能同时使用。

fcp sync <directory>

显式下载并解析最新 Figma 文件，但不执行图片和合成图增强。该命令总是联网。

fcp sync ./design-context --geometry paths
fcp sync ./design-context --geometry none

通常优先使用 fcp run . --refresh，因为它会执行完整增强和校验。

fcp images <directory>

下载 Figma image fill 并保存到 assets/images/，在节点旁写入稳定的本地 imagePath。临时签名 URL 不会保存到 Design Context。

fcp images ./design-context

该命令需要网络和用户授权。

fcp vectors <directory>

将已检测到的复合矢量根节点按 Figma 父节点导出为完整 SVG。例如由眼廓和眼球构成的图标会得到一个可直接复用的 SVG，而不是由 AI 重新绘制或拼接本地 path。

# 仅查看高置信度候选，不联网
fcp vectors ./design-context --dry-run

# 用户授权后下载完整 SVG
fcp vectors ./design-context --auto

产物位于 assets/compound-vectors/；节点的 compoundVector.assetRef 是默认引用路径。该命令需要网络和用户授权。

fcp renders <directory>

下载 Figma 合成好的节点图片，用作旋转、Mask、透明度、混合模式、滤镜、多重填充和 Blur 等复杂效果的视觉兜底。

# 只预览候选节点，不请求渲染接口
fcp renders ./design-context --auto --dry-run

# 自动渲染复杂节点
fcp renders ./design-context --auto

# 渲染指定节点
fcp renders ./design-context --ids "123:456,123:789"

# 渲染全部 Screen
fcp renders ./design-context --screens

可用参数：

• --scale <0.01-4>：渲染倍率，默认 2。
• --format png|jpg：输出格式，默认 png。
• --dry-run：仅列出候选节点。
• -v, --verbose：显示详细进度。

--auto、--ids 和 --screens 不能同时使用。

fcp plans <directory>

只使用现有 JSON Screen 重建 Screen Plan，不读取 config.json、不读取 .source、不访问网络，也不修改图片、矢量和合成图。

fcp plans ./design-context

fcp context <directory>

实现一个页面时的首选入口。它将本地 Screen、Screen Plan、资产和语义规则压缩为一份有上限的任务包，不读取 .source、config.json，也不联网：

fcp context ./design-context --screen-id "1:123"

AI 应先读取该输出，再按需使用 inspect 深挖局部节点；不要先展开整份 Screen JSON。

默认输出会为每个 Screen Plan Region 提供文字标签预览、语义信号和不可遗漏项计数，因此长页面的下半部分也会被纳入首轮上下文。实现复杂页面时，按返回的 Region ID 逐区块展开：

fcp context ./design-context --screen-id "1:123" --region "region-03"

Region 输出只展开该区块的文字、资产、组件和视觉规则；若 checklist.*.truncated 为 true，执行返回的 nextPage（或同一命令加 --offset）继续分页，直到该类清单完成。不要读取完整 Screen JSON 或 completeArtifact。可用 --max-items 8-80 调整每类清单的上限。

fcp validate <directory>

离线检查 metadata、导航索引、搜索索引、Screen Plan、资源文件、临时文件和配置权限。

fcp validate ./design-context

验证失败时返回非 0 退出码。

fcp status <directory>

离线查看当前产物统计、完整性和上次运行报告。

fcp status ./design-context

fcp clean <directory>

默认只删除残留的 .fcp-* 锁和临时状态，保留 .source。

fcp clean ./design-context

离线 Inspect 查询

fcp inspect 只读取已生成的 Design Context 与本地 SVG 元数据，不读取 .source、不读取 config.json、不访问 Figma。它的输出有数量和深度上限，适合 AI 按需获取少量事实。

# 先查看当前版本的能力和上限
fcp inspect tools ./design-context

# 复杂页面的实现简报、Region 和工具提示
fcp inspect screen ./design-context --screen-id "1:100"

# 单节点、批量节点、上下内外关系
fcp inspect node ./design-context --id "1:123"
fcp inspect nodes ./design-context --ids "1:123,1:124"
fcp inspect ancestors ./design-context --id "1:123" --depth 4
fcp inspect relatives ./design-context --id "1:123"
fcp inspect descendants ./design-context --id "1:123" --depth 2 --max-nodes 40

# 布局、测量、重叠和 SVG 边界
fcp inspect layout ./design-context --id "1:123"
fcp inspect measure ./design-context --ids "1:10,1:11,1:12"
fcp inspect overlap ./design-context --id "1:123"
fcp inspect svg ./design-context --id "1:456"

批量节点还支持重复 --id，以及 --ids-file ./node-ids.json。该文件可以是 JSON 字符串数组，也可以是每行一个 ID 或逗号分隔的文本。

inspect layout 返回 Gap、对齐、行列聚类、重叠和 Flex/Grid/Hybrid 候选。候选只是几何证据，不是必须照抄的 CSS；AI 仍应结合页面语义和响应式需求决策。

页面布局验收

完成一个页面前，执行本地静态审计：

fcp audit-layout ./pages/index/index.vue --screen-id "1:123"

它不读取 .source、config.json，也不联网。页面直接子节点 Absolute、将多个 Region 翻译为坐标切片、页面固定设计稿高度都会作为 error 阻止完成；固定容器尺寸等会作为 warning 要求复核。

Screen Plan 的 Region 是读取和验收单位，不是 DOM/CSS 层。页面应先由普通文档流的 Section 组成，再只在局部视觉叠层中使用 Absolute。局部确有必要时，可在对应 CSS 规则写 /* fcp-allow: 不少于八个字的具体理由 */；不能用它豁免整页或 Region。

如果目标 Screen 已生成 Figma 合成图兜底，还必须检查代码是否实际引用：

fcp audit-renders ./design-context ./pages/index/index.vue --screen-id "1:123"

renderFallback.path 默认应直接使用，尤其是图片滤镜、Blur、混合模式、复杂矩阵、多 Fill、复杂 Mask。只有结构化实现完整覆盖该节点全部 reasons 时，才可添加精确的跳过说明：

/* fcp-render-skip: assets/renders/[email protected] | 已完整覆盖滤镜、矩阵和混合效果 */

只有用户明确要求删除本地源缓存时才能执行：

fcp clean ./design-context --source

删除 .source 后，下次生成可能需要重新请求 Figma。

生成目录

完整运行后主要结构如下：

design-context/
├── metadata.json
├── index.json
├── search.json
├── actions.json
├── run-report.json
├── AGENTS.md
├── FCP.md
├── pages/
├── sections/
├── screens/
├── screenPlans/
├── components/
├── componentSets/
├── tokens/
├── assets/
│   ├── index.json
│   ├── images/
│   ├── vectors/
│   └── renders/
└── .source/

.source 只供解析器使用。AI 不得打开、搜索、输出或摘要其中的原始 JSON。

命令返回类型

每个 fcp 命令的 JSON 输出都包含稳定的顶层 schema，例如 fcp-inspect-layout/v1、fcp-audit-layout/v1。完整字段契约见安装包根目录的 FCP.types.d.ts，以及每个生成目录中的同名文件。AI 应先按 schema 判断返回类型，不应猜测可选字段。

输出模型

分层和引用

pages、sections、screens、screenPlans、components 和 componentSets 中的对象可以独立检索。被拆出的子对象在父节点中只保留紧凑引用：

{ "id": "1:2", "name": "Button", "type": "COMPONENT", "ref": "components/Button--1_2.json", "children": [] }

Instance 保留 componentId、componentSetId、属性和 Variant，但不会复制 Component 主体。导出文件缺少组件 Master 时，解析器会把第一个展开的 Instance 保存为唯一的 external: true, surrogate: true 替代组件。

Screen Plan 和不可遗漏清单

每个 Screen 都会由本地的 ComplexityAnalyzer、ScreenPlanBuilder 和 RequirementBuilder 生成确定性的 Screen Plan，不调用模型，也不产生额外 Figma 请求。

顶层 Plan 保存复杂度、区域顺序、边界、预期数量和完成规则；每个 Region 有独立 JSON 清单。清单覆盖文本、图片、矢量、组件实例、Mask、裁剪、旋转、矩阵、透明度、混合模式、滤镜、特效、混合文本和合成图兜底。

Figma Node ID 只用于源定位，不要求业务代码加入 data-figma-id，也不需要人工维护节点到代码文件的映射。

布局、变换和文本

• 普通自由布局子节点的源坐标保存在 sourceBounds，并标记 referenceOnly: true；它用于测量和视觉核对，不是 Absolute 指令。只有 Figma 明确为 Absolute 的节点才在 layout.x/y 保留局部锚定坐标。
• Auto Layout 保留方向、Gap、Padding、对齐、Hug、Fill 和 Fixed 尺寸语义。
• 普通实现默认使用 Flex/Grid + Gap/Padding/Margin；数字 width/height 是视觉测量值，不能自动等同于固定 CSS 尺寸。sizeIntent 仅在 Figma 明确提供 Hug/Fill/Fixed 时出现。
• Region 仅用于读取和验收，禁止逐个转换为带 top/left 的 Absolute DOM 切片；页面根高度由内容决定，不能照抄 Figma 画布高度。
• Absolute 和固定尺寸不需要用户授权，但必须能说明 Flex/Grid、响应式尺寸、Gap/Padding/Margin、minmax()、max-width、aspect-ratio 或 Transform 无法合理表达该效果。
• Frame 裁剪保存为 clip。
• Mask 保存 mask.type 和 mask.appliesTo。
• 旋转和矩阵保存为 transform.rotation 与 CSS 顺序的 transform.matrix。
• 混合文本使用紧凑的 text.runs，只保存与基础样式不同的范围。
• 列表类型和缩进保存在 text.paragraphs。

图片

图片 Paint 与节点级样式分开保存自己的 opacity、blend、rotation、imageTransform、scalingFactor 和非零 filters，避免错误地把图片透明度或混合模式应用到边框、文本、子节点和特效。

存在 renderFallback.path 的节点默认直接引用对应合成图；只有能完整覆盖其全部复杂效果原因时才能按节点写明 fcp-render-skip。

下载后的图片保存为稳定本地文件；临时签名 URL 和 Token 永远不会写入输出。

矢量

使用 geometry=paths 下载源文件后，Fill 和 Stroke 几何会转换为独立的 assets/vectors/*.svg。节点只保留紧凑 vectorRef，路径数据不会进入面向 LLM 的 JSON。

支持纯色、渐变、Fill Override、Winding Rule 和 Stroke Outline。

AIContextBuilder

每个产物包含面向 AI 的摘要：

{
  "title": "Login Screen",
  "kind": "frame",
  "contains": ["Header", "Phone Input", "SMS Button", "Agreement", "Login Button"],
  "summary": "Login Screen contains Header, Phone Input, SMS Button, Agreement, Login Button."
}

AI 可以先理解页面包含什么，再按需读取具体 Region 或节点，而不必直接打开完整节点树。

索引

• index.json 只存导航，目标保持小于 100KB；过大时页面目录会自动拆出。
• search.json 包含名称直接索引和 __ids 节点 ID 索引。
• assets/index.json 保存图片、矢量、合成图及其引用关系。
• tokens/index.json 保存导出文件中可用的样式。

AI 安全读取规则

AI 进入 Design Context 后必须先读取 AGENTS.md。需要执行或排查 FCP 命令时再读取 FCP.md。

AI 不得：

• 直接读取 figma-full.json 或 .source/ 中的任何文件。
• 读取、打印、复制或提交 config.json。
• 为确认线上是否更新而主动调用 Figma。
• 绕过 actions.json 猜测或搜索解析器路径。
• 未经用户明确授权执行 --refresh、sync、images 或实际 renders。

超大文件与内存

内置 JSON Reader 以流式方式解码输入，每次只物化一个 Figma Page，完成标准化、拆分和写入后再读取下一页。内存峰值主要取决于最大单页，而不是整个导出文件大小。

所有产物使用临时文件原子写入。完整 fcp run 在同级临时目录构建并验证，成功后才事务性替换旧产物；失败时旧的有效 Design Context 保持不变。

解析完成后会对已经拆分的小文件进行一次轻量补充扫描，为 Instance 填充 componentSetId，仍不会把整个输入或输出一次性载入内存。

跨平台说明

新的 fcp 核心 CLI 使用 Node.js 文件、路径和网络 API，不依赖 Bash、curl 或数据库。

• macOS/Linux：可直接使用 fcp。
• Windows：npm 会生成 fcp.cmd，建议通过 PowerShell 或 CMD 使用。
• tools/*.sh 是旧版 macOS/Linux 兼容脚本，不是 Windows 命令；新项目不需要使用它们。
• Windows 的文件安全由 ACL 管理，chmod 600 的显示和语义与 macOS/Linux 不完全相同。

当前自动化测试在禁网模式下运行，真实 Windows 支持仍建议通过 Windows CI 继续验收。

旧版直接 CLI

需要只解析一个已经存在的本地 JSON 时，可以使用旧入口：

node cli.js \
  --input ../figma-full.json \
  --output ../design-context \
  --minify \
  --markdown \
  --verbose

常用参数：

• --pretty：格式化 JSON，默认开启。
• --minify：压缩 JSON。
• --markdown：为每个产物生成 AI 友好的 Markdown。
• --json：生成 JSON，默认开启。
• --no-json --markdown：只生成 Markdown。
• --verbose：输出逐页进度和统计。

旧入口仍可通过 --config、--download-images、--render-auto 等参数使用，但推荐的新项目统一使用全局 fcp 子命令。

编程接口

import { parseFigmaExport } from "./src/parser.js";

const metadata = await parseFigmaExport({
  input: "figma-full.json",
  output: "design-context",
  pretty: false,
  json: true,
  markdown: false,
  verbose: true,
});

测试与打包检查

npm test
npm run pack:check

自动化测试默认阻止真实网络请求，线上 Figma API 流程不会在测试中执行。