Understand-Anything /understand-figma 设计规格解析：把 Figma 文件变成可交互的设计知识图谱

本文以 Understand-Anything 仓库中已批准的 /understand-figma 基础版设计规格（2026-06-24-understand-figma-foundation-design.md）为主体，完整拆解该规格提出的技术方案：Figma 文件如何通过可插拔的源适配器接入 Figma REST API，如何经确定性解析生成 page → screen → component / componentSet / instance / token 的浅层结构图，再经 LLM 语义增强与合并校验，最终产出 kind: "design" 的知识图谱并在现有 Dashboard 中渲染。读完本文，你能掌握该功能的 schema 扩展机制、四阶段流水线实现、增量策略与安全边界，并可对照仓库中已落地的 core/figma 源码验证每一项设计决策。

1. 背景与目标：Figma 作为首个"设计输入"

Understand Anything 的核心理念是"能教学的图谱，而非只会 impress 人的图谱"（Graphs that teach > graphs that impress）。此前 /understand-knowledge（wiki）与 /understand-domain（业务域）已经把工具从纯代码输入扩展到非代码输入，其模式是固定的：确定性解析搭结构骨架 → LLM Agent 补充语义 → 合并步骤装配同一份 knowledge-graph.json → 同一个 Dashboard 渲染。/understand-figma 是同一模式在设计文件上的第三次复用。

该规格被定位为五个子项目中的第 1 个（Foundation），交付"Figma 接入 + 结构分析 + 轻量设计系统模型"，其余四项作为路线图：

                       ③ C  Design ↔ Code
                       (needs Figma graph + code graph + matching)
                          ▲
   ② B Flows   ② D Audit   ② E Planning-text     ← built on the parsed structure
          ▲          ▲            ▲
          └──────────┴────────────┘
                     │
   ① Foundation: Figma ingestion + structure (+ light design-system model)   ← THIS SPEC

v1 目标（Goals）：

• 通过 Figma REST API（GET /v1/files/:key）接入 Figma 文件，且置于可插拔的源适配器接缝（seam）之后，后续可无改造地加入离线本地 JSON 源；
• 产出浅层结构图：page → screen → component / componentSet / instance，外加轻量设计系统模型（color/type/spacing/effect 等样式的 token 节点，配 uses_token 关系）；
• 通过新的 design-analyzer LLM Agent 做语义增强（摘要、标签、图层提示、屏幕用途）；
• 复用现有 schema、持久化、校验与 Dashboard，只新增 kind: "design" 视图与侧边栏缩略图；
• 渲染采用混合策略：图中节点保持轻量文本，选中节点时才在侧边栏按需加载缩略图；
• v1 解析阶段即前瞻性地记录 prototypeTargets、componentKey 元数据，让路线图 B（用户流）与 C（设计↔代码映射）将来无需重新解析即可启用。

非目标（Non-Goals） 同样写得很明确：

• 不生成设计系统产物（组件库代码、token 文件、Storybook）——只做分析与建模；
• 不在画布节点内渲染缩略图（性能/存储代价），v1 仅侧边栏预览；
• 不把 Figma 每一层都变成节点（一个屏幕可能有数百层）——深层图层会被读取（用于 instance_of 解析、token 用量、未来的规划文本提取），但不晋升为节点；
• B / C / D / E 四项能力不在 v1 范围；
• 不支持离线解析 .fig 专有二进制，离线能力后续经本地 JSON 源适配器实现。

2. Schema 扩展：6 种节点、3 种边，以及一个必须拆除的别名冲突

设计规格选择与 domain、knowledge 扩展完全相同的机制来扩展图谱 schema：NodeType/EdgeType zod 枚举是封闭的（validateGraph 会丢弃未知类型），因此新类型必须追加进枚举，并由别名表（alias-map）归一化 LLM 的词汇；GraphNode 使用 .passthrough()，所以类型化的 figmaMeta 字段可以与 domainMeta/knowledgeMeta 平级共存。这一点在仓库源码中可以直接验证，types.ts 中 KnowledgeGraph 已声明 kind?: "codebase" | "knowledge" | "design"（L109），GraphNode 也声明了 figmaMeta?: FigmaMeta（L66）。

