Understand-Anything 的 design-analyzer 智能体：为 Figma 设计图注入语义层

design-analyzer 是 Understand-Anything 插件中负责 Figma 设计文件分析的语义增强智能体（Agent），定义于 design-analyzer.md。它运行在“确定性解析 → LLM 语义增强 → 合并校验”的三段式流水线中段：确定性的扫描脚本先把 Figma 文件解析为结构节点（页面、屏幕、组件、变体集、实例、设计令牌）和结构边，design-analyzer 则在此基础上为每个节点补充“这个屏幕/组件是干什么用的”这一层语义——摘要、标签与少量保守的 related 关系边。读完本文，你将理解该智能体的输入输出契约、四条硬约束规则背后的工程动机，以及它的产物如何被 mergeDesignGraph 消费并落入最终的 kind:"design" 知识图谱。

在 /understand-figma 流水线中的位置

/understand-figma 技能（见 SKILL.md）的完整流程为：

1. Phase 1（确定性）：运行 figma-scan.mjs，通过 Figma REST API 拉取文件文档与样式，调用 parseDocument 与 extractTokens 生成 $UA_DIR/intermediate/scan-manifest.json，并打印各类型节点计数；若文件版本未变则打印 UP_TO_DATE 直接退出。
2. Phase 2（LLM 增强）：把 manifest 中的节点按“尽量按 page 分组、每批约 15 个”切批，逐批派发 design-analyzer 智能体。智能体收到批次节点、全量已存在节点 ID 列表、$INTERMEDIATE_DIR 和批次号，写出 analysis-batch-<N>.json。最多 5 个批次并发执行；单批失败只记录告警并继续——manifest 本身已经是可靠的兜底基线。
3. 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:brand
type	枚举值之一：page | screen | component | componentSet | instance | token
name	节点在 Figma 中的显示名称
figmaMeta	元数据：尺寸（dimensions）、令牌种类（tokenKind）、组件发布键（componentKey）等
childSummary	该节点下值得注意的子节点名称（用于 screen/component，帮助判断屏幕内容而不需要看像素）
tokenUsage	该节点用到的设计令牌名称列表（如存在）

此外，智能体还会收到完整的已存在节点 ID 列表，用于在生成 related 边时只能引用真实存在的 ID。

从源码看，这些字段并非凭空约定。parse-document.ts 中的 parseDocument 负责生成结构节点：CANVAS 映射为 page，FRAME 映射为 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”。
• tags：2–5 个小写标签（功能域、角色、状态），示例：auth、entry、cta、list、empty-state、primary。

在此之外，智能体可以选择性地输出保守的 related 边，连接明显属于同一功能域/同一流程的节点（例如同一 onboarding 流程中的两个屏幕）。约束是“只有当名称/结构让它显而易见时”才输出——这是防止 LLM 幻觉污染图结构的关键闸门。

四条硬规则及其工程动机

design-analyzer.md 的 Rules 部分规定了四条约束：

1. 禁止输出 page/screen/component/componentSet/instance/token 节点——它们已经存在，智能体只能产出增强对象与可选的 related 边；
2. 禁止重新输出结构边（contains、instance_of、variant_of、uses_token）；
3. 输出 related 边时必须使用精确的已存在 id；
4. 保持简洁：约 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" }
  ]
}

智能体应只输出增强对象（id + summary/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.”。
• 分层与导览是确定性的，不依赖 LLM：merge.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.mjs	Phase 1 扫描脚本，产出 scan-manifest.json 与版本级增量判断
figma-merge.mjs	Phase 3 合并脚本，收集 analysis-batch-*.json 并落盘图谱
parse-document.ts	确定性结构解析，产出的占位 summary 等待智能体增强
tokens.ts	设计令牌提取与 uses_token 边生成
merge.ts	mergeDesignGraph：按 ID 应用增强、忽略未知节点、构建 layer 与 tour
schema.ts	图谱 schema：related 为标准 Semantic 边，含 LLM 别名归一
merge.test.ts	验证“design-analyzer 按 ID 增强”等契约的测试

总结来说，design-analyzer 智能体体现了一种稳健的 LLM 集成模式：把“什么是事实”（结构、ID、结构边）交给确定性代码，把“意味着什么”（目的、标签、弱关联）交给模型，并在合并端用 ID 白名单和 schema 校验兜底，使 LLM 的任何越界输出都无法污染最终的设计知识图谱。