Understand-Anything 的 design-analyzer 智能体为 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-Anythingdesign-analyzer是 Understand-Anything 插件中负责 Figma 设计文件分析的语义增强智能体Agent定义于 design-analyzer.md。它运行在“确定性解析 → LLM 语义增强 → 合并校验”的三段式流水线中段确定性的扫描脚本先把 Figma 文件解析为结构节点页面、屏幕、组件、变体集、实例、设计令牌和结构边design-analyzer 则在此基础上为每个节点补充“这个屏幕/组件是干什么用的”这一层语义——摘要、标签与少量保守的related关系边。读完本文你将理解该智能体的输入输出契约、四条硬约束规则背后的工程动机以及它的产物如何被mergeDesignGraph消费并落入最终的kind:design知识图谱。在 /understand-figma 流水线中的位置/understand-figma技能见 SKILL.md的完整流程为Phase 1确定性运行 figma-scan.mjs通过 Figma REST API 拉取文件文档与样式调用parseDocument与extractTokens生成$UA_DIR/intermediate/scan-manifest.json并打印各类型节点计数若文件版本未变则打印UP_TO_DATE直接退出。Phase 2LLM 增强把 manifest 中的节点按“尽量按 page 分组、每批约 15 个”切批逐批派发design-analyzer智能体。智能体收到批次节点、全量已存在节点 ID 列表、$INTERMEDIATE_DIR和批次号写出analysis-batch-N.json。最多 5 个批次并发执行单批失败只记录告警并继续——manifest 本身已经是可靠的兜底基线。Phase 3合并运行 figma-merge.mjs合并 manifest 与全部analysis-batch-*.json执行mergeDesignGraph校验后写出knowledge-graph.json与meta.json。design-analyzer 正是 Phase 2 中每个批次使用的 Agent 定义。这种“确定性打底、语义层可选增强”的拆分意味着即便所有 LLM 批次都失败用户依然能拿到一张结构完整的设计图只是缺少目的性摘要。输入契约一批 manifest 节点智能体接收的输入是一批 JSON 格式的 manifest 节点。每个节点包含以下字段这些字段由 figma-scan.mjs 写入 manifest字段含义id全局唯一节点 ID形如screen:1:1、token:color:brandtype枚举值之一page|screen|component|componentSet|instance|tokenname节点在 Figma 中的显示名称figmaMeta元数据尺寸dimensions、令牌种类tokenKind、组件发布键componentKey等childSummary该节点下值得注意的子节点名称用于 screen/component帮助判断屏幕内容而不需要看像素tokenUsage该节点用到的设计令牌名称列表如存在此外智能体还会收到完整的已存在节点 ID 列表用于在生成related边时只能引用真实存在的 ID。从源码看这些字段并非凭空约定。parse-document.ts 中的parseDocument负责生成结构节点CANVAS 映射为pageFRAME 映射为screen并深读子树收集 INSTANCE 节点建立contains/instance_of边COMPONENT / COMPONENT_SET 分别生成component与componentSet节点及variant_of边tokens.ts 中的extractTokens则只把已发布的样式/变量转为token节点限定集合规模并沿文档树把样式用法归因到最近的结构性祖先生成uses_token边。一个值得注意的细节parseDocument创建节点时写入的summary只是节点名本身代码注释明确写着placeholder; design-analyzer enriches in Phase 2。也就是说design-analyzer 的摘要是对占位符的正式替换这是两个阶段之间的隐含接口。任务为每个节点产出语义增强对象智能体对批次中每个节点产出一个增强对象只含两个字段summary一两句话说明该屏幕/组件是做什么的purpose而不是描述像素内容。对 token 节点则说明其角色例如 “Primary brand color used on CTAs”。tags2–5 个小写标签功能域、角色、状态示例auth、entry、cta、list、empty-state、primary。在此之外智能体可以选择性地输出保守的related边连接明显属于同一功能域/同一流程的节点例如同一 onboarding 流程中的两个屏幕。约束是“只有当名称/结构让它显而易见时”才输出——这是防止 LLM 幻觉污染图结构的关键闸门。四条硬规则及其工程动机design-analyzer.md的 Rules 部分规定了四条约束禁止输出page/screen/component/componentSet/instance/token节点——它们已经存在智能体只能产出增强对象与可选的related边禁止重新输出结构边contains、instance_of、variant_of、uses_token输出related边时必须使用精确的已存在id保持简洁约 15 个节点的批次预期产出约 15 条增强与 0–8 条related边。这些规则并非单纯的对 LLM 的叮嘱而是与合并端代码逐条对应的防御性设计合并端会丢弃未知节点。merge.ts 中增强补丁按id在 manifest 节点索引里查找查不到就continue跳过summary/tags也只在补丁提供时才覆盖占位值。规则 1 因此在实现层面被强制执行智能体即便违规生造节点也不会进入最终图谱。related是唯一合法的新边类型。related在图谱 schema 中被归类为 Semantic 类标准边见 schema.ts同时 schema 还为 LLM 常见的近义写法提供了别名归一如relates_to/related_to→related。而四种结构边只由确定性解析器产出LLM 重发它们既多余又可能引入 ID 笔误故被规则 2 禁止。mergeDesignGraph单测直接验证了这套契约。merge.test.ts 中的用例 “applies design-analyzer enrichment by id” 精确模拟了智能体输出——给screen:1:1打上summary: The sign-in screen和tags: [auth, entry]——然后断言合并后该节点的summary与tags被正确替换。这正是文档中 JSON 示例对应的真实消费路径。输出格式与落盘约定智能体把结果写入$INTERMEDIATE_DIR/analysis-batch-$BATCH_NUM.json$INTERMEDIATE_DIR即$UA_DIR/intermediate其中$UA_DIR优先取已存在的.understand-anything/否则新建.ua/。文件结构如下{ 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 } ] }智能体应只输出增强对象idsummary/tags与可选的related边不含其他内容。合并端 figma-merge.mjs 用正则^analysis-batch-.*\.json$扫描 intermediate 目录收集所有批次文件与scan-manifest.json一起送入mergeDesignGraph合并成功后写出knowledge-graph.json和meta.json后者记录figmaVersion、analyzedFiles等。related边的 schema 字段source/target/type/direction/weight/description与 schema.ts 中GraphEdgeSchema的边定义一致direction: forward与确定性解析器产边的方式保持一致见 parse-document.ts 的link辅助函数。语义层最终如何被呈现理解 design-analyzer 的产出如何被消费能反过来解释它的输入输出约束为何如此设计节点增强直接可见summary替换占位摘要、tags替换默认的[type]标签后仪表盘节点信息面板展示的就是智能体写下的目的性描述例如 “The sign-in screen where returning users authenticate.”。分层与导览是确定性的不依赖 LLMmerge.ts 在合并阶段按contains边回溯父链为每个 Figma page 建一个 layer并把全部component/componentSet/token节点单独归入 “Design System” layer导览tour固定以 Design System 为首站再逐页展开。这意味着智能体输出的related边只补充语义关联而不会改变图的整体骨架——骨架完全由确定性解析与合并逻辑决定。失败可降级Phase 2 允许批次失败继续、Phase 3 后还会清理除scan-manifest.json外的中间文件因此analysis-batch-*.json是一次性产物。若 Figma 文件版本未变重跑时 Phase 1 走UP_TO_DATE分支仅刷新会过期的预签名缩略图 URL根本不重放 LLM 增强——语义层只在建图时计算一次。关键文件索引文件角色design-analyzer.md本文主题智能体的输入/任务/规则/输出契约SKILL.md/understand-figma技能定义分批约 15 节点/批、按 page 分组、5 并发与失败降级策略figma-scan.mjsPhase 1 扫描脚本产出scan-manifest.json与版本级增量判断figma-merge.mjsPhase 3 合并脚本收集analysis-batch-*.json并落盘图谱parse-document.ts确定性结构解析产出的占位summary等待智能体增强tokens.ts设计令牌提取与uses_token边生成merge.tsmergeDesignGraph按 ID 应用增强、忽略未知节点、构建 layer 与 tourschema.ts图谱 schemarelated为标准 Semantic 边含 LLM 别名归一merge.test.ts验证“design-analyzer 按 ID 增强”等契约的测试总结来说design-analyzer智能体体现了一种稳健的 LLM 集成模式把“什么是事实”结构、ID、结构边交给确定性代码把“意味着什么”目的、标签、弱关联交给模型并在合并端用 ID 白名单和 schema 校验兜底使 LLM 的任何越界输出都无法污染最终的设计知识图谱。【免费下载链接】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），仅供参考