2.1 图级 kind 标志

export interface KnowledgeGraph {
  version: string;
  kind?: "codebase" | "knowledge" | "design"; // 新增 "design"
  // ...
}

不带 kind 的图谱默认视为 "codebase"（行为不变）；Dashboard 依据 kind 切换布局与样式。

2.2 新增节点类型（6 种）：NodeType 21 → 27

类型	表示什么	示例	ID 约定
page	Figma 页面（画布）	"Onboarding"	page:<figmaNodeId>
screen	顶层 frame / artboard（一个 UI 屏幕）	"Login"	screen:<figmaNodeId>
component	主组件	"Button/Primary"	component:<figmaNodeId>
componentSet	变体集合	"Button"	componentSet:<figmaNodeId>
instance	组件的一次使用	"Login › SignInBtn"	instance:<figmaNodeId>
token	设计 token / 已发布样式（color、type、spacing、effect、grid）	"color/brand-500"	token:<tokenKind>:<name>

Figma 的"styles"被折叠进 token（以 figmaMeta.tokenKind 区分），以此控制类型数量。

2.3 新增边类型（3 种）：EdgeType 35 → 38（另复用 contains）

类型	方向	含义
contains（复用）	page → screen，screen → instance，componentSet → component	结构包含
instance_of（新增）	instance → component	某组件的一个实例
variant_of（新增）	component → componentSet	集合内的一个变体
uses_token（新增）	component / screen / instance → token	应用了某个 token / 发布样式

规格中特别标出了别名冲突：instance_of 原本是 EDGE_TYPE_ALIASES 中映射到 exemplifies 的条目（为 knowledge 模式添加），design 模式需要它是一等公民边。解决方案是把 instance_of 提升为正式 EdgeType 并删除其别名条目——因为 knowledge 模式的 Agent 本来就直发 exemplifies（该别名只是保险丝），影响可忽略，且规格要求必须有 schema 测试覆盖该变更。

另外，navigates_to（原型链接，screen → screen）在 v1 不添加——它属于路线图 B；原型链接数据保存在 figmaMeta.prototypeTargets 中，B 落地时可直接据此发边而无需重新解析。

2.4 FigmaMeta 元数据接口

export interface FigmaMeta {
  fileKey?: string;
  nodeId?: string;            // Figma 节点 id，如 "1:23"
  figmaType?: string;         // 原始 Figma 类型: FRAME | COMPONENT | COMPONENT_SET | INSTANCE | TEXT ...
  thumbnailUrl?: string;      // 由 GET /v1/images 惰性填充
  dimensions?: { width: number; height: number };
  tokenKind?: "color" | "type" | "spacing" | "effect" | "grid";
  tokenValue?: string;        // 例如 "#0A84FF"、"16px"
  prototypeTargets?: string[]; // 供路线图 B（用户流）—— v1 记录，边后发
  componentKey?: string;       // 供路线图 C（设计↔代码）—— v1 记录
}

以可选字段形式挂在 GraphNode 上：figmaMeta?: FigmaMeta。

2.5 别名表新增条目

面向合并步骤的 LLM/词汇鲁棒性：

• NODE_TYPE_ALIASES：frame → screen、artboard → screen、canvas → page、main_component → component、variant_set → componentSet、component_set → componentSet、design_token → token、style → token；
• EDGE_TYPE_ALIASES：instantiates → instance_of、variant → variant_of、styled_by → uses_token、applies_token → uses_token（同时按上述说明移除旧的 instance_of → exemplifies 条目）。

3. 接入层：FigmaSource 适配器接缝与 FigmaApiSource

"设计文件从哪里来"与"如何解析"被刻意解耦成一个可插拔接缝：

