基于 FigmaMCP 的 D2C 工具(三): catalog——机器出事实，人补判断

{
  "kind": "catalog-search",
  "count": 1,
  "hits": [
    {
      "id": "dialog",
      "name": "Dialog",
      "roles": [],
      "importPath": "components/Dialog.vue",
      "autoMatch": { "eligible": false, "reviewed": false },
      "completeness": "complete"
    }
  ]
}

catalog/
  generated/        # 机器写 每次 build 整目录替换 人不要碰
    dialog.json
    button.json
    ...
  overrides/        # 人写 走 PR
    dialog.yaml
    button.yaml
  links/            # 人写 走 PR
    dialog.yaml
  snapshot.json     # build 产物 运行时唯一读的文件

interface ComponentContractIR {
  schemaVersion: 2
  kind: 'component-contract'
  id: string                          // kebab id 例如 dialog / button
  name: string
  source: {
    kind: 'library' | 'project'       // 组件库还是项目组件
    importPath: string
    files?: string[]                  // 抽取时读过的文件 sources 指纹从这来
    fingerprint: string
  }
  roles: string[]                     // 语义角色 generated 里通常是空的
  structureFamilies: string[]         // 结构签名族 抽取器派生 overlay 可覆盖
  verifiedSupport: number             // 人工批过的次数 只影响排序
  props: Array<{ name: string, type: TypeExpression, required: boolean, default?: BindingValue }>
  models: Array<{ name: string, prop: string, event: string, type: TypeExpression }>   // v-model 对
  events: Array<{ name: string, payload: TypeExpression[] }>
  slots: Array<{ name: string, required: boolean, props: SlotProp[], dynamic: boolean }>
  attrs: { inheritAttrs: boolean | UnresolvedFact, forwarding: AttrForwarding[] }
  coverage: Record<CoverageKey, { status: 'proven' | 'unresolved' | 'not-applicable', unresolved?: UnresolvedFact }>
  hazards: Hazard[]                   // generated 里为空
  extensionRecipes: ExtensionRecipe[] // generated 里为空
  autoMatch: { eligible: boolean, reviewed: boolean }   // generated 里都是 false
  completeness: { status: 'complete' | 'incomplete', unresolved: UnresolvedFact[] }
}

{
  "id": "dialog",
  "name": "Dialog",
  "source": { "kind": "project", "importPath": "components/Dialog.vue", "fingerprint": "5d84dc9e…" },
  "roles": [],
  "structureFamilies": ["dialog"],
  "props": [
    { "name": "modelValue", "type": { "kind": "primitive", "name": "boolean" }, "required": false },
    { "name": "title", "type": { "kind": "primitive", "name": "string" }, "required": false },
    { "name": "width", "type": { "kind": "primitive", "name": "number" }, "required": false, "default": { "kind": "literal", "value": 480 } }
  ],
  "models": [{ "name": "modelValue", "prop": "modelValue", "event": "update:modelValue" }],
  "events": [{ "name": "close", "payload": [] }],
  "slots": [
    { "name": "default", "required": false, "props": [], "dynamic": false },
    { "name": "header", "required": false, "props": [{ "name": "close", "type": { "kind": "function" } }], "dynamic": false },
    { "name": "footer", "required": false, "props": [], "dynamic": false }
  ],
  "hazards": [],
  "extensionRecipes": [],
  "autoMatch": { "eligible": false, "reviewed": false },
  "completeness": { "status": "complete", "unresolved": [] }
}

{
  "id": "legacy-picker",
  "props": [], "models": [], "events": [], "slots": [],
  "coverage": { "props": { "status": "unresolved" }, "slots": { "status": "unresolved" } },
  "autoMatch": { "eligible": false, "reviewed": false },
  "completeness": {
    "status": "incomplete",
    "unresolved": [{ "kind": "unresolved", "reason": "incomplete-component-contract", "detail": "Cannot resolve props type for legacy-picker" }]
  }
}

schemaVersion: 2
kind: component-overlay
id: dialog
roles:
  - dialog
semantics:
  whenToUse:
    - 需要遮罩 + 居中卡片的模态场景
  antiPatterns:
    - 自己写 fixed 遮罩 不用 Dialog
    - 表格单元格里直接嵌 Dialog
  figmaHints:
    - 图层名带 弹窗 / 对话框 / modal
hazards:
  - id: no-dialog-in-table-cell
    severity: block
    scope:
      - '**'
    condition: dialog rendered inside a table cell
    message: 表格单元格里禁止直接嵌 Dialog 会锁滚动
  - id: mobile-needs-review
    severity: review
    scope:
      - 'app/pages/m/**'
    condition: dialog used on mobile routes
    message: 移动端路由用 Dialog 要人看一眼 通常该用 Drawer
extensionRecipes:
  - id: footer-actions
    operations:
      - kind: fill-slot
        targets:
          - footer
      - kind: set-prop
        targets:
          - width
          - showClose
        constraints:
          width:
            - kind: literal
              value: 480
            - kind: literal
              value: 640
    scopes:
      - '**'
autoMatch:
  eligible: true
  reviewed: true

d2c overrides scaffold --component-id dialog

# TODO: fill in curated semantics for dialog.
# Minimal valid overlay; every field below is optional per CatalogOverlaySchema.
schemaVersion: 2
kind: component-overlay
id: dialog
roles: []
autoMatch:
  eligible: false
  reviewed: false

