基于 FigmaMCP 的 D2C 工具(四): ingest——把 Figma 噪声收成 DesignIntentIR

Group 12
├── Decoration line          RECTANGLE 1px 高
└── Frame 1000011563         FRAME 圆角 4 实心填充
    └── 确认                  TEXT

{
  "node": {
    "id": "1:2", "name": "Group 12", "type": "GROUP",
    "absoluteBoundingBox": { "x": 16, "y": 600, "width": 343, "height": 84 },
    "children": [
      { "id": "1:3", "name": "Decoration line", "type": "RECTANGLE", "fills": [{ "type": "SOLID" }],
        "absoluteBoundingBox": { "x": 16, "y": 600, "width": 343, "height": 1 }, "children": [] },
      { "id": "1:4", "name": "Frame 1000011563", "type": "FRAME", "cornerRadius": 4, "fills": [{ "type": "SOLID" }],
        "absoluteBoundingBox": { "x": 16, "y": 640, "width": 343, "height": 44 },
        "children": [
          { "id": "1:5", "name": "确认", "type": "TEXT", "characters": "确认", "fills": [{ "type": "SOLID" }],
            "boundVariables": { "fills": { "id": "VariableID:12:34" } },
            "absoluteBoundingBox": { "x": 165, "y": 652, "width": 45, "height": 20 }, "children": [] }
        ] }
    ]
  }
}

interface DesignIntentIR {
  schemaVersion: 2
  kind: 'design-intent'
  id: string                          // design:{documentId}:{rootIds}
  source: {
    adapter: 'figma-rest' | 'figma-mcp' | 'design-intent-v2'
    documentId: string
    fingerprint: string               // 整份输入 JSON 的 sha256
    evidence: EvidenceRef[]
  }
  roots: DesignIntentNode[]           // 至少一个 空树在 schema 层就过不去
  normalization: NormalizationTrace[] // 每个节点的 keep / flatten / drop 记录
  layout: LayoutConstraintGraph       // 布局约束图 单独成图 不挂在节点上
  unresolved: UnresolvedFact[]        // 解不开的事实 不是警告
  evidence: EvidenceRef[]
}

// EvidenceRef = { source, locator, extractorVersion, fingerprint, confidence }
// locator 格式 figma://{documentId}/{nodeId} 后面 ProofObligation 引用设计侧证据就靠它

interface DesignIntentNode {
  id: string
  name: string
  nodeType: 'frame' | 'group' | 'instance' | 'text' | 'shape' | 'vector' | 'unknown' | /* ... */
  role?: DesignRole                   // button / input / table / dialog / display ... 可以为空
  visible?: boolean | UnresolvedFact
  component?: { componentKey?: string, codeComponentId?: string, variantProperties?: Record<string, string>, evidence: EvidenceRef[] }
  text?: { characters: string, evidence: EvidenceRef[] }
  bounds?: { x: number, y: number, width: number, height: number }
  tokens?: DesignToken[]              // 见第 7 节
  interactions?: Array<{ trigger: string, action: string, destinationNodeId?: string, evidence: EvidenceRef[] }>
  children: DesignIntentNode[]
  evidence: EvidenceRef[]
}

d2c ingest --input button.json --adapter figma-mcp --document-id demo-file --out .d2c/design-intent.json

function normalizationAction(node): { action: 'keep' | 'flatten' | 'drop', rule: string, confidence: number } {
  const name = node.name?.trim() ?? ''
  const children = node.children ?? []
  const hasIdentity = Boolean(node.componentKey || node.mainComponent?.key || node.componentSetKey)
  const hasContent = typeof node.characters === 'string' && node.characters.length > 0
  const hasInteraction = Boolean(node.reactions?.length || node.prototypeInteractions?.length)

  // 1. 装饰叶子才 drop 五个条件同时满足 少一个都不行
  const decorativeName = /^(?:background|divider|decoration|shadow|line)(?:\s|$)/i.test(name)
  if (!hasIdentity && !hasContent && !hasInteraction && !children.length && decorativeName)
    return { action: 'drop', rule: 'explicit-decorative-leaf', confidence: 0.98 }

  // 2. 匿名包裹 Group 12 / Frame 1000011563 这类名字 自己没有身份没有文字
  const isAnonymousWrapper = !hasIdentity && !hasContent && !hasInteraction && children.length
    && /^(?:group|frame)\s*\d*$/i.test(name)
  if (isAnonymousWrapper) {
    // 压扁之前先看形状 数字名 Frame 里经常住着真按钮 见第 4 节
    const structural = inferStructuralRole(node)
    if (structural && ['button', 'input', 'media', 'dialog'].includes(structural.role))
      return { action: 'keep', rule: `${structural.rule}+pre-flatten`, confidence: structural.confidence }
    return { action: 'flatten', rule: 'anonymous-structural-wrapper', confidence: 0.95 }
  }

  // 3. 表格预检 必须在子节点被 flatten 之前用原始树判断 见 4.2
  if (isTableAreaShape(node))
    return { action: 'keep', rule: 'role-inference:structure:table+header+pre-flatten', confidence: 0.65 }

  // 4. 其余全部 keep 有组件身份的置信度 1 没有的 0.7 一样留下
  return hasIdentity
    ? { action: 'keep', rule: 'semantic-component-identity', confidence: 1 }
    : { action: 'keep', rule: 'preserve-uncertain-node', confidence: 0.7 }
}