// packages/core/src/figma/source/types.ts
export interface FigmaSource {
  /** 返回原始 Figma 文档树（GET /v1/files/:key 的形状） */
  fetchDocument(): Promise<FigmaDocument>;
  /** 返回已发布样式元数据（GET /v1/files/:key/styles 的形状） */
  fetchStyles(): Promise<FigmaStyles>;
  /** 为给定节点 id 渲染缩略图（GET /v1/images） */
  renderImages(nodeIds: string[]): Promise<Record<string, string>>;
}

该接口与文档树类型定义在仓库的 source/types.ts 中，FigmaDocument 还额外携带 version（每次编辑都变化）与 lastModified（ISO 时间戳）——这正是后文增量模式的数据来源。

v1 实现是 FigmaApiSource（Node-only），仓库实现见 source/api-source.ts：

• Token 只从 process.env.FIGMA_TOKEN 读取；缺失时构造函数抛出友好提示（到 Figma 官网设置页创建个人访问令牌，然后 export FIGMA_TOKEN=<token>），见 L15-L23；
• 三个 API 端点：文档树 GET {API}/files/:key、样式 GET /files/:key/styles、缩略图 GET /images/:key?ids=…&format=png&scale=1（按需调用），API 基址 https://api.figma.com/v1 硬编码在 L3；
• 同时接受 Figma URL 或裸 file key：parseFileKey 用正则 /figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/ 解析 URL，也接受纯字母数字裸 key，否则抛错；
• 安全细节落在代码注释里：L26-L27 的 get() 方法只把 token 放进 X-Figma-Token 请求头——不进 URL、不进日志，错误信息里也只会打印 API 路径与状态码。

未来实现 LocalJsonSource：读取预导出的 JSON 文档，同一 FigmaSource 接口、无 token、无网络。这是基础版从"仅 API"（A）演进到"两者皆可"的路径。

规格还划定了模块边界：API 客户端与任何 fetch 使用都留在 core 的 Node-only 部分，绝不从浏览器安全子路径（./search、./types、./schema）导出；Dashboard 只共享 schema 类型。仓库的 figma/index.ts 确认了导出面：parseFileKey、FigmaApiSource、parseDocument、extractTokens、applyScreenThumbnails、mergeDesignGraph——全部经独立子路径 @understand-anything/core/figma 暴露。

4. 解析与粒度：浅节点集、深读取、有界 token

确定性解析器（packages/core/src/figma/parse/）遍历文档树、输出结构骨架。粒度原则是浅（shallow）：

• 成为节点的：page、screen（顶层 frame）、component、componentSet、instance、token；
• 不成为节点的：Figma "sections" 在 v1 被压平（其子 frame 挂到父 page）；嵌套 group、文本/矢量/形状叶子层也不成节点；
• 仍被读取（但不成节点）的：更深层图层会被遍历，用于解析 instance_of 目标、收集 uses_token 用量、把 prototypeTargets/componentKey 写入 figmaMeta，（将来为 E 读取规划文本）。

规格用一句话点明关键区分：节点粒度 ≠ 解析粒度——解析器读全树，但只把浅层集合晋升为节点。

4.1 parseDocument：结构骨架如何生成

仓库实现 parse/parse-document.ts 与规格逐条对应：

• mkNode() 统一生成节点：id 为 ${type}:${figmaId}（即规格的 ID 约定），summary 初始等于节点名（占位，Phase 2 由 design-analyzer 填充），tags 为 [type]，complexity 为 "simple"；
• parseDocument() 以 seen 集合去重，仅处理 CANVAS 类型的根子节点（每个 CANVAS → 一个 page 节点）；
• handlePageChild() 按子节点类型分派：FRAME → screen（并把 absoluteBoundingBox 写入 figmaMeta.dimensions）、COMPONENT → component、COMPONENT_SET → componentSet（同时遍历其 COMPONENT 子节点、发 variant_of 边）、SECTION → 递归压平、其余顶层类型忽略；
• 深读取由 collectInstances() 完成：它在 screen 子树里递归找所有 INSTANCE 层，为每个实例发 screen → instance 的 contains 边（权重 1.0）与 instance → component 的 instance_of 边（权重 0.8）。注意 L36-L39 的注释：实例的 componentKey 取自文档 components 映射里的全局发布 key（GUID），因为 child.componentId 只是文件内节点 id（已由 instance_of 边表达）——这正是路线图 C 所需的元数据在 v1 就被记录的方式；
• 原型链接同样在此捕获：child.transitionNodeID 被写入 figmaMeta.prototypeTargets（L40），边留待路线图 B。

