基于 FigmaMCP 的 D2C 工具(九): 我收紧过的规则，以及 Agent/MCP 怎么接进来

function skeletonLayoutObligations(designNode, usageNode, design, usage): ProofObligation[] {
  // 设计侧对这个节点没有布局事实 → 没什么可证 不产出义务
  // 收紧的是"有意图却假装无事" 不是凡组件必 runtime
  if (layoutFactCount(design.layout, designNode.id) === 0)
    return []
  // 设计有布局意图 但 usage 布局图是空的
  // 旧行为：这里也 return [] 报表上等于通过
  // 新行为：落一条 unknown 要求第七篇那套 runtime 补齐
  if (layoutFactCount(usage.layout, usageNode.id) === 0) {
    return [{
      id: `skeleton:${designNode.id}`,
      category: 'layout',
      phase: 'static',
      outcome: 'unknown',
      unresolved: unresolvedFact(
        'runtime-required',
        `Skeleton layout proof requires source-side layout facts; the usage layout graph has none for node ${usageNode.id}.`,
        usage.evidence,
      ),
      evidence: usageNode.evidence,
    }]
  }
  // 两边都有事实 → 正常走 skeleton 等价证明
  const results = proveSkeletonEquivalence({
    nodeMapping: { [designNode.id]: usageNode.id },
    designNodes: [designNode],
    usageNodes: [usageNode],
    designGraph: design.layout,
    usageGraph: usage.layout,
  })
  return skeletonProofToObligations(results)
}

if (operation.kind === 'fill-slot') {
  // 字面量精确匹配 或 default 槽下有非 template 子节点 → pass
  if (node.slots.some(slot => slot.name.kind === 'literal' && slot.name.value === operation.slot)
    || (operation.slot === 'default' && node.children.some(child => child.nodeKind !== 'template'))) {
    return pass(`structure:slot:${operation.slot}`, 'structure', operation.contractEvidence)
  }
  // 有动态 slot 名 → 旧行为直接 pass 新行为落 unknown 交给 runtime
  const dynamicSlot = node.slots.find(slot => slot.name.kind !== 'literal')
  if (dynamicSlot) {
    const fact = unresolvedFact(
      'runtime-required',
      `A dynamic slot name may fill slot ${operation.slot}; runtime proof is required.`,
      dynamicSlot.evidence,
    )
    return unknown(`structure:slot:${operation.slot}`, 'structure', fact)
  }
  // 既没字面量匹配 也没动态槽 → 还是 fail 这一条没变
  return fail(`structure:slot:${operation.slot}`, 'structure', `Slot ${operation.slot} is not filled.`, operation.contractEvidence)
}

// buildBindingPlan 里对每个映射到的 prop 做的判断 精简
for (const [name, value] of mapped) {
  const prop = context.contract.props.find(item => item.name === name)
  if (!prop) {
    // 组件根本没这个 prop → fail 这是硬约束
    constraints.push(fail(`contract:prop:${name}`, 'contract', `Component ${context.contract.id} has no declared prop ${name}.`, context.evidence))
    continue
  }
  const proof = bindingProof(`contract:prop-value:${name}`, value, prop, context.evidence)
  if (proof.outcome === 'fail') {
    // 值不在类型或 validator 范围内 → fail
    constraints.push(fail(`contract:prop-value:${name}`, 'contract', `Binding for ${name} is outside the declared type or validator.`, prop.evidence, prop.type, value))
    continue
  }
  // 收紧点：来源是 provided 且没有 recipe 声明 → unknown 不进 operations
  if (provenance.get(name) === 'provided' && proof.outcome === 'pass' && !providedBindingDeclared(context, name, value)) {
    const fact = unresolvedFact(
      'undeclared-provided-binding',
      `Provided binding ${name} is not declared by an extension recipe for ${context.contract.id}; human review is required.`,
      context.evidence,
    )
    unresolved.push(fact)
    constraints.push(unknown(`contract:provided-binding:${name}`, 'contract', fact))
    continue
  }
  operations.push({ kind: 'set-prop', prop: name, value, designEvidence, contractEvidence: prop.evidence, source: provenance.get(name) })
  if (proof.outcome === 'pass')
    constraints.push(pass(`contract:prop:${name}`, 'contract', prop.evidence))
}

// 声明与否 就是在 scope 内找一条 set-prop 的 recipe
// findRecipe 里会顺带检查 constraints：recipe 对这个 prop 列了枚举 值就必须命中其中一个
function providedBindingDeclared(context, name, value): boolean {
  return findRecipe(context.contract.extensionRecipes, { kind: 'set-prop', target: name, value }, context.scope) !== undefined
}

{
  "verdict": "needs-review",
  "target": "input",
  "candidates": [
    {
      "componentId": "input",
      "outcome": "unknown",
      "constraints": [
        { "id": "contract:prop:placeholder", "outcome": "pass" },
        {
          "id": "contract:provided-binding:resize",
          "category": "contract",
          "outcome": "unknown",
          "unresolved": {
            "kind": "unresolved",
            "reason": "undeclared-provided-binding",
            "detail": "Provided binding resize is not declared by an extension recipe for input; human review is required."
          }
        }
      ],
      "unsatisfiedCore": []
    }
  ],
  "unresolved": [
    { "kind": "unresolved", "reason": "undeclared-provided-binding", "detail": "Provided binding resize is not declared by an extension recipe for input; human review is required." }
  ]
}

# catalog/overrides/input.yaml 精简
schemaVersion: 2
kind: component-overlay
id: input
extensionRecipes:
  - id: curated-provided-bindings
    operations:
      - kind: set-prop
        targets:
          - resize
        # 带枚举约束 塞别的值照样 undeclared-provided-binding
        constraints:
          resize:
            - kind: literal
              value: horizontal
            - kind: literal
              value: vertical
    scopes:
      - '**'
autoMatch:
  eligible: true
  reviewed: true

# 对照一：不带 recipe 时 应出现 undeclared-provided-binding
d2c decide --input .d2c/design/settings.json --scope app/pages/settings \
  --bindings bindings.json --out /tmp/without-recipe.json
d2c explain --input /tmp/without-recipe.json
# "unresolved": [{ "reason": "undeclared-provided-binding", ... }]

# 对照二：补上 recipe 重新 build 后 同一输入应进 BindingPlan
d2c catalog build
d2c decide --input .d2c/design/settings.json --scope app/pages/settings \
  --bindings bindings.json --out /tmp/with-recipe.json
d2c explain --input /tmp/with-recipe.json
# "bindings": [{ "kind": "set-prop", "prop": "resize", "source": "provided", ... }]

export const MCP_TOOL_NAMES = [
  'd2c_catalog_build',
  'd2c_catalog_check',
  'd2c_ingest_figma_link',
  'd2c_ingest',
  'd2c_decide',
  'd2c_verify',
  'd2c_explain',
  'd2c_evolve',
  'd2c_search_catalog',
  'd2c_log_decision',
  'd2c_review_decision',
] as const

// 每个 handler 只是转发 不解析结果 不加默认值 不改字段
export function createMcpHandlers(service = new D2CService()) {
  return {
    catalogBuild: (args = {}) => service.catalogBuild(args),
    catalogCheck: () => service.catalogCheck(),
    ingestFigmaLink: (args: { input: unknown, write?: boolean }) => service.ingestFigmaLink(args),
    ingest: (args: Parameters<D2CService['ingest']>[0]) => service.ingest(args),
    decide: (args: Parameters<D2CService['decide']>[0]) => service.decide(args),
    verifyStatic: (args: Parameters<D2CService['verifyStatic']>[0]) => service.verifyStatic(args),
    verifyRuntime: (args: Parameters<D2CService['verifyRuntime']>[0]) => service.verifyRuntime(args),
    explain: (args: { input: unknown }) => service.explain(args.input),
    evolve: (args = {}) => service.evolve(args),
    searchCatalog: (args = {}) => service.searchCatalog(args),
    logDecision: (args: { decision: unknown }) => service.logDecision(args.decision),
    reviewDecision: (args: { file: string, status: 'approved' | 'rejected', reviewer: string }) => service.reviewDecision(args),
  }
}

