基于 FigmaMCP 的 D2C 工具(八): 账本与 evolve——只提案，不自动改库

tools/d2c/
├── catalog/
│   ├── generated/          # 编译导出的契约 机器生成
│   ├── overrides/          # 人工覆盖 一个组件一个 yaml
│   ├── links/              # Figma 链接
│   └── snapshot.json       # 三层合并后的只读 CatalogSnapshot
└── decision-log/
    └── v2/
        ├── 2026-07.jsonl   # 按月一个文件 只追加
        ├── 2026-08.jsonl
        └── 2026-09.jsonl

.d2c/                       # gitignore 工作区草稿
├── decisions/              # decide 的输出 一条一个 json
└── verify/                 # verify 的输出 VerifyReport

{
  "schemaVersion": 2,
  "kind": "decision",
  "id": "decision:settings-form:12:401",
  "taskId": "settings-form",
  "designIntentId": "design:settings-form:12:400",
  "designNodeId": "12:401",
  "fingerprints": {
    "extractor": "557adf3c...20c6d0",
    "catalog": "f00a5404...23657e",
    "design": "ef855063...7f9ad",
    "source": "9f2c11ab...0e1a0"
  },
  "candidateUniverse": {
    "scope": "app/pages/settings/index.vue",
    "status": "complete",
    "fingerprint": "f00a5404...23657e",
    "evidence": [
      { "source": "catalog-builder", "locator": "tools/d2c/catalog", "extractorVersion": "2.0.0", "fingerprint": "78a1fef5...792f3c", "confidence": 1 }
    ]
  },
  "candidates": [
    {
      "componentId": "input",
      "retrieval": { "rank": 0, "sources": ["identity-link"] },
      "outcome": "satisfiable",
      "constraints": [
        { "id": "boundary:hazards", "category": "boundary", "phase": "static", "outcome": "pass" },
        { "id": "contract:prop:resize", "category": "contract", "phase": "static", "outcome": "pass" }
      ],
      "unsatisfiedCore": [],
      "bindingPlan": {
        "schemaVersion": 2,
        "kind": "binding-plan",
        "componentId": "input",
        "operations": [
          {
            "kind": "set-prop",
            "prop": "resize",
            "value": { "kind": "literal", "value": "none" },
            "extensionRecipeId": "resize-control",
            "source": "provided"
          }
        ],
        "unresolved": []
      }
    },
    {
      "componentId": "textarea",
      "retrieval": { "rank": 1, "sources": ["structure-index"] },
      "outcome": "unsatisfiable",
      "unsatisfiedCore": ["contract:slot:prefix"],
      "compact": true
    }
  ],
  "verdict": "extend",
  "target": "input",
  "bindingPlan": { "componentId": "input", "operations": ["同上 略"] },
  "unresolved": [],
  "review": {
    "status": "approved",
    "reviewer": "skelanimals",
    "reviewedAt": "2026-09-12T03:21:07.000Z"
  },
  "createdAt": "2026-09-12T02:58:44.000Z"
}

d2c log-decision --input .d2c/decisions/settings-form.12:401.json

{
  "schemaVersion": 2,
  "kind": "decision-log-result",
  "decisionId": "decision:settings-form:12:401",
  "path": "tools/d2c/decision-log/v2/2026-09.jsonl"
}

logDecision(input: unknown) {
  // 先过 schema 不合法的记录进不了账本
  const decision = DecisionRecordSchema.parse(input)
  const directory = join(this.projectRoot, 'tools/d2c/decision-log/v2')
  mkdirSync(directory, { recursive: true })
  // 按 createdAt 的年月定文件 不按当前时间 补录旧记录也能落到正确的月份
  const month = decision.createdAt.slice(0, 7)
  const file = join(directory, `${month}.jsonl`)
  // appendFileSync 只追加 这里没有任何读旧内容再写回的逻辑
  appendFileSync(file, `${JSON.stringify(decision)}\n`)
  return { schemaVersion: 2, kind: 'decision-log-result', decisionId: decision.id, path: file }
}

d2c decision review .d2c/decisions/settings-form.12:401.json --status approved --reviewer skelanimals

{
  "schemaVersion": 2,
  "kind": "decision-review-result",
  "file": ".d2c/decisions/settings-form.12:401.json",
  "status": "approved",
  "reviewer": "skelanimals",
  "recordsReviewed": 1
}

export const FingerprintSetSchema = z.object({
  extractor: z.string().min(1),   // 抽取器代码本身的哈希
  catalog: z.string().min(1),     // CatalogSnapshot 的整体哈希
  design: z.string().min(1),      // DesignIntentIR.source 的哈希
  source: z.string().min(1).optional(),  // 被验证源码的哈希 decide 时可能还没有
}).strict()

fingerprints: {
  extractor: catalog.fingerprints.extractor,
  catalog: catalog.fingerprint,
  design: design.source.fingerprint,
  source: options.sourceFingerprint,   // 可选
},

const fingerprints = {
  extractor: catalogExtractorFingerprint(projectRoot),
  inventory: catalogInventoryFingerprint(inventory),
  generated: generatedFingerprint,
  overrides: overridesFingerprint,   // overrides 目录下所有 yaml 按路径排序后逐个哈希
  links: linksFingerprint,
  sources: sourcesFingerprint,
}
// 任何一层变了 整体指纹都变
const fingerprint = fingerprintContent(stableJson({ fingerprints, contracts: compiledContracts, links }))

export function fingerprintFiles(paths: string[], root = process.cwd()): string {
  const entries = paths
    .map(path => ({ path: relative(root, resolve(path)).replaceAll('\\', '/'), content: readFileSync(path) }))
    .sort((a, b) => a.path.localeCompare(b.path))   // 排序 保证遍历顺序不影响结果
  const hash = createHash('sha256')
  for (const entry of entries) {
    hash.update(entry.path)
    hash.update('\0')
    hash.update(entry.content)
    hash.update('\0')
  }
  return hash.digest('hex')
}

obligations.push(fingerprintProof('extractor', decision.fingerprints.extractor, catalog.fingerprints.extractor, evidence))
obligations.push(fingerprintProof('design', decision.fingerprints.design, design.source.fingerprint, evidence))
obligations.push(fingerprintProof('catalog', decision.fingerprints.catalog, catalog.fingerprint, evidence))
obligations.push(fingerprintProof('source', decision.fingerprints.source, usage.source.fingerprint, evidence))

function fingerprintProof(name: string, expected: string | undefined, actual: string, evidence: EvidenceRef[]): ProofObligation {
  // decision 里没有这条指纹 → unknown 理由 stale-fingerprint 不是 fail
  if (!expected) {
    const fact = unresolvedFact('stale-fingerprint', `${name} fingerprint is missing from the decision.`, evidence)
    return unknown(`boundary:fingerprint:${name}`, 'boundary', fact)
  }
  // 有但对不上 → fail 报告整单 rejected
  return expected === actual
    ? pass(`boundary:fingerprint:${name}`, 'boundary', evidence)
    : fail(`boundary:fingerprint:${name}`, 'boundary', `${name} fingerprint is stale.`, evidence, expected, actual)
}

review: z.object({
  status: z.enum(['unreviewed', 'approved', 'rejected']),
  reviewer: z.string().min(1).optional(),
  reviewedAt: z.string().datetime().optional(),
}).strict().optional(),

const reviewed = decisions.filter(decision => decision.review?.status === 'approved' && decision.target)

export const EvolutionProposalSchema = z.object({
  schemaVersion: z.literal(2),
  kind: z.literal('evolution-proposal'),
  id: z.string().min(1),                    // proposal:<kind>:<componentId>
  componentId: z.string().min(1),
  // 枚举留了四种 目前只有前后两种有生产者 semantic-role 和 extension-recipe 还没写
  proposalKind: z.enum(['retrieval-prior', 'semantic-role', 'hazard', 'extension-recipe']),
  samples: z.object({
    supporting: z.array(z.string().min(1)),  // 成功样本的 decision id
    failing: z.array(z.string().min(1)),     // 失败样本的 decision id
  }).strict(),
  statistics: z.object({
    successes: z.number().int().nonnegative(),
    failures: z.number().int().nonnegative(),
    successRate: z.number().min(0).max(1),
  }).strict(),
  patch: z.record(z.unknown()),             // 建议改动的形状 不是能直接 apply 的 diff
  requiredRegressionTests: z.array(z.string().min(1)).min(1),  // 至少一条 空数组过不了 schema
  evidence: z.array(EvidenceRefSchema).min(1),
  createdAt: z.string().datetime(),
}).strict()