4.2 extractTokens：有界 token 集与"就近消费者归因"

Token 是有意有界的：v1 只把已发布样式与变量（color/text/effect/grid 样式、design variables）晋升为 token 节点，保持 token 集有意义并防止节点爆炸。一次性内联值（如孤立的 hex 色值）只记录在使用方节点的 figmaMeta 上，除非能解析到已发布样式/变量，否则不晋升。

仓库实现 parse/tokens.ts 有两个值得展开的细节：

1. 样式类型到 tokenKind 的映射：STYLE_KIND 把 FILL → color、TEXT → type、EFFECT → effect、GRID → grid，未知类型回退 color；token 节点 id 为 token:<kind>:<slug(名称)>，与规格中 token:<tokenKind>:<name> 的 ID 约定一致（slug 化为小写连字符）；
2. 两级桥接 + 就近归因：Figma 节点上的 styles 值是文件内样式 id（如 "2:10"），而 token 节点以全局发布 key 为键——tokens.ts L56 先用文档顶层 styles 映射把本地 id 桥接到发布 key，再查 tokenByStyleKey。另一个精妙处是 walk() 的 consumerId 逻辑：样式通常打在嵌套叶子层（TEXT/RECTANGLE 等）上，而不是浅层结构节点本身，所以实现把"被样式化节点"的 token 用量归因到最近的结构祖先（screen/component/componentSet/instance/page），并用 consumerId|tokenId 去重，保证真实的消费关系不会因样式化图层本身不是节点而丢失。

解析阶段（无 LLM）的产物是 scan-manifest.json——确定性的结构基础图。

5. 四阶段 Agent 流水线：从确定性扫描到合并保存

规格定义了与 /understand-knowledge 同构的四阶段流水线，仓库中的 SKILL.md 与两个脚本 figma-scan.mjs、figma-merge.mjs 与之完全对应：

阶段	步骤	位置	产物
1	FETCH & PARSE	core/figma（确定性）	scan-manifest.json
2	ANALYZE	design-analyzer LLM 子代理（分批）	analysis-batch-*.json
3	MERGE	core/figma/merge + 复用 validateGraph	assembled-graph.json
4	SAVE & LAUNCH	skill + /understand-dashboard	knowledge-graph.json

5.1 Phase 1：fetch & parse

SKILL.md 的 Phase 0 先做预检：解析 URL/key、解析数据目录 $UA_DIR（若项目已有 .understand-anything/ 则沿用旧目录，否则用新的 .ua/）、确认 packages/core/dist/figma/index.js 存在（缺失则 pnpm install + pnpm --filter @understand-anything/core build）、创建 intermediate/ 目录。然后运行：

FIGMA_TOKEN="$FIGMA_TOKEN" node <SKILL_DIR>/figma-scan.mjs "$PROJECT_ROOT" "<url-or-key>"

figma-scan.mjs 的完整流程是：parseFileKey → FigmaApiSource.fetchDocument() → 增量判断 → fetchStyles()（失败降级为空样式）→ parseDocument + extractTokens 合并节点与边 → 仅为 screen 预取缩略图（失败不阻断）→ 写出 scan-manifest.json 并打印各类型节点计数。

其中有两处实现细节超出了规格的文字：