interface NormalizationTrace {
  nodeId: string
  action: 'keep' | 'flatten' | 'drop'
  rule: string                        // 上面那些规则名 排查时直接搜
  confidence: number
  mappedNodeIds?: string[]            // 只有 flatten 有 记上浮的子节点 id
  evidence: EvidenceRef[]
}

Frame 88                            表区域根
├── 币种 / 年化 / 期限 / 操作         4 个 TEXT
├── Frame 91 / Frame 92 / Frame 93   同形行容器 343 x 48 纵向排列

const chineseAliases = Object.entries(CHINESE_ROLE_ALIASES).sort((a, b) => b[0].length - a[0].length)
for (const [alias, role] of chineseAliases) {
  if (name.includes(alias)) return { role, confidence: 0.85, rule: 'role-inference:name-zh' }
}

type LayoutRelation =
  | { kind: 'containment', parentId: string, childId: string }
  | { kind: 'order', parentId: string, childIds: string[] }
  | { kind: 'axis', nodeId: string, value: 'row' | 'column' | 'grid' | UnresolvedFact }
  | { kind: 'alignment', nodeId: string, axis: 'main' | 'cross', value: 'start' | 'center' | 'end' | 'space-between' | /* ... */ }
  | { kind: 'gap', nodeId: string, value: number | UnresolvedFact }
  | { kind: 'padding', nodeId: string, value: { top: number, right: number, bottom: number, left: number } }
  | { kind: 'sizing', nodeId: string, axis: 'horizontal' | 'vertical', mode: 'fixed' | 'hug' | 'fill' }
  | { kind: 'grid-tracks' | 'wrap' | 'overflow' | 'positioning', /* ... */ }
// 每条 relation 还带 evidence 上面省略了

function addLayoutRelations(node, id, children, evidence, relations) {
  // 有子节点就写 order 顺序就是 children 数组顺序
  if (children.length)
    relations.push({ kind: 'order', parentId: id, childIds: children.map(c => c.id), evidence })
  // auto-layout 主轴 HORIZONTAL → row / VERTICAL → column / GRID → grid
  const axis = { HORIZONTAL: 'row', VERTICAL: 'column', GRID: 'grid' }[node.layoutMode]
  if (axis) relations.push({ kind: 'axis', nodeId: id, value: axis, evidence })
  // 对齐 MIN → start / CENTER → center / MAX → end / SPACE_BETWEEN → space-between 主轴交叉轴各一条
  if (typeof node.itemSpacing === 'number')
    relations.push({ kind: 'gap', nodeId: id, value: node.itemSpacing, evidence })
  // padding 四边齐了才写一条 缺一边整条不写 不写半吊子数字
  if ([node.paddingTop, node.paddingRight, node.paddingBottom, node.paddingLeft].every(v => typeof v === 'number'))
    relations.push({ kind: 'padding', nodeId: id, value: { top: node.paddingTop, right: node.paddingRight, bottom: node.paddingBottom, left: node.paddingLeft }, evidence })
  // sizing：layoutSizingHorizontal / Vertical 的 FIXED / HUG / FILL 两个轴各一条
  // grid 只知道行列数 track 统一写 1fr / auto
  // layoutWrap → wrap  clipsContent → overflow  positioning === 'ABSOLUTE' → positioning
}

interface DesignToken {
  kind: 'color' | 'typography' | 'spacing' | 'radius' | 'shadow' | 'opacity' | 'other'
  property: string                    // Figma 里绑定变量的属性名 比如 fills
  variableId?: string                 // VariableID:xxx
  evidence: EvidenceRef[]
}
// kind 按属性名猜：color|fill|stroke → color  font|text → typography
// padding|gap|spacing → spacing  radius → radius  shadow|effect → shadow  猜不出落 other