function register(server: McpServer, name: string, description: string, inputSchema, handler) {
  server.registerTool(name, { description, inputSchema }, async (args) => {
    try {
      // 返回值原样 JSON 化 不做任何 "友好化"
      return jsonResult(await handler(args))
    }
    catch (error) {
      // schema 校验失败 / 文件不存在 / 组件不在 catalog 都走这里
      return errorResult(error)
    }
  })
}

export function jsonResult(data: unknown) {
  return { content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] }
}

export function errorResult(error: unknown) {
  return {
    content: [{ type: 'text' as const, text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }) }],
    isError: true as const,
  }
}

{
  "design": { "schemaVersion": 2, "kind": "design-intent", "id": "design:settings", "nodes": ["..."], "layout": { "relations": ["..."] } },
  "taskId": "settings-submit",
  "scope": "app/pages/settings",
  "designNodeId": "12:300",
  "providedBindings": {
    "resize": { "kind": "literal", "value": "vertical" }
  },
  "candidateUniverseComplete": true,
  "writePath": ".d2c/decisions/settings-submit.json"
}

{
  "schemaVersion": 2,
  "kind": "decision",
  "id": "decision:settings-submit:12:300",
  "taskId": "settings-submit",
  "designIntentId": "design:settings",
  "designNodeId": "12:300",
  "fingerprints": { "extractor": "3c1f...", "catalog": "a9e2...", "design": "77b0..." },
  "candidateUniverse": { "scope": "app/pages/settings", "status": "complete", "fingerprint": "b4d1..." },
  "verdict": "reuse",
  "target": "input",
  "candidates": [
    {
      "componentId": "input",
      "retrieval": { "rank": 0, "sources": ["identity-link"] },
      "outcome": "satisfiable",
      "constraints": [
        { "id": "contract:prop:placeholder", "category": "contract", "outcome": "pass" },
        { "id": "contract:prop:resize", "category": "contract", "outcome": "pass" }
      ],
      "unsatisfiedCore": [],
      "bindingPlan": { "componentId": "input", "operations": ["..."] }
    }
  ],
  "bindingPlan": {
    "componentId": "input",
    "operations": [
      { "kind": "set-prop", "prop": "placeholder", "value": { "kind": "literal", "value": "请输入" }, "source": "design" },
      { "kind": "set-prop", "prop": "resize", "value": { "kind": "literal", "value": "vertical" }, "source": "provided" }
    ]
  },
  "unresolved": [],
  "review": { "status": "unreviewed" },
  "createdAt": "2026-09-01T02:14:33.000Z"
}

{
  "mode": "static",
  "decision": { "schemaVersion": 2, "kind": "decision", "id": "decision:settings-submit:12:300", "...": "..." },
  "design": { "schemaVersion": 2, "kind": "design-intent", "...": "..." },
  "sourceFile": "app/pages/settings/index.vue",
  "writePath": ".d2c/verify/settings-submit.static.json"
}

// Agent 编排层 只有流程控制 没有裁决逻辑
async function runTask(task: { taskId: string, scope: string, figmaNode: unknown }) {
  const check = await mcp.call('d2c_catalog_check', {})
  if (check.status !== 'pass')
    return stop('catalog 不可用 先修 overrides 或重新 build', check)

  const design = await mcp.call('d2c_ingest', { input: task.figmaNode, adapter: 'figma-mcp' })
  // NormalizationTrace 和 unresolved 要看 不能跳过
  if (design.unresolved.length)
    report('ingest 有未解析事实', design.unresolved)

  const decision = await mcp.call('d2c_decide', { design, taskId: task.taskId, scope: task.scope })
  if (decision.verdict === 'needs-review') {
    // 停下 把 obligation id 和 reason 原样列给人 不要自己改 verdict
    return stop('needs-review', decision.unresolved.map(fact => ({ reason: fact.reason, detail: fact.detail })))
  }
  if (decision.verdict === 'new')
    return stop('new: 候选全部 unsatisfiable 交给人决定是否新建组件', decision.candidates)

  // reuse / extend：只按 bindingPlan.operations 生成代码
  const sourceFile = await generateVue(decision.bindingPlan)

  let report = await mcp.call('d2c_verify', { mode: 'static', decision, design, sourceFile })
  const needsRuntime = report.obligations.some(o => o.outcome === 'unknown' && o.unresolved?.reason === 'runtime-required')
  if (needsRuntime) {
    // 缺 scenario 就停 不要在没有 scenario 的情况下宣称通过
    const scenario = await findOrDraftScenario(decision.designNodeId)
    if (!scenario)
      return stop('runtime-required 但没有 RuntimeScenario', report.obligations)
    report = await mcp.call('d2c_verify', { mode: 'runtime', decision, design, scenario, baseURL, sourceFingerprint: fingerprintOf(sourceFile) })
  }

  if (report.status !== 'pass') {
    const explanation = await mcp.call('d2c_explain', { input: report })
    return stop(`verify ${report.status}`, explanation.failed.concat(explanation.unknown))
  }
  // 到这里 Agent 的活干完了 log-decision 和 review 是人批准之后的事
  return done({ decision, report })
}