• 缩略图只预取 screen 层级（figma-scan.mjs L46-L54）：URL 是预签名的、数小时后会过期，注释明确说"够用即止——重新运行可刷新"；
• 增量模式：读取 meta.json 里存的 figmaVersion，与 API 返回的 doc.version 比对（L29-L37）。未变化时不重跑解析与 LLM 分析，但会就地刷新已有图谱中的 screen 缩略图 URL（预签名链接会过期，不刷新则 Dashboard 侧边栏图片失效），然后打印 UP_TO_DATE 退出；设置环境变量 UNDERSTAND_FIGMA_FORCE=1 可强制全量重建。规格中的表述是：v1 文件变化即全量重析，"按 Figma nodeId 的节点级增量是未来优化"——这是 /understand 提交哈希增量的 Figma 对应物。

5.2 Phase 2：design-analyzer LLM 子代理

无需 scanner agent——扫描就是 Phase 1 的确定性解析器（与 wiki 解析脚本同理）。新增的 design-analyzer（规格注明"以 article-analyzer 为模板"）的契约是：

• 输入：一批 manifest 节点（每节点含 id、type、name、figmaMeta、childSummary（重要子节点名）、tokenUsage）+ 全部现有节点 ID 列表；
• 输出：每节点的 summary（一两句话，讲这个屏幕/组件是用来做什么的，而非像素描述；token 讲角色，如"CTA 上的主品牌色"）与 tags（2–5 个小写标签，如 auth、entry、cta、empty-state、primary），外加保守的 related 边（仅当名称/结构明显表明同属一个功能/流，例如同一 onboarding 流的两个屏幕）；
• 硬性禁止：不得发明结构节点（page/screen/component/componentSet/instance/token 已存在）、不得重发结构边（contains、instance_of、variant_of、uses_token）、related 边必须使用精确的现有 id；
• 产出写到 $INTERMEDIATE_DIR/analysis-batch-$BATCH_NUM.json，格式示例（来自 design-analyzer.md）：

{
  "nodes": [
    { "id": "screen:1:1", "summary": "The sign-in screen where returning users authenticate.", "tags": ["auth", "entry"] }
  ],
  "edges": [
    { "source": "screen:1:1", "target": "screen:1:5", "type": "related", "direction": "forward", "weight": 0.5, "description": "Both part of the sign-in flow" }
  ]
}

SKILL.md 规定：按页分组、每批约 15 个节点、最多 5 批并发（与 /understand 一致）；单批失败只记警告继续——manifest 本身就是扎实的基础；--language 参数复用 /understand 的语言指令。

5.3 Phase 3：merge——LLM 补丁只能"改"不能"建"

figma-merge.mjs 读取 scan-manifest.json 与全部 analysis-batch-*.json，调用核心函数 mergeDesignGraph()。其合并策略在源码中非常清晰：

1. 索引 manifest 节点（克隆以便富化）；LLM 补丁只能命中已存在的 id（byId.get(patch.id) 找不到就跳过），只更新 summary/tags——从机制上落实了 design-analyzer "不得发明结构节点"的约束；LLM 的 edges（即 related 边）直接追加；
2. Layers：沿 contains 边构建父子表，每个 Figma page 一层（含其后代），组件/变体/token 额外归入专门的 "Design System" 层（merge.ts L33-L66）；未归属任何 page 的节点落入 layer:unscoped；
3. Tour："Design System 优先 → 逐页关键屏幕"，复用现有 tour 结构，每步取前 8 个节点（L68-L75）；
4. 装配 + 校验：组装 { version: "1.0.0", kind: "design", ... } 后过 validateGraph，成功则重新挂回 kind: "design"（L77-L82）——因为校验器会剥离未知字段，这一步是规格里"合并步骤复用 validateGraph"的关键细节。

中间文件约定在 .understand-anything/intermediate/（组装完成后清理，实际 SKILL.md 保留了 scan-manifest.json）：figma-doc.json（原始树缓存）、scan-manifest.json、analysis-batch-*.json、assembled-graph.json。

5.4 Phase 4：save & launch

figma-merge.mjs L28-L35 写出 knowledge-graph.json 与 meta.json（lastAnalyzedAt、figmaVersion、图谱版本 1.0.0、节点数）；SKILL.md 随后清理中间文件（保留 manifest）、汇报节点/边/层/tour 统计，并自动调用 /understand-dashboard 启动视图。