export function proposeEvolution(decisions: DecisionRecord[], reports: VerifyReport[], createdAt: string): EvolutionProposal[] {
  // 报告按 decisionId 分组 一条 decision 可能有多份报告 静态一份 运行时几份
  const reportsByDecision = Map.groupBy(reports, report => report.decisionId)

  // 1. 过滤 只留人盖过 approved 且落到了具体组件的
  const reviewed = decisions.filter(decision => decision.review?.status === 'approved' && decision.target)

  // 2. 按目标组件分组 提案的粒度是组件 不是设计节点
  const grouped = Map.groupBy(reviewed, decision => decision.target!)

  const proposals: EvolutionProposal[] = []
  for (const [componentId, records] of grouped) {
    // 3. 看每条 decision 关联报告的结局
    const successes = records.filter(record => reportOutcome(reportsByDecision.get(record.id)) === 'accepted')
    const failures = records.filter(record => reportOutcome(reportsByDecision.get(record.id)) === 'rejected')

    // 4. 样本不够就不说话 成功少于 2 且没有失败 → 跳过
    if (successes.length < 2 && failures.length === 0)
      continue

    // 5. 证据从决定性的样本里摊平 needs-review 的报告不算证据
    const decisive = [...successes, ...failures]
    const evidence = decisive.flatMap(record => [
      ...record.evidence,
      ...(reportsByDecision.get(record.id) ?? [])
        .filter(report => report.disposition === 'accepted' || report.disposition === 'rejected')
        .flatMap(report => report.evidence),
    ])
    const base = {
      schemaVersion: 2, kind: 'evolution-proposal', componentId,
      samples: { supporting: successes.map(r => r.id), failing: failures.map(r => r.id) },
      statistics: { successes: successes.length, failures: failures.length,
        successRate: decisive.length ? successes.length / decisive.length : 0 },
      evidence, createdAt,
    }

    // 6. 成功 >= 2 → retrieval-prior 建议把 verifiedSupport 抬到成功次数
    if (successes.length >= 2) {
      proposals.push(EvolutionProposalSchema.parse({
        ...base,
        id: `proposal:retrieval-prior:${componentId}`,
        proposalKind: 'retrieval-prior',
        patch: { componentId, verifiedSupport: successes.length },
        requiredRegressionTests: [
          `Add a positive fixture for ${componentId}.`,
          `Add a competing-candidate negative fixture for ${componentId}.`,
          `Add a boundary fixture for ${componentId}.`,
        ],
      }))
    }

    // 7. 失败 > 0 → hazard 把失败的 obligation id 去重后列出来
    if (failures.length > 0) {
      proposals.push(EvolutionProposalSchema.parse({
        ...base,
        id: `proposal:hazard:${componentId}`,
        proposalKind: 'hazard',
        patch: {
          componentId,
          failedObligations: unique(failures.flatMap(record =>
            (reportsByDecision.get(record.id) ?? [])
              .flatMap(report => report.obligations)
              .filter(obligation => obligation.outcome === 'fail')
              .map(obligation => obligation.id))),
        },
        // 每条失败样本一条 要求复现成变异测试
        requiredRegressionTests: failures.map(record => `Reproduce ${record.id} as a failing mutation test.`),
      }))
    }
  }
  return proposals
}

// 一条 decision 的多份报告 任一 rejected 就算失败 有 accepted 且没有 rejected 才算成功
// 全是 needs-review 或者根本没报告 → undefined 不计入任何一侧
function reportOutcome(reports: VerifyReport[] | undefined): 'accepted' | 'rejected' | undefined {
  if (reports?.some(report => report.disposition === 'rejected'))
    return 'rejected'
  if (reports?.some(report => report.disposition === 'accepted'))
    return 'accepted'
}

{
  "schemaVersion": 2,
  "kind": "evolution-proposals",
  "proposals": [
    {
      "schemaVersion": 2,
      "kind": "evolution-proposal",
      "id": "proposal:retrieval-prior:input",
      "componentId": "input",
      "proposalKind": "retrieval-prior",
      "samples": {
        "supporting": ["decision:settings-form:12:401", "decision:profile-form:31:77"],
        "failing": ["decision:search-bar:8:12"]
      },
      "statistics": { "successes": 2, "failures": 1, "successRate": 0.6667 },
      "patch": { "componentId": "input", "verifiedSupport": 2 },
      "requiredRegressionTests": [
        "Add a positive fixture for input.",
        "Add a competing-candidate negative fixture for input.",
        "Add a boundary fixture for input."
      ],
      "evidence": [
        { "source": "catalog-overlay", "locator": "tools/d2c/catalog/overrides/input.yaml", "extractorVersion": "2.0.0", "fingerprint": "a1b14be6...110680", "confidence": 1 },
        { "source": "figma-mcp", "locator": "figma://settings-form/12:401", "extractorVersion": "2.0.0", "fingerprint": "ef855063...7f9ad", "confidence": 1 }
      ],
      "createdAt": "2026-09-18T01:12:00.000Z"
    },
    {
      "schemaVersion": 2,
      "kind": "evolution-proposal",
      "id": "proposal:hazard:input",
      "componentId": "input",
      "proposalKind": "hazard",
      "samples": {
        "supporting": ["decision:settings-form:12:401", "decision:profile-form:31:77"],
        "failing": ["decision:search-bar:8:12"]
      },
      "statistics": { "successes": 2, "failures": 1, "successRate": 0.6667 },
      "patch": {
        "componentId": "input",
        "failedObligations": ["layout:geometry:8:12", "skeleton:8:12"]
      },
      "requiredRegressionTests": [
        "Reproduce decision:search-bar:8:12 as a failing mutation test."
      ],
      "evidence": ["同上 略"],
      "createdAt": "2026-09-18T01:12:00.000Z"
    }
  ]
}

# 默认读账本 decision-log/v2/*.jsonl 和 .d2c/verify/ 下的报告
d2c evolve --out .d2c/proposals/2026-09-18.json

# 调试时可以显式指向草稿 这是逃生口 CI 里不该用
d2c evolve --decisions .d2c/decisions/drafts.json --reports .d2c/verify/reports.json

evolve(options: { decisions?: unknown[], reports?: unknown[], writePath?: string } = {}) {
  // 默认输入是版本化账本 只追加的 jsonl
  // .d2c/decisions/ 是草稿 要读它必须显式传 --decisions
  const decisions = options.decisions
    ? options.decisions.map(value => this.parseDecision(value))
    : this.readJsonl(join(this.projectRoot, 'tools/d2c/decision-log/v2'), DecisionRecordSchema)
  const reports = options.reports
    ? options.reports.map(value => VerifyReportSchema.parse(value))
    : this.readArtifacts(join(this.projectRoot, '.d2c/verify'), VerifyReportSchema)
  const proposals = proposeEvolution(decisions, reports, this.now())
  const result = { schemaVersion: 2, kind: 'evolution-proposals', proposals }
  // 唯一的写操作 写的是提案文件 不是 catalog
  if (options.writePath)
    this.writeJson(options.writePath, result)
  return result
}

schemaVersion: 2
kind: component-overlay
id: input
roles:
  - input
  - text-field
# retrieval-prior 提案接受后 人手写进来 数字来自 statistics.successes
verifiedSupport: 2
hazards:
  # hazard 提案接受后 人手写进来 condition 和 message 是人写的 不是 patch 里抄的
  - id: search-bar-geometry
    severity: review
    scope:
      - 'app/pages/search/**'
    condition: input placed in a fill-width search bar without explicit width
    message: search bar geometry drifted in runtime verify; see decision:search-bar:8:12
extensionRecipes:
  - id: resize-control
    operations:
      - kind: set-prop
        targets:
          - resize
        constraints:
          resize:
            - kind: literal
              value: none
            - kind: literal
              value: both
    scopes:
      - '**'
autoMatch:
  eligible: true
  reviewed: true

d2c catalog build
d2c catalog check

// overlay 有就用 overlay 的 没有就用编译出来的
verifiedSupport: overlay.verifiedSupport ?? contract.verifiedSupport,
hazards: overlay.hazards?.map(hazard => ({ ...hazard, evidence })) ?? contract.hazards,

// 批过次数折进 rankingScore：source 优先级不变，只在 structure-index 内部靠前。
function structureIndexEntry(contract: ComponentContractIR): RetrievedCandidate {
  return {
    componentId: contract.id,
    source: 'structure-index',
    ...(contract.verifiedSupport > 0 ? { rankingScore: contract.verifiedSupport } : {}),
  }
}

function hazardConstraint(context: CandidateContext): ProofObligation {
  // 只有 block 级且 scope 匹配的 hazard 才 fail review / warn 只给人看
  const active = context.contract.hazards.filter(hazard =>
    hazard.severity === 'block' && hazard.scope.some(pattern => matchesScope(context.scope, pattern)))
  return active.length
    ? fail('boundary:hazards', 'boundary', active.map(hazard => hazard.message).join('; '), active.flatMap(hazard => hazard.evidence))
    : pass('boundary:hazards', 'boundary', context.contract.evidence)
}