企业官网建设流程全解析

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

【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything

本文以 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-analyzerLLM 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/EdgeTypezod 枚举是封闭的（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

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

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

规格中特别标出了别名冲突：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 与之完全对应：

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 文件变化即全量重析，"按 FigmanodeId的节点级增量是未来优化"——这是/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的类型→颜色映射：

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 之所以要"多记录"（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 → "两者皆可"的演进）；
• 节点级增量：文件变化时按 FigmanodeId做 diff，替代全量重析。

11. 关键路径索引

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

【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything