Understand-Anything /understand-figma：把 Figma 文件变成 kind:“design“ 知识图谱的设计与实现

Understand-Anything /understand-figma把 Figma 文件变成 kind:design 知识图谱的设计与实现【免费下载链接】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 仓库中已批准的 Figma 基础设计规格docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.ko.md其英文原文为docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.md展开完整覆盖基因为先的范围分解、知识图谱 schema 扩展、可插拔的 Figma 源适配器、确定性解析与浅粒度策略、四阶段 Agent 流水线、仪表盘变更、技能接口与安全边界并结合packages/core/src/figma/下的真实源码逐条印证设计决策的落地方式帮助读者掌握非代码输入 → 结构化知识图谱这一扩展范式。背景为什么基础优先/understand-figma是 Understand Anything 插件内的新技能接收一个 Figma 文件产出可交互的知识图谱——页面page、屏幕screen、组件component、组件集componentSet、实例instance、设计令牌token——并以kind: design布局在既有仪表盘上可视化。这与/understand-knowledge维基和/understand-domain业务域扩展非代码输入的方式完全一致确定性解析构建结构骨架LLM 代理补充语义合并步骤组装出同一份knowledge-graph.json同一套仪表盘负责渲染。该文档是 5 个子项目中的第 1 个基础其余 4 个仅作为路线图定义各自拥有独立的 规格 → 计划 → 实现 周期③ C 设计 ↔ 代码 (需要 Figma 图 代码图 匹配) ▲ ② B 流程 ② D 审计 ② E 规划文本 ← 构建在已解析结构之上 ▲ ▲ ▲ └─────────┴───────────┘ │ ① 基础: Figma 收集 结构 ( 轻量设计系统模型) ← 本规格A本规格确立收集、kind: designschema、解析模块、技能骨架与仪表盘视图——其余一切的前提。B / D / E是对同一份解析数据的附加抽取。C是收官之作需要 Figma 图A 代码图/understand 匹配策略三者齐备。目标与非目标目标通过 Figma REST APIGET /v1/files/:key收集 Figma 文件但置于可插拔的源适配器边界之后以便日后不返工地加入离线本地 JSON 源生成浅层结构图page → screen → component / componentSet / instance外加轻量设计系统模型面向色/字号/间距/效果样式的token节点与uses_token关系;新增design-analyzerLLM 代理做语义增强摘要、标签、图层提示、屏幕用途复用既有 schema、持久化、校验与仪表盘只新增kind: design视图与侧边栏缩略图;混合渲染策略图中是轻量文本节点选中节点的缩略图在侧边栏按需显示v1 解析期间记录前瞻元数据prototypeTargets、componentKey使路线图 B、C 无需重新解析即可启用。非目标不生成设计系统产物代码组件库、token 文件、Storybook——本工作只做分析/建模不在画布内做节点内缩略图渲染性能/存储成本——v1 仅侧边栏预览不把每个 Figma 图层都变成节点一个屏幕可能有数百个图层。更深层图层会被读取用于instance_of链接、token 使用、将来的规划文本提取但不成为节点B用户流程、C设计↔代码、D设计系统审计、E规划文档分析是路线图不属于 v1不解析离线.fig专有二进制离线支持将由本地 JSON 源适配器提供。Schema 扩展与 domain/knowledge 相同的机制扩展机制与domain、knowledge一致NodeType/EdgeType的 zod 枚举是封闭的validateGraph会丢弃未知类型因此新类型必须追加进枚举而 alias 映射负责把 LLM 的词汇规范化。GraphNode使用.passthrough()所以带类型的figmaMeta字段可以与domainMeta/knowledgeMeta并列存放。这一点在 types.ts 中得到印证设计节点类型page、screen、component、componentSet、instance、token与设计边类型instance_of、variant_of、uses_token已经并入枚举figmaMeta?: FigmaMeta作为可选字段挂在GraphNode上。图级 Kind 标志export interface KnowledgeGraph { version: string; kind?: codebase | knowledge | design; // 新增 design // ... }没有kind的图按codebase处理行为不变仪表盘按kind切换布局/样式。schema.ts 中kind正是z.enum([codebase, knowledge, design]).optional()。新增节点类型6 个—— 21 → 27类型含义示例ID 规则pageFigma 页面画布Onboardingpage:figmaNodeIdscreen顶层 frame/画板UI 屏幕Loginscreen:figmaNodeIdcomponent主组件Button/Primarycomponent:figmaNodeIdcomponentSet变体集合ButtoncomponentSet:figmaNodeIdinstance组件的使用处Login › SignInBtninstance:figmaNodeIdtoken设计令牌/已发布样式色、字号、间距、效果、网格color/brand-500token:tokenKind:nameFigma 的 styles 统一折叠进token用figmaMeta.tokenKind区分以控制类型数量。新增边类型3 个—— 35 → 38另复用contains类型方向含义contains(复用)page → screenscreen → instancecomponentSet → component结构包含instance_of(新增)instance → component某组件的实例variant_of(新增)component → componentSet集合内的变体uses_token(新增)component / screen / instance → token应用了某令牌/已发布样式instance_of的 alias 冲突instance_of原本是EDGE_TYPE_ALIASES中映射到exemplifies的条目knowledge 模式引入。design 模式下它必须是一等边类型。规格给出的方案是将instance_of提升为正式的EdgeType并移除其 alias 条目——knowledge 代理本就直接输出exemplifiesalias 只是安全网影响微乎其微。实际实现比规格走得更细致从 schema.ts 的源码看实现采用按 kind 作用域划分 alias 表的方式消解了冲突——instantiates → instance_of、variant → variant_of、styled_by → uses_token、applies_token → uses_token这一组设计边 alias仅在图的 kind 为 design 时生效而instance_of → exemplifies则保留在非 design kind的 alias 表中。这样既让 design 图里instance_of是一等边又不动 knowledge 模式的行为比直接删条目更安全。navigates_to原型链接screen → screen不在 v1 添加——归路线图 B 所有。原型链接数据保存在figmaMeta.prototypeTargets中B 之后可以不再解析就补上这些边。新增元数据接口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上export interface GraphNode { // ...既有字段 figmaMeta?: FigmaMeta; }Alias 映射新增为合并步骤中的 LLM/词汇健壮性NODE_TYPE_ALIASESframe → screen、artboard → screen、canvas → page、main_component → component、variant_set → componentSet、component_set → componentSet、design_token → token、style → token。EDGE_TYPE_ALIASESinstantiates → instance_of、variant → variant_of、styled_by → uses_token、applies_token → uses_token并处理上文所述instance_of → exemplifies条目。实现侧的一个细节值得注意见 schema.ts由于sanitizeGraph会把节点类型全部小写化而componentSet是唯一含大写的类型非 design kind 的节点 alias 表里额外补了componentset → componentSet并且page → article这类映射只作用于非 design kind——否则 Figma 的 page 会被误规范化成维基的 article。这正是 alias 表必须感知 kind 的原因。收集FigmaSource 源适配器文档从哪来与如何解析之间的一条可插拔边界定义在 source/types.ts// packages/core/src/figma/source/types.ts export interface FigmaSource { /** 返回原始 Figma 文档树 (GET /v1/files/:key 的形状). */ fetchDocument(): PromiseFigmaDocument; /** 返回已发布样式元数据 (GET /v1/files/:key/styles 的形状). */ fetchStyles(): PromiseFigmaStyles; /** 为给定节点 id 渲染缩略图 (GET /v1/images). */ renderImages(nodeIds: string[]): PromiseRecordstring, string; }同文件中还定义了FigmaDocument根DOCUMENT节点的 children 是CANVAS页面附带version/lastModified用于增量判断、顶层components/componentSets/styles映射、FigmaNode含componentId、absoluteBoundingBox、styles、transitionNodeID等字段与FigmaStyles。v1 实现 ——FigmaApiSourcesource/api-source.ts仅 Node从process.env.FIGMA_TOKEN读取 token。缺失时技能以友好消息中断到 figma.com/settings 创建个人访问令牌然后export FIGMA_TOKENtoken。源码构造函数确实抛出带指引的错误信息文档树走GET /v1/files/:key样式走GET /v1/files/:key/styles缩略图走GET /v1/images/:key?ids…按需formatpngscale1同时接受 Figma URL 或裸文件键。parseFileKey的正则同时匹配figma.com/file/与figma.com/design/两种 URL 形态纯[A-Za-z0-9]字符串则直接当 key 用无法解析时抛出明确错误安全约束在代码注释里写得很直白token 只出现在请求头X-Figma-Token绝不出现在 URL 中也绝不进日志。未来 ——LocalJsonSource读取预先导出的 JSON 文档同一套FigmaSource接口无需 token、无需网络。这是基础从仅 APIA演进到两者皆可的路径。API 客户端与一切fetch用法都位于core的仅 Node 部分绝不从浏览器安全子路径./search、./types、./schema导出仪表盘只共享 schema 类型。figma/index.ts 是这条 Node 专属入口仅导出parseFileKey、FigmaApiSource、parseDocument、extractTokens、applyScreenThumbnails、mergeDesignGraph等符号。解析与粒度浅节点深读取确定性解析器packages/core/src/figma/parse/遍历文档树并产出结构骨架粒度刻意浅是节点page、screen顶层 frame、component、componentSet、instance、token不是节点Figma section 在 v1 中被扁平化其子 frame 挂到父page下嵌套 group 以及文本/矢量/形状叶子图层也不是节点仍被读取但不成节点更深层图层被遍历以解析instance_of目标、收集uses_token使用、把prototypeTargets/componentKey记入figmaMeta以及将来供 E读取规划文本。节点粒度 ≠ 解析粒度解析器读完整棵树只把浅层集合提升为节点。parse-document.ts 的实现与规格逐条对应遍历doc.document.children中每个CANVAS创建page节点mkNode生成的节点 id 即${type}:${figmaId}与规格 ID 规则一致summary先占位、tags初始为[type]等待 Phase 2 增强handlePageChild按 Figma 类型分派FRAME→screen带dimensions 递归collectInstances深读子树收集实例COMPONENT→componentCOMPONENT_SET→componentSet其子COMPONENT逐个成节点并连variant_of边SECTION→ 递归扁平化其他顶层类型 v1 忽略collectInstances深读屏幕子树遇到INSTANCE节点时创建instance节点componentKey取自文档顶层components映射中的全局发布 key注释特别说明child.componentId只是文件内节点 id已由instance_of边捕获transitionNodeID存在则记入prototypeTargets边权重在源码中是确定性的contains1.0、variant_of0.9、instance_of0.8见 parse-document.ts。令牌刻意有界v1 只把已发布样式与变量色/文本/效果/网格样式、设计变量提升为token节点——保证令牌集合有意义、不引发节点爆炸。原始内联值如一次性的 hex只记在消费节点自己的figmaMeta上除非能解析到已发布样式/变量否则不提升为token节点。每个token节点带figmaMeta.tokenKindtokenValue由uses_token边连接消费者。tokens.ts 里可以看到有界如何落地样式类型到 tokenKind 的映射是FILL → color、TEXT → type、EFFECT → effect、GRID → grid未知类型回落到colortoken 节点 id 为token:kind:slug(样式名)一个关键桥接细节节点上的styles值是文件内样式 id如2:10指向文档顶层styles映射而 token 节点按/files/:key/styles返回的全局发布 key建索引——extractTokens显式做本地 id → 发布 key的桥接找不到映射时退回直接匹配兼容不提供顶层映射的源由于样式通常打在嵌套叶子图层TEXT/RECTANGLE…而非浅层结构节点本身walk会把被样式化节点的 token 使用归属到最近的结构祖先screen/component/componentSet/instance/page并用consumerId|tokenId去重避免真实消费关系因被打样的图层本身不是节点而丢失uses_token边权重 0.5。输出scan-manifest.json确定性、无 LLM——结构基础图。Agent 流水线四阶段复刻 /understand-knowledge阶段步骤位置输出1FETCH PARSEcore/figma确定性scan-manifest.json2ANALYZEdesign-analyzerLLM 子代理批处理analysis-batch-*.json3MERGEcore/figma/merge 复用validateGraphassembled-graph.json4SAVE LAUNCH技能 /understand-dashboardknowledge-graph.json新代理design-analyzer代理输入输出design-analyzer(新增以article-analyzer为蓝本)一批清单节点id、名称、类型、figmaMeta、子节点摘要、token 使用 既有节点 ID 全表每节点增强摘要、标签、图层提示、屏幕用途 保守的related边。不重新生成结构节点/边。不需要扫描器代理——扫描由 Phase 1 的确定性解析器完成与维基解析脚本同理。仓库中的 agents/design-analyzer.md 把边界划得非常硬摘要写这个屏幕/组件为了什么而非像素描述标签 2–5 个小写词如auth、entry、cta、empty-staterelated边只在名称/结构明显同属一个功能流时才输出每批 ~15 节点期望 0–8 条且禁止重新输出任何结构节点与结构边related边必须使用精确的既有id。输出写入$INTERMEDIATE_DIR/analysis-batch-$BATCH_NUM.json格式为{ nodes: [{id, summary, tags}], edges: [...] }。中间文件.understand-anything/intermediate/组装后清理figma-doc.json原始树缓存、scan-manifest.json、analysis-batch-*.json、assembled-graph.json。图层与导览Tour图层每个 Figma 页面一层外加一个专属 Design System 层组件、组件集、令牌导览Design System 优先 → 关键屏幕复用既有 tour 结构。merge.ts 完整实现了这两点mergeDesignGraph先用contains边建 parent 索引、沿链回溯找到每个节点所属页面带环保护把component/componentSet/token三类节点划入layer:design-system层描述 Components, variants, and design tokens其余按页面归层、无归属的落入layer:unscopedtour 第一步固定是 Design System最多取 8 个节点随后每个页面一层依次展开。合并末尾的装配也保留了规格要求validateGraph校验后重新挂回kind: design因为校验流程会将其丢弃。增量模式重跑时对比meta.json中存储的 Figma 文件version/lastModified来自 API。未变 → 跳过变了 → v1 全量重新分析按 FigmanodeId的节点级增量是将来优化。这是/understand提交哈希增量的 Figma 版对应物。figma-scan.mjs 的实现有一个规格未细说但很关键的细节预签名缩略图 URL 数小时后会过期因此即便UP_TO_DATE命中doc.version prevVersion且未设UNDERSTAND_FIGMA_FORCE1脚本也会就地重渲染屏幕缩略图并补丁既有knowledge-graph.json再打印UP_TO_DATE退出——避免下次打开仪表盘时侧边栏出现一堆裂图。缩略图刷新整体是 best-effort永不抛错。仪表盘变更全部限定在 kind: design 内纯新增工作只有四处其余全部复用kind: design分支App.tsx——新增 design 视图就像当初添加KnowledgeGraphView那样。结构是层级式的故复用既有 dagre/ELK 层级布局类似DomainGraphView的 LR。现有 App.tsx 已按kind分支挂载KnowledgeGraphView与DomainGraphViewdesign 分支沿同一模式扩展按类型的节点样式——给CustomNode增加类型→颜色映射节点强调色备注page容器/中性归组屏幕同时构成一层screen蓝accentinstance绿component紫罗兰componentSet琥珀token中性 色板色块颜色令牌显示其实际颜色侧边栏NodeInfo缩略图 —— 唯一的纯新 UI选中 figma 节点时显示缩略图块名称、类型、尺寸、标签、关系复用既有 slide-up/NodeInfo 面板模式缩略图供给——复用代码查看器/file-content.json所用的token 门 路径 allowlist开发服务器端点模式提供按需的/figma-image端点或者把缩略图 URL 直接存进图里。图例与过滤器增加新节点类型条目。布局、搜索、过滤、主题、导出全部原样复用。技能接口用法/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前置条件见 SKILL.mdFIGMA_TOKEN环境变量、Node ≥ 22、pnpm ≥ 10若packages/core/dist/figma/index.js缺失先pnpm --filter understand-anything/core build构建 core。行为解析 URL/key校验FIGMA_TOKEN缺失时友好报错;Phase 1 fetch parse → 播报发现摘要N pages, N screens, N components, N tokens 已发现;Phase 2design-analyzer批处理最多 5 个并发与/understand相同允许单批失败——清单是扎实的基础。SKILL.md 规定节点按每批约 15 个分组、尽量按页面聚批;Phase 3 merge → 规范化 →validateGraph→kind: design由figma-merge.mjs调用mergeDesignGraph完成;Phase 4 写knowledge-graph.jsonmeta.json含 Figma 文件版本→ 自动拉起/understand-dashboard并清理中间文件保留scan-manifest.json。文件结构understand-anything-plugin/ skills/understand-figma/ SKILL.md — 薄编排层 agents/ design-analyzer.md — 新增 LLM 代理 packages/core/src/figma/ source/ types.ts — FigmaSource 接口(适配器边界) api-source.ts — FigmaApiSource (REST, 仅 Node) parse/ parse-document.ts — 树 → 节点/边 (确定性, 有测试) tokens.ts — 令牌/样式抽取 merge.ts — 清单 分析装配 index.ts — 仅 Node 入口(不暴露给仪表盘子路径) __tests__/ — vitest 单元测试以上结构在仓库中逐一可查skills/understand-figma/ 还包含两个编排脚本figma-scan.mjs与figma-merge.mjscore 侧__tests__/下有api-source.test.ts、parse-document.test.ts、tokens.test.ts、thumbnails.test.ts、merge.test.ts五个 vitest 单测覆盖解析、令牌桥接、缩略图填充与合并校验兑现了规格确定性解析必须带测试的要求。路线图B · C · D · E每一项都是后续独立的 规格 → 计划 → 实现 周期构建在本基础之上项能力在 v1 之上增加主要新工作B用户流程figmaMeta.prototypeTargets→navigates_to边 流程视图navigates_to边类型流程布局复用 flow/step DomainGraphViewC设计 ↔ 代码figmaMeta.componentKey↔ 代码图组件两图结合匹配策略名称/结构/LLM跨图边D设计系统审计分析实例/token 使用 → 复用率、游离实例、不一致确定性审计规则仪表盘徽章E规划文档分析LLM 读 Figma 规划文本 →claim/entity节点复用 knowledge 模式深读文本图层扩展现有或新增分析器正因为 v1 记录了prototypeTargets、componentKey并深读了深层图层B/C/E 才能免重解析直接挂接。向后兼容、共存与安全向后兼容所有新节点/边类型都是追加式枚举增项既有 codebase/knowledge/domain 图保持有效无kind的图按codebase处理figmaMeta是可选 passthrough 字段——既有节点不受影响instance_ofalias 的处理影响微小knowledge 代理直接输出exemplifies由 schema 测试覆盖。共存与其他模式一样/understand-figma写入共享的.understand-anything/knowledge-graph.json运行某一种模式会替换既有图既有策略。SKILL.md 还约定数据目录的向后兼容解析已存在.understand-anything/则用之否则用新目录.ua/混合仓库中可产出figma-knowledge-graph.json子域图按既有 merge-subdomain-graphs.py 模式合并。安全FIGMA_TOKEN只从环境变量读取绝不写入图、config、meta.json、日志或中间文件携带 token 的请求头绝不出现在错误/日志中FigmaApiSource.get的注释即此约定;流水线会向 Figma API 发起出站网络调用——这与/understand的全离线性质不同需要在技能输出中一次性告知用户figma-doc.json原始树缓存与缩略图属于设计数据非机密但.understand-anything/默认保持 git-ignore 仍是推荐做法缩略图端点沿用代码查看器既有的 token 门 路径 allowlist 模式。未来改进项屏幕深度展开按需把单个屏幕的深层图层提升为节点节点内缩略图侧边栏缩略图管线验证成熟后提供可选的更丰富渲染本地 JSON 源FigmaSource边界的离线实现A → 两者皆可的演进节点级增量文件变更时按 FigmanodeId做 diff替代全量重分析。延伸阅读英文原版规格docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.md内容冲突时以英文原文为准技能定义 SKILL.md核心实现 figma/index.ts代理定义 design-analyzer.mdschema 校验 schema.ts。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考