const SHAPE_NODE_TYPES = new Set(['FRAME', 'INSTANCE', 'RECTANGLE', 'VECTOR', 'LINE', 'ELLIPSE', 'POLYGON', 'STAR'])

// 只报 key 缺失 不报值为 0 或空数组
// Figma 数据源里这些 key 必然存在 缺 key 只可能是 adapter 序列化时丢了
function flagMissingAdapterFields(node, id, evidence, context) {
  const missing: string[] = []
  // 开了 auto-layout 的 FRAME / INSTANCE 必须有 itemSpacing 和四边 padding
  if ((node.type === 'FRAME' || node.type === 'INSTANCE') && node.layoutMode && node.layoutMode !== 'NONE') {
    if (typeof node.itemSpacing !== 'number') missing.push('itemSpacing')
    for (const key of ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'])
      if (typeof node[key] !== 'number') missing.push(key)
  }
  if (node.type === 'TEXT' && typeof node.fontSize !== 'number') missing.push('fontSize')
  // 可见的形状节点必须有 fills 数组 空数组也算有
  if (SHAPE_NODE_TYPES.has(node.type) && node.visible !== false && !Array.isArray(node.fills)) missing.push('fills')
  if (missing.length)
    context.unresolved.push(unresolvedFact('adapter-field-missing',
      `Node ${id} (${node.type}) is missing expected adapter fields: ${missing.join(', ')}. Re-dump the design with a single complete serialization pass.`, evidence))
}

{
  "schemaVersion": 2,
  "kind": "design-intent",
  "id": "design:demo-file:1:4",          // Group 12 被 flatten 根直接变成 Frame 1000011563
  "source": {
    "adapter": "figma-mcp", "documentId": "demo-file",
    "fingerprint": "3f9c…e21a",          // 整份输入 JSON 的 sha256
    "evidence": [{ "source": "figma-mcp", "locator": "figma://demo-file/document", "extractorVersion": "2.0.0", "fingerprint": "3f9c…e21a", "confidence": 1 }]
  },
  "roots": [{
    "id": "1:4", "name": "Frame 1000011563", "nodeType": "frame",
    "role": "button",                    // 靠形状推出来的 置信度 0.6 在 trace 里
    "visible": true,
    "bounds": { "x": 16, "y": 640, "width": 343, "height": 44 },
    "tokens": [], "interactions": [],
    "children": [{
      "id": "1:5", "name": "确认", "nodeType": "text", "role": "display", "visible": true,
      "text": { "characters": "确认", "evidence": [/* figma://demo-file/1:5 */] },
      "bounds": { "x": 165, "y": 652, "width": 45, "height": 20 },
      "tokens": [{ "kind": "color", "property": "fills", "variableId": "VariableID:12:34", "evidence": [/* 同上 */] }],
      "interactions": [], "children": [],
      "evidence": [/* figma://demo-file/1:5 */]
    }],
    "evidence": [/* figma://demo-file/1:4 */]
  }],
  "normalization": [
    // 子节点先写 父节点后写
    { "nodeId": "1:3", "action": "drop",    "rule": "explicit-decorative-leaf",                    "confidence": 0.98 },
    { "nodeId": "1:5", "action": "keep",    "rule": "preserve-uncertain-node",                     "confidence": 0.7 },
    { "nodeId": "1:5", "action": "keep",    "rule": "role-inference:type",                         "confidence": 0.8 },
    { "nodeId": "1:4", "action": "keep",    "rule": "role-inference:structure:button+pre-flatten", "confidence": 0.6 },
    { "nodeId": "1:4", "action": "keep",    "rule": "role-inference:structure:button",             "confidence": 0.6 },
    { "nodeId": "1:2", "action": "flatten", "rule": "anonymous-structural-wrapper", "mappedNodeIds": ["1:4"], "confidence": 0.95 }
  ],
  "layout": {
    "nodes": [{ "id": "1:5", "label": "确认" }, { "id": "1:4", "label": "Frame 1000011563" }],
    "relations": [
      { "kind": "containment", "parentId": "1:4", "childId": "1:5" },
      { "kind": "order",       "parentId": "1:4", "childIds": ["1:5"] }
      // 没有 axis / gap / padding 因为原始节点没开 auto-layout ingest 不从坐标反推
    ],
    "unresolved": []
  },
  "unresolved": [{
    "kind": "unresolved", "reason": "adapter-field-missing",
    "detail": "Node 1:5 (TEXT) is missing expected adapter fields: fontSize. Re-dump the design with a single complete serialization pass.",
    "evidence": [/* figma://demo-file/1:5 */]
  }],
  "evidence": [/* 同 source.evidence */]
}