6. Dashboard 变更：kind:"design" 的四个净新增点

规格强调所有变更都限定在 kind: "design" 作用域内，净新增工作只有四处，其余全部复用：

1. App.tsx 的 kind: "design" 分支——像当年加入 KnowledgeGraphView 一样新增设计视图；结构是层级化的，因此复用现有 dagre/ELK 层级布局（类似 DomainGraphView 的 LR 方向）；
2. 按节点类型着色——扩展 CustomNode 的类型→颜色映射：

节点	配色	备注
page	容器 / 中性色	聚合屏幕（同时构成一个 layer）
screen	蓝色（accent）
instance	绿色
component	紫色
componentSet	琥珀色
token	中性色 + 色板	颜色 token 展示其实际颜色

3. 侧边栏（NodeInfo）缩略图——唯一的净新增 UI：选中 figma 节点时显示缩略图区块（名称、类型、尺寸、标签、关系），复用现有上滑/NodeInfo 面板模式；
4. 缩略图供给——复用代码查看器 /file-content.json 的 token-gate + 路径白名单 dev-server 端点模式，作为按需服务的 /figma-image 端点；或者直接把缩略图 URL 存进图谱（v1 实现选择了后者：screen 的预签名 URL 写入 figmaMeta.thumbnailUrl）。

图例与过滤器获得新节点类型条目；布局、搜索、过滤、主题、导出原样复用。仓库中已有两个测试守护这一扩展：allNodeTypes.test.ts 确保 6 种 design 节点类型在 JSON 导出中存活，structuralVisibleTypes.test.ts 确保它们在结构视图下钻时可见；store.ts 的 EdgeCategory 也已包含 "design" 类别。

7. Skill 使用方式与文件布局

7.1 用法

/understand-figma https://www.figma.com/file/<KEY>/<name>   # URL
/understand-figma <FILE_KEY>                                 # 裸 key
/understand-figma <KEY> --page "Onboarding"                  # 限定单个页面（可选）
/understand-figma <KEY> --language ko                        # 复用现有 --language

前置条件：环境变量 FIGMA_TOKEN（Figma 个人访问令牌，在 Figma 官方账号设置页创建后 export FIGMA_TOKEN=<token>）、Node ≥ 22、pnpm ≥ 10。

7.2 行为

1. 解析 URL/key；校验 FIGMA_TOKEN（缺失时给出友好错误并停止）；
2. Phase 1 抓取并解析 → 播报（"发现 N 个 page、N 个 screen、N 个 component、N 个 token"）；
3. Phase 2 design-analyzer 批次（最多 5 并发，容忍单批失败——manifest 是扎实基础）；
4. Phase 3 合并 → 归一化 → validateGraph → kind: "design"；
5. Phase 4 写 knowledge-graph.json + meta.json（含 Figma 文件版本）→ 自动启动 /understand-dashboard。

7.3 文件结构

understand-anything-plugin/
  skills/understand-figma/
    SKILL.md                  — 薄编排层
  agents/
    design-analyzer.md        — 新 LLM Agent
  packages/core/src/figma/
    source/
      types.ts                — FigmaSource 接口（适配器接缝）
      api-source.ts           — FigmaApiSource（REST，Node-only）
    parse/
      parse-document.ts       — 树 → 节点/边（确定性，有测试）
      tokens.ts               — token/样式抽取
    merge.ts                  — manifest + analysis 组装
    index.ts                  — Node-only 入口（不暴露给 dashboard 子路径）
    __tests__/                — vitest 单元测试

规格中的文件布局与仓库实际结构一致，且 __tests__/ 下已有 api-source.test.ts、parse-document.test.ts、tokens.test.ts、merge.test.ts、thumbnails.test.ts 五组单元测试，对应规格"确定性解析器必须有测试"的要求。

8. 路线图：B · C · D · E

每项能力都是后续独立的 spec → plan → implementation 循环，构建在本基础之上：