schemaVersion: 2
kind: figma-component-link
componentKey: 16a7aa909691a6e2dc232c8165927714e684f03a
componentSetKey: 3f0c2e…
componentId: button
propertyMappings:
  - figmaProperty: Type
    target:
      kind: prop
      name: type
    values:
      Primary:
        kind: literal
        value: primary
      Default:
        kind: literal
        value: default
  - figmaProperty: Label
    target:
      kind: slot
      name: default

d2c links validate

{
  "kind": "links-validate-report",
  "status": "fail",
  "errors": [
    { "componentId": "button", "message": "Figma property Size targets missing prop size." }
  ]
}

function applyOverlay(contract: ComponentContractIR, overlay: CatalogOverlay): ComponentContractIR {
  // overlay 声明了 coverage 就按人工确认的重算 unresolved 否则沿用 generated 的
  const unresolved = overlay.coverage
    ? recomputeUnresolved(contract, overlay.coverage)
    : contract.completeness.unresolved

  return {
    ...contract,
    aliases: unique([...(contract.aliases ?? []), ...(overlay.aliases ?? [])]),   // 只有 aliases 是合并
    roles: overlay.roles ?? contract.roles,                                       // 其他都是整体替换
    structureFamilies: overlay.structureFamilies ?? contract.structureFamilies,
    hazards: overlay.hazards ?? contract.hazards,
    extensionRecipes: overlay.extensionRecipes ?? contract.extensionRecipes,
    autoMatch: overlay.autoMatch
      ? {
          ...overlay.autoMatch,
          // 人说 eligible 也不算 还要 reviewed 且没有任何 unresolved
          eligible: overlay.autoMatch.eligible && overlay.autoMatch.reviewed && unresolved.length === 0,
        }
      : contract.autoMatch,
    completeness: { status: unresolved.length ? 'incomplete' : 'complete', unresolved },
  }
}

{
  "kind": "catalog-snapshot",
  "fingerprint": "a3f1…",
  "fingerprints": {
    "extractor": "…",   // 抽取器代码本身的哈希 抽取逻辑改了也算变
    "inventory": "…",   // 发现了哪些组件文件
    "generated": "…",   // 合并后契约的哈希
    "overrides": "…",   // overrides 目录所有 yaml 的哈希
    "links": "…",       // links 目录所有 yaml 的哈希
    "sources": "…"      // 契约 source.files 里所有源码文件的哈希
  },
  "contracts": [ "…" ],
  "links": [ "…" ],
  "generatedAt": "2026-…"
}

D2C catalog drift detected:
- curated overlay fingerprints are stale
- component source fingerprints are stale

d2c catalog build

{
  "kind": "catalog-build-report",
  "status": "pass",
  "summary": {
    "fingerprint": "a3f1…",
    "contracts": 212,
    "completeContracts": 187,
    "autoMatchContracts": 41,
    "links": 6,
    "generatedAt": "2026-…"
  },
  "errors": [],
  "written": 213
}

function deriveStructureFamilies(input: {
  identity: string            // kebab id 名称规则在这里匹配
  props: Set<string>
  models: Set<string>         // v-model 的 prop 名
  slots: Set<string>
  events: Set<string>
}): string[] {
  const id = input.identity.toLowerCase()
  const families: string[] = []
  const hasProp = (...names: string[]) => names.some(n => input.props.has(n))
  const hasEvent = (...names: string[]) => names.some(n => input.events.has(n))
  const hasSlot = (...names: string[]) => names.some(n => input.slots.has(n))

  // 名称规则优先 目录名和导出名在组件库里足够可靠 形状规则补充命名不含族词的组件
  if (/modal|dialog/.test(id)
    || (input.models.size > 0 && hasProp('title', 'closeOnClickModal', 'showClose') && hasEvent('close', 'closed')))
    families.push('dialog')

  // 有 click 事件、没有 v-model、也没有别的族的特征 prop → button
  if (hasEvent('click') && input.models.size === 0
    && !hasProp('placement', 'options', 'data', 'columns', 'href') && !hasSlot('reference'))
    families.push('button')

  if (input.models.size > 0 && hasProp('placeholder') && !hasProp('options'))
    families.push('input')

  if (input.props.has('data') && hasProp('columns', 'rowKey'))
    families.push('table')

  // ... drawer / tabs / select / checkbox / switch / tooltip / pagination / card / media 同理
  return families.sort()
}

# 1. 搜到了
d2c_search_catalog { "query": "dialog" }
# → autoMatch: { eligible: false, reviewed: false }  roles: []

# 2. 看一眼全局状态
d2c contracts status
# → { total: 212, reviewed: 41, eligible: 41, incomplete: 25 }

# 3. 跑 decide 拿到 needs-review
d2c decide --input .d2c/design/new-account-dialog.json --scope app/pages/account
# → verdict: needs-review  候选 dialog 的 auto-match 约束 unknown

# 4. 补 overlay
d2c overrides scaffold --component-id dialog
# 编辑 overrides/dialog.yaml 填 roles / autoMatch / hazards / recipe

# 5. build 再 decide
d2c catalog build
d2c decide --input .d2c/design/new-account-dialog.json --scope app/pages/account
# → verdict: reuse