private parseDecision(value: unknown): DecisionRecord {
  if ((value as { schemaVersion?: unknown })?.schemaVersion !== 2)
    throw new Error('D2C v1 DecisionRecord is unsupported. Run `d2c decide` again.')
  // strict 模式 多一个字段都不行
  return DecisionRecordSchema.parse(value)
}

export const DecisionRecordSchema = z.object({ /* ... */ }).strict().superRefine((decision, ctx) => {
  const selected = decision.target ? decision.candidates.find(c => c.componentId === decision.target) : undefined

  if (decision.verdict === 'new') {
    // new 要求候选全集完整 且每个候选都是可解释的 unsatisfiable
    if (decision.candidateUniverse.status !== 'complete' || decision.candidates.length === 0 || decision.candidates.some(c => c.outcome !== 'unsatisfiable'))
      ctx.addIssue({ path: ['verdict'], message: 'New requires a complete universe and explainable unsatisfiability for every candidate.' })
    if (decision.target || decision.bindingPlan)
      ctx.addIssue({ path: ['target'], message: 'New decisions cannot select an existing component.' })
  }

  if (decision.verdict === 'reuse' || decision.verdict === 'extend') {
    // 把 needs-review 手改成 reuse：selected.outcome 还是 unknown 这里直接不过
    if (!selected || selected.outcome !== 'satisfiable' || !decision.bindingPlan || decision.bindingPlan.componentId !== decision.target) {
      ctx.addIssue({ path: ['target'], message: 'Reuse and extend require a satisfiable selected candidate and matching binding plan.' })
      return
    }
    const extensionOperations = decision.bindingPlan.operations.filter(op => op.extensionRecipeId)
    if (decision.verdict === 'reuse' && extensionOperations.length > 0)
      ctx.addIssue({ path: ['bindingPlan'], message: 'Reuse cannot apply extension-recipe operations.' })
    if (decision.verdict === 'extend' && extensionOperations.length === 0)
      ctx.addIssue({ path: ['bindingPlan'], message: 'Extend requires at least one declared extension-recipe operation.' })
  }

  // needs-review 必须有 unresolved 或 unknown 候选 不能凭空 needs-review
  if (decision.verdict === 'needs-review' && decision.unresolved.length === 0 && !decision.candidates.some(c => c.outcome === 'unknown'))
    ctx.addIssue({ path: ['unresolved'], message: 'Needs-review requires unresolved evidence.' })
})

reviewDecision(options: { file: string, status: 'approved' | 'rejected', reviewer: string }) {
  const lines = readFileSync(this.resolvePath(options.file, true), 'utf8').split('\n')
  const parsedLines = lines.map((line) => {
    if (!line.trim())
      return line
    // 先 parse 原记录 手改过的记录在这里就过不去
    const decision = DecisionRecordSchema.parse(JSON.parse(line))
    // 只写 review 三个字段 review 不参与 decision 指纹
    decision.review = { status: options.status, reviewer: options.reviewer, reviewedAt: this.now() }
    return JSON.stringify(decision)
  })
  writeFileSync(file, parsedLines.join('\n'))
  return { schemaVersion: 2, kind: 'decision-review-result', file, status: options.status, reviewer: options.reviewer, recordsReviewed: reviewed.length }
}