项	能力	在 v1 之上追加	主要新工作
B	用户流	figmaMeta.prototypeTargets → navigates_to 边 + 流视图	navigates_to 边类型；流布局（复用 flow/step + DomainGraphView）
C	设计 ↔ 代码	figmaMeta.componentKey ↔ 代码图谱组件	双图合并；匹配策略（名称/结构/LLM）；跨图边
D	设计系统审计	分析 instance/token 用量 → 复用率、游离实例、不一致	确定性审计规则；Dashboard 徽标
E	规划文档分析	LLM 读 Figma 规划文本 → claim/entity 节点（复用 knowledge 模式）	深层文本读取；扩展或新增分析器

v1 之所以要"多记录"（prototypeTargets、componentKey）和"深读取"，正是为了让 B/C/E 落地时无需重新解析 Figma 文件。

9. 向后兼容、共存与安全

向后兼容：

• 所有新节点/边类型都是追加式（枚举追加），现有 codebase/knowledge/domain 图谱继续有效；
• 无 kind 的图谱默认 "codebase"；
• figmaMeta 是可选的 passthrough 字段，现有节点不受影响；
• 移除 instance_of → exemplifies 别名影响可忽略（knowledge Agent 直发 exemplifies），由 schema 测试覆盖。

共存：与其他模式一样，/understand-figma 写共享的 .understand-anything/knowledge-graph.json；运行一个模式会替换上一个图谱（既有策略）。对混合仓库，可产出 figma-knowledge-graph.json 子域图谱，经现有 merge-subdomain-graphs.py 同级的子域合并脚本（merge-subdomain-graphs.py）模式合并。

安全（SKILL.md 与规格双重声明）：

• FIGMA_TOKEN 只从环境读取，绝不写入图谱、配置、meta.json、日志或中间文件；请求头（含 token）绝不出现在错误信息与日志中——api-source.ts 的 get() 实现 即此约束的落点；
• 该流水线会对 api.figma.com 发起出站网络调用——这是对 /understand 全离线特性的有意偏离，要求在 skill 输出中向用户明示并写入文档；
• figma-doc.json（原始树缓存）与缩略图是设计数据而非秘密，但 .understand-anything/ 应默认保持 git-ignore；
• 缩略图端点遵循代码查看器既有的 token-gate + 路径白名单模式。

10. 开放问题与未来增强

规格末尾列出的四个方向，均已被适配器接缝或元数据预留支撑：

• 深展开某个屏幕：按需把单个屏幕的更深层图层晋升为节点；
• 节点内缩略图：待侧边栏缩略图管线被验证后，作为可选的更丰富渲染；
• 本地 JSON 源：FigmaSource 接缝的离线实现（完成 A → "两者皆可"的演进）；
• 节点级增量：文件变化时按 Figma nodeId 做 diff，替代全量重析。

11. 关键路径索引

关注点	路径
设计规格（本文主体）	docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.md
实施计划	docs/superpowers/plans/2026-06-24-understand-figma-foundation.md
Skill 编排	understand-anything-plugin/skills/understand-figma/SKILL.md
LLM Agent 定义	understand-anything-plugin/agents/design-analyzer.md
源适配器接口 / API 源	source/types.ts · source/api-source.ts
确定性解析 / token 抽取	parse/parse-document.ts · parse/tokens.ts
合并与校验	figma/merge.ts
扫描 / 合并脚本	figma-scan.mjs · figma-merge.mjs
单元测试	figma/tests/

从规格到落地，/understand-figma 基础版展示了一个可复制的扩展范式：封闭 schema 靠"枚举追加 + 别名归一 + passthrough 元数据"做零破坏扩展；LLM 只负责语义层且被合并阶段机制性地约束在"只能修补既有节点"；确定性解析承担全部结构责任，使整条流水线在 LLM 批次失败时依然有可交付的图谱。这三点共同解释了为什么后续 B/C/D/E 四个子项目可以在不重新解析 Figma 文件的前提下继续叠加。