mini-figma-code-connect 0.1.0

package/scripts/figma-mapping/ai-generate.mjs

@@ -0,0 +1,102 @@
+import { execFileSync } from 'node:child_process';
+
+// 引擎自带的格式示例，不依赖任何具体消费方的真实数据——这个 CLI 可能在任何装了
+// mini-figma-code-connect 的项目里跑，不能假设某份 .figma.ts 一定存在。
+const EXAMPLE_TEMPLATE = `import { defineTemplate, code } from 'mini-figma-code-connect'
+
+export default defineTemplate({
+  meta: {
+    url: 'https://www.figma.com/design/FILE_KEY/Design-System?node-id=NODE_ID',
+    source: '../path/to/components/button.tsx',
+    component: 'Button',
+  },
+  id: 'button',
+  match: { componentName: 'Button' },
+
+  render(instance) {
+    const label = instance.getString('Label')
+    const disabled = instance.getBoolean('Disabled')
+    const size = instance.getEnum('Size', { Large: 'large', Medium: 'medium', Small: 'small' })
+
+    return {
+      example: code\`<Button size="\${size}"\${disabled ? code\` disabled\` : ''}>\${label}</Button>\`,
+      imports: ['import { Button } from "@/components/button"'],
+      id: 'button',
+    }
+  },
+})
+`;
+
+function buildPrompt({ schema, candidates, importPaths }) {
+  const candidateBlocks = candidates
+    .map(
+      (c) => `### 候选文件: ${c.relPath}
+\`\`\`
+${c.source}
+\`\`\`
+`,
+    )
+    .join('\n');
+
+  return `你是 Figma Code Connect 映射生成器。任务：判断下面这个 Figma 组件该接到哪个候选代码组件，如果有合适的就生成映射文件内容。
+
+## Figma 组件 schema
+\`\`\`json
+${JSON.stringify(schema, null, 2)}
+\`\`\`
+
+## 候选代码组件（按路径排列，可能一个都不合适）
+${candidateBlocks}
+
+## 目标文件格式（这是一份已有的示例，照这个格式和 accessor API 写，不要用别的格式）
+\`\`\`ts
+${EXAMPLE_TEMPLATE}
+\`\`\`
+
+## import 路径换算规则
+候选文件路径前缀 → 生成文件里 imports 用的 specifier：
+${JSON.stringify(importPaths, null, 2)}
+
+## 要求
+1. 从候选文件里选一个最合适的（组件名、Props 语义都要对得上，不是字符串像不像）。一个都不合适就选 NONE。
+2. Figma 属性名可能是中文、可能跟代码 prop 不是字面一致（比如"状态"里的 disabled/hover/loading 需要拆成 disabled/loading 两个 prop，hover/pressed 是 CSS 状态不是 prop，不能硬塞）。VARIANT 的字典要覆盖 schema 里给的每一个选项，配不上真实值的必须显式留 'TODO' 不要瞎编一个能编译但语义错的值。
+3. 不确定的判断（比如没有精确对应的 variant 值该猜哪个），照样做出选择，但在生成文件顶部注释里明确写出"这是猜的，需要人工确认"，别不声不响。
+4. 严禁调用任何工具/命令，严禁读写文件系统 —— 你现在没有这些权限，只需要基于上面给的信息直接生成文本。
+5. 严禁编造代码里不存在的 prop 名。
+
+## 输出格式（严格遵守，不要输出其它任何文字）
+第一行：\`MATCH: <候选文件的 relPath>\` 或 \`MATCH: NONE\`
+如果 MATCH 不是 NONE，第二行开始是一条分隔线 \`---\`，之后是完整的 .figma.ts 文件内容（不要用 markdown 代码块包裹，直接是可以原样写入文件的 TypeScript 源码）。
+如果 MATCH 是 NONE，第二行开始简短说明为什么没有合适的候选（一两句话）。`;
+}
+
+/** 调本机 claude CLI 无头模式做真判断，禁掉所有工具权限强制纯文本生成，不给它碰文件系统的机会 */
+export function aiGenerateMapping({ schema, candidates, importPaths }) {
+  const prompt = buildPrompt({ schema, candidates, importPaths });
+
+  const raw = execFileSync(
+    'claude',
+    [
+      '-p',
+      prompt,
+      '--output-format',
+      'text',
+      '--disallowedTools',
+      'Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch,Task,NotebookEdit',
+    ],
+    { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 },
+  );
+
+  const firstLineEnd = raw.indexOf('\n');
+  const firstLine = (firstLineEnd === -1 ? raw : raw.slice(0, firstLineEnd)).trim();
+  const rest = firstLineEnd === -1 ? '' : raw.slice(firstLineEnd + 1);
+
+  const m = firstLine.match(/^MATCH:\s*(.+)$/);
+  if (!m || m[1].trim() === 'NONE') {
+    return { matched: false, reason: rest.trim() || firstLine };
+  }
+
+  const relPath = m[1].trim();
+  const content = rest.replace(/^---\s*\n?/, '');
+  return { matched: true, relPath, content };
+}

package/scripts/figma-mapping/index.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { ROOT, readConfig, listCandidateFiles, extractComponentInfo, scoreCandidate, MAPPINGS_DIR } from './lib.mjs';
+import { buildMatchedScaffold, toImportSpecifier } from './scaffold.mjs';
+import { refreshRegistry } from './registry.mjs';
+import { aiGenerateMapping } from './ai-generate.mjs';
+
+const rl = readline.createInterface({ input: stdin, output: stdout });
+const ask = (q) => rl.question(q);
+
+function printHelp() {
+  console.log(`用法:
+  node scripts/figma-mapping/index.mjs <schema.json> [--ai]
+
+schema.json 从插件面板拿：
+  - 单个组件："导出 schema.json"按钮（未映射状态下才有）
+  - 一整批：候选列表里"导出全部 schema.json"按钮，会是一个 schema 数组，脚本挨个跑完
+
+不带 --ai：本地正则打分排候选，你自己挑、自己判断要不要接哪个 prop。
+带 --ai：调本机 claude CLI（无头模式，禁掉所有工具权限）读 schema + 候选源码，直接做真判断、
+        生成完整映射内容，你只需要确认要不要采纳——判断力比正则强，但也可能判断错，一样要看一眼。
+
+两种模式都会把 .figma.ts 生成到当前目录（运行这个命令的项目根目录）的 figma-mappings/，并重新生成
+registry.generated.ts（自动扫全部 .figma.ts，不需要手动加 import）。`);
+}
+
+function rankFiles(files, schema) {
+  return files
+    .map((f) => {
+      const info = extractComponentInfo(f);
+      const s = scoreCandidate(schema, info);
+      return { file: f, info, ...s };
+    })
+    .sort((a, b) => b.score - a.score);
+}
+
+async function main(schemaPath, useAi) {
+  if (!schemaPath || !fs.existsSync(schemaPath)) {
+    console.error(`找不到 schema 文件: ${schemaPath}\n先在插件面板里对着未映射的实例点"导出 schema.json"。`);
+    process.exitCode = 1;
+    return;
+  }
+  const parsed = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const queue = Array.isArray(parsed) ? parsed : [parsed];
+  console.log(`\n共 ${queue.length} 个 Figma 组件待处理。${useAi ? '（AI 模式）' : ''}\n`);
+
+  await processQueue(queue, useAi);
+  rl.close();
+}
+
+async function processQueue(queue, useAi) {
+  if (queue.length === 0) {
+    console.log('\n全部处理完。');
+    return;
+  }
+  const [schema, ...rest] = queue;
+  console.log(`\n────────── [还剩 ${queue.length} 个] ──────────`);
+  console.log(`目标 Figma 组件: ${schema.componentName}`);
+  console.log(`属性: ${schema.properties.map((p) => `${p.name}(${p.type})`).join(', ') || '（无）'}\n`);
+
+  const allFiles = listCandidateFiles();
+  if (useAi) {
+    return aiFlow(schema, rankFiles(allFiles, schema), rest);
+  }
+  await pickLoop(schema, rankFiles(allFiles, schema), allFiles, rest);
+}
+
+async function aiFlow(schema, ranked, rest) {
+  const top = ranked.slice(0, 6);
+  if (top.length === 0) {
+    console.log('没有候选文件，跳过这个组件。');
+    return processQueue(rest, true);
+  }
+  console.log(`把这 ${top.length} 个候选连同源码交给 claude 判断:`);
+  top.forEach((r) => console.log(`  - ${r.file}`));
+  console.log('\n调用中（可能要几十秒）...\n');
+
+  const config = readConfig();
+  const candidates = top.map((r) => ({ relPath: r.file, source: r.info.source }));
+
+  let result;
+  try {
+    result = aiGenerateMapping({ schema, candidates, importPaths: config.importPaths });
+  } catch (err) {
+    console.log(`调用 claude CLI 失败：${err.stderr || err.stdout || err.message}\n`);
+    const fallback = (await ask('要不要退回本地正则打分手动挑一个？(y/N): ')).trim().toLowerCase();
+    if (fallback === 'y') {
+      const allFiles = listCandidateFiles();
+      return pickLoop(schema, ranked, allFiles, rest, true);
+    }
+    return processQueue(rest, true);
+  }
+
+  if (!result.matched) {
+    console.log(`AI 判断没有合适的候选：${result.reason}\n`);
+    const fallback = (await ask('要不要退回本地正则打分手动挑一个？(y/N): ')).trim().toLowerCase();
+    if (fallback === 'y') {
+      const allFiles = listCandidateFiles();
+      return pickLoop(schema, ranked, allFiles, rest, true);
+    }
+    return processQueue(rest, true);
+  }
+
+  console.log(`AI 选了: ${result.relPath}\n`);
+  console.log('─'.repeat(60));
+  console.log(result.content);
+  console.log('─'.repeat(60));
+
+  const confirm = (await ask('\n确认采纳这份生成结果吗？输入 "good" 确认，其他任意键放弃: ')).trim();
+  if (confirm !== 'good') {
+    console.log('放弃，跳过这个组件。\n');
+    return processQueue(rest, true);
+  }
+
+  return writeMappingFile(schema, result.content, rest, true);
+}
+
+async function pickLoop(schema, ranked, allFiles, rest, useAi) {
+  const top = ranked.slice(0, 8);
+  if (top.length === 0) {
+    console.log('没有候选文件了，跳过这个组件。');
+    return processQueue(rest, useAi);
+  }
+  console.log('候选排名（分数越高越像）:\n');
+  top.forEach((r, i) => {
+    const reason = `名字相似度 ${r.nameScore.toFixed(2)} · 属性重合 ${r.overlapCount}/${schema.properties.length}`;
+    console.log(`  ${i + 1}. ${r.file}  [${r.score.toFixed(2)}]  (${reason})`);
+  });
+
+  const answer = (
+    await ask('\n输入序号选一个 / 输入关键字重新筛选文件 / "m" 手动输入路径 / "s" 跳过这个组件 / "q" 全部退出: ')
+  ).trim();
+
+  if (answer === 'q') return;
+  if (answer === 's') return processQueue(rest, useAi);
+
+  if (answer === 'm') {
+    const rel = (await ask('输入路径（相对项目根目录，或绝对路径）: ')).trim();
+    if (!fs.existsSync(path.resolve(ROOT, rel))) {
+      console.log('文件不存在，重来。\n');
+      return pickLoop(schema, ranked, allFiles, rest, useAi);
+    }
+    return confirmAndGenerate(schema, path.relative(ROOT, path.resolve(ROOT, rel)), rest, useAi);
+  }
+
+  const idx = Number(answer);
+  if (Number.isInteger(idx) && idx >= 1 && idx <= top.length) {
+    return confirmAndGenerate(schema, top[idx - 1].file, rest, useAi);
+  }
+
+  const filtered = allFiles.filter((f) => f.toLowerCase().includes(answer.toLowerCase()));
+  if (filtered.length === 0) {
+    console.log('没匹配到文件，重来。\n');
+    return pickLoop(schema, ranked, allFiles, rest, useAi);
+  }
+  console.log('');
+  return pickLoop(schema, rankFiles(filtered, schema), allFiles, rest, useAi);
+}
+
+async function confirmAndGenerate(schema, relPath, rest, useAi) {
+  const info = extractComponentInfo(relPath);
+  const componentName =
+    info.names.find((n) => n.toLowerCase() === path.basename(relPath, '.ts').toLowerCase()) ??
+    info.names[0] ??
+    path.basename(relPath, '.ts');
+
+  console.log(`\n选中: ${relPath}`);
+  console.log(`识别到的导出: ${info.names.join(', ') || '（没找到 export 的组件名，会用文件名兜底）'}`);
+  console.log(`默认取: ${componentName}（不对的话下一步可以改）`);
+  if (info.propsBlocks.length) {
+    console.log(`Props 定义:`);
+    for (const b of info.propsBlocks) {
+      const names = [...b.body.matchAll(/^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\??:/gm)].map((m) => m[1]);
+      console.log(`  ${b.typeName} { ${names.join(', ')} }`);
+    }
+  } else {
+    console.log('没找到 Props type/interface（可能是内联类型，生成后自己核对）');
+  }
+
+  const nameInput = (await ask(`\n代码组件名 [回车用 "${componentName}"]: `)).trim();
+  const finalName = nameInput || componentName;
+
+  const confirm = (await ask(`\n确认生成映射吗？输入 "good" 确认，其他任意键放弃: `)).trim();
+  if (confirm !== 'good') {
+    console.log('放弃，回到列表。\n');
+    const allFiles = listCandidateFiles();
+    return pickLoop(schema, rankFiles(allFiles, schema), allFiles, rest, useAi);
+  }
+
+  const config = readConfig();
+  const importSpecifier = toImportSpecifier(relPath, config.importPaths);
+  const propsBlock = info.propsBlocks[0];
+  const content = buildMatchedScaffold({
+    schema,
+    componentFile: relPath,
+    componentName: finalName,
+    importSpecifier,
+    propsBlock,
+  });
+
+  return writeMappingFile(schema, content, rest, useAi);
+}
+
+/** 两条路径（本地打分 / AI 判断）共用的落盘逻辑：确认保存路径、硬性保护、写文件、接 registry */
+async function writeMappingFile(schema, content, rest, useAi) {
+  const safeName = schema.componentName.replace(/[^a-zA-Z0-9]+/g, '') || 'Component';
+  const defaultOut = path.relative(ROOT, path.join(MAPPINGS_DIR, `${safeName}.figma.ts`));
+  const outInput = (await ask(`保存到哪 [回车用 "${defaultOut}"]: `)).trim();
+  const outRel = outInput || defaultOut;
+  const outAbs = path.resolve(ROOT, outRel);
+
+  // 硬性保护：绝不允许写到当前项目（ROOT = 运行这个命令时所在的目录）以外
+  if (!outAbs.startsWith(ROOT + path.sep)) {
+    console.log(`拒绝写入：${outAbs} 在项目根目录之外，这个脚本只允许往 ${ROOT} 里写。跳过这个组件。\n`);
+    return processQueue(rest, useAi);
+  }
+
+  if (fs.existsSync(outAbs)) {
+    const overwrite = (await ask(`${outRel} 已存在，覆盖？(y/N): `)).trim().toLowerCase();
+    if (overwrite !== 'y') {
+      console.log('取消写入，跳过这个组件。\n');
+      return processQueue(rest, useAi);
+    }
+  }
+
+  fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+  fs.writeFileSync(outAbs, content);
+  console.log(`\n已写入 ${outRel}`);
+
+  const { count } = refreshRegistry({ cwd: ROOT });
+  console.log(`registry.generated.ts 已重新生成（${count} 条映射）`);
+
+  return processQueue(rest, useAi);
+}
+
+const args = process.argv.slice(2);
+const useAiFlag = args.includes('--ai');
+const schemaPath = args.find((a) => !a.startsWith('--'));
+
+if (!schemaPath) {
+  printHelp();
+  rl.close();
+} else {
+  await main(schemaPath, useAiFlag);
+  console.log(`\n全部跑完，回到项目里跑一遍类型检查 + 插件构建（比如 rexy 是 "pnpm run figma:build"），确认编得过，再回 Figma 重新读取验证。`);
+  rl.close();
+}

package/scripts/figma-mapping/lib.mjs

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ROOT 是运行这个 CLI 时所在的目录——消费方（比如 trex-website/apps/rexy）在自己项目里
+// 跑 `figma-mapping`，ROOT 就是那个项目，.figma.ts 和 config 都读写在消费方自己那边，
+// 不是这个引擎包安装到哪 ROOT 就是哪（那是 import.meta.url 的算法，这里故意不用）。
+export const ROOT = process.cwd();
+// 文件名特意不叫 figma.config.json —— 官方 Figma Code Connect CLI 也认这个文件名，
+// 消费方项目里可能已经有一份官方的（trex-website/apps/rexy 就有），撞名会互相踩。
+export const CONFIG_PATH = path.join(ROOT, 'figma-mapping.config.json');
+export const MAPPINGS_DIR = path.join(ROOT, 'figma-mappings');
+
+/**
+ * figma-mapping.config.json 放在消费方项目根目录，内容都是项目内相对路径，可以直接提交 git——
+ * 不再需要"公共配置 + 每人一份本地绝对路径覆盖"那一套，因为 CLI 现在就是在消费方项目里跑的，
+ * 不存在"扫另一个仓库"的绝对路径问题了。
+ */
+export function readConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    console.warn(
+      `[figma-mapping] 当前目录（${ROOT}）没有 figma-mapping.config.json —— 扫不到任何候选组件目录。\n` +
+        `抄引擎包里的 figma-mapping.config.example.json，在这个项目根目录建一份，改成自己的组件目录。`,
+    );
+    return { paths: {}, importPaths: {} };
+  }
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')).codeConnect;
+}
+
+function globToRegExp(glob) {
+  let re = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  // "dir/**/pattern" 得能匹配零层子目录（"dir/pattern" 本身），不能死要求斜杠两边都有内容
+  re = re.replace(/\/\*\*\//g, '/(?:.*/)?');
+  re = re.replace(/\*\*/g, '.*');
+  re = re.replace(/\*/g, '[^/]*');
+  return new RegExp(`^${re}$`);
+}
+
+/** 候选代码组件从 figma.config.json 的 paths 里声明的目录扫，不是随便全仓库翻 */
+export function listCandidateFiles() {
+  const { paths } = readConfig();
+  const dirs = Object.values(paths ?? {});
+  const results = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.tsx?$/.test(entry.name) && !/\.figma\.tsx?$/.test(entry.name)) {
+        results.push(path.relative(ROOT, full));
+      }
+    }
+  }
+
+  // path.resolve 而不是 path.join —— dirs 里可能是绝对路径（比如指向另一个仓库只读扫描），
+  // join 会把绝对路径当成普通片段拼接在 ROOT 后面，resolve 才会正确地整个替换掉
+  for (const d of dirs) walk(path.resolve(ROOT, d));
+  return results;
+}
+
+/** 正则抠出组件名 + Props 类型定义源码，够打分和展示用，不追求 AST 级精确 */
+export function extractComponentInfo(relPath) {
+  const source = fs.readFileSync(path.join(ROOT, relPath), 'utf8');
+
+  const nameMatches = [
+    ...source.matchAll(/export\s+(?:declare\s+)?(?:const|function|class)\s+([A-Z][A-Za-z0-9]*)/g),
+  ].map((m) => m[1]);
+
+  const propsBlocks = [
+    ...source.matchAll(/(?:interface|type)\s+([A-Za-z0-9]*Props)\b[^{]*\{([\s\S]*?)\n\}/g),
+  ].map((m) => ({ typeName: m[1], body: m[2] }));
+
+  const propNames = new Set();
+  for (const block of propsBlocks) {
+    for (const m of block.body.matchAll(/^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\??:/gm)) {
+      propNames.add(m[1]);
+    }
+  }
+
+  return { relPath, names: nameMatches, propsBlocks, propNames: [...propNames], source };
+}
+
+function normalize(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function tokenOverlap(a, b) {
+  const na = normalize(a);
+  const nb = normalize(b);
+  if (!na || !nb) return 0;
+  if (na === nb) return 1;
+  if (na.includes(nb) || nb.includes(na)) return 0.7;
+  return 0;
+}
+
+/** 打分：组件名相似度权重高，属性名重合度加分 */
+export function scoreCandidate(schema, info) {
+  const fileBase = path.basename(info.relPath).replace(/\.tsx?$/, '');
+  const nameCandidates = [...info.names, fileBase];
+  const nameScore = Math.max(0, ...nameCandidates.map((n) => tokenOverlap(schema.componentName, n)));
+
+  const schemaProps = schema.properties.map((p) => normalize(p.name)).filter(Boolean);
+  const codeProps = info.propNames.map(normalize);
+  const overlapCount = schemaProps.filter((p) => codeProps.some((c) => c === p || c.includes(p) || p.includes(c)))
+    .length;
+  const propScore = schemaProps.length ? overlapCount / schemaProps.length : 0;
+
+  const score = nameScore * 0.6 + propScore * 0.4;
+  return { score, nameScore, propScore, overlapCount, fileBase };
+}

package/scripts/figma-mapping/registry.mjs

@@ -0,0 +1,12 @@
+import { generateRegistry } from '../generate-registry.mjs';
+import { REGISTRY_GENERATED } from '../build-plugin.mjs';
+
+/**
+ * registry.ts 的 templates 数组由 scripts/generate-registry.mjs 按 glob 自动生成，不需要手动加
+ * import。输出文件固定写进引擎包自己的 src/runtime/registry.generated.ts（跟 buildPlugin() 用的
+ * 是同一个路径，build-plugin.mjs 里解释过为什么——多个消费方会互相覆盖，目前接受这个简化）。
+ */
+export function refreshRegistry({ cwd, mappingsGlob = 'figma-mappings/**/*.figma.ts' }) {
+  const result = generateRegistry({ cwd, mappingsGlob, outFile: REGISTRY_GENERATED });
+  return { count: result.count };
+}

package/scripts/figma-mapping/scaffold.mjs

@@ -0,0 +1,153 @@
+function normalize(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** 从 Props 类型源码里找某个 prop 声明行，抠出它的联合类型字面量（给 VARIANT 自动配值用） */
+function findUnionLiterals(propsBody, propName) {
+  const line = propsBody.split('\n').find((l) => new RegExp(`^\\s*${propName}\\??:`).test(l));
+  if (!line) return null;
+  const literals = [...line.matchAll(/"([^"]+)"|'([^']+)'/g)].map((m) => m[1] ?? m[2]);
+  return literals.length ? literals : null;
+}
+
+/** 在 code prop 名单里，找跟某个 schema property 名字最像的一个 */
+function bestPropMatch(schemaPropName, codePropNames) {
+  const target = normalize(schemaPropName);
+  if (!target) return null; // 中文/符号属性名会被 normalize 削成空串，空串是任何字符串的子串，不能拿来配
+  let best = null;
+  for (const name of codePropNames) {
+    const n = normalize(name);
+    if (n === target || n.includes(target) || target.includes(n)) {
+      if (!best || n.length < normalize(best).length) best = name;
+    }
+  }
+  return best;
+}
+
+function varName(p, i, seen) {
+  const cleaned = p.name.replace(/[^a-zA-Z0-9]/g, '');
+  const base = cleaned || `prop${i + 1}`;
+  const camel = base[0].toLowerCase() + base.slice(1);
+  let name = /^[0-9]/.test(camel) ? `_${camel}` : camel;
+  // 中文属性名剥完 ascii 后可能撞车（比如"左icon"和"右icon"都只剩"icon"），撞了就按顺序加序号
+  if (seen.has(name)) {
+    let n = 2;
+    while (seen.has(`${name}${n}`)) n++;
+    name = `${name}${n}`;
+  }
+  seen.add(name);
+  return name;
+}
+
+function idFrom(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '') || 'template';
+}
+
+function propLine(p, i, codePropNames, propsBody, seen, claimedCodeProps) {
+  const v = varName(p, i, seen);
+  const guess = bestPropMatch(p.name, codePropNames);
+  // 一个代码 prop 已经被别的 Figma 属性占用了，就不能再配第二次（比如"左icon"/"右icon"都只剩"icon"，
+  // 不能俩都配到同一个 leftIcon 上——留 TODO 比生成一个明摆着错的重复 attr 更诚实）
+  const matched = guess && !claimedCodeProps.has(guess) ? guess : null;
+  if (matched) claimedCodeProps.add(matched);
+
+  switch (p.type) {
+    case 'TEXT':
+      return { line: `const ${v} = instance.getString('${p.name}')`, jsxAttr: matched ? `${matched}={${v}}` : null };
+    case 'BOOLEAN':
+      return { line: `const ${v} = instance.getBoolean('${p.name}')`, jsxAttr: matched ? `${matched}={${v}}` : null };
+    case 'VARIANT': {
+      const literals = matched && propsBody ? findUnionLiterals(propsBody, matched) : null;
+      const opts = p.variantOptions ?? [];
+      const mapping = opts
+        .map((o) => {
+          const guess = literals?.find((l) => normalize(l) === normalize(o)) ?? literals?.[0];
+          const value = guess ? JSON.stringify(guess) : `'TODO'`;
+          return `      ${JSON.stringify(o)}: ${value},`;
+        })
+        .join('\n');
+      return {
+        line: `const ${v} = instance.getEnum('${p.name}', {\n${mapping}\n    })`,
+        jsxAttr: matched ? `${matched}="\${${v}}"` : null,
+      };
+    }
+    case 'INSTANCE_SWAP':
+      return {
+        line:
+          `const ${v} = instance.getInstanceSwap('${p.name}')\n` +
+          `    let ${v}Code\n` +
+          `    if (${v} && ${v}.type === 'INSTANCE') {\n      ${v}Code = ${v}.executeTemplate()?.example\n    }`,
+        jsxAttr: matched ? `${matched}={\${${v}Code}}` : null,
+      };
+    default:
+      return { line: `// TODO: 未知属性类型 ${p.type} — ${p.name}`, jsxAttr: null };
+  }
+}
+
+/**
+ * 生成一份接到 mini-figma-code-connect 运行时的 .figma.ts —— 落进消费方项目的 figma-mappings/。
+ * import/source/component 用匹配到的真实文件与 figma-mapping.config.json 的 importPaths 换算出来的 specifier；
+ * VARIANT 字典尽量从 Props 联合类型里自动配对真实值，配不上的标 TODO。
+ */
+export function buildMatchedScaffold({ schema, componentFile, componentName, importSpecifier, propsBlock }) {
+  const propsBody = propsBlock?.body ?? '';
+  const codePropNames = propsBlock ? [...propsBody.matchAll(/^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\??:/gm)].map((m) => m[1]) : [];
+
+  const seen = new Set();
+  const claimedCodeProps = new Set();
+  const parts = schema.properties.map((p, i) => propLine(p, i, codePropNames, propsBody, seen, claimedCodeProps));
+  const lines = parts.map((p) => `    ${p.line}`).join('\n\n');
+  const jsxAttrs = parts
+    .map((p) => p.jsxAttr)
+    .filter(Boolean)
+    .map((a) => `\n          ${a}`)
+    .join('');
+  const unmatchedCount = schema.properties.length - parts.filter((p) => p.jsxAttr).length;
+  const id = idFrom(schema.componentName);
+
+  return `// url=https://www.figma.com/design/REPLACE_FILE_KEY/Design-System?node-id=REPLACE
+// source=${componentFile}
+// component=${componentName}
+import { defineTemplate } from '../runtime/define'
+import { code } from '../runtime/tagged'
+
+/**
+ * 由 figma-mapping CLI 生成：Figma "${schema.componentName}" ↔ 代码 ${componentName}（${componentFile}）
+ * ${unmatchedCount > 0 ? `${unmatchedCount} 个属性没自动配上对应的代码 prop，人工确认` : '每个属性都自动配上了对应的代码 prop，仍建议人工确认一遍'}
+ */
+export default defineTemplate({
+  meta: {
+    url: 'https://www.figma.com/design/REPLACE_FILE_KEY/Design-System?node-id=REPLACE',
+    source: '${componentFile}',
+    component: '${componentName}',
+  },
+  id: '${id}',
+  match: { componentName: '${schema.componentName}' },
+
+  render(instance) {
+${lines || '    // 这个组件没有可读的属性'}
+
+    return {
+      example: code\`
+        <${componentName}${jsxAttrs}
+        />
+      \`,
+      imports: ['import { ${componentName} } from "${importSpecifier}"'],
+      id: '${id}',
+      metadata: { nestable: true },
+    }
+  },
+})
+`;
+}
+
+export function toImportSpecifier(relPath, importPaths) {
+  for (const [glob, spec] of Object.entries(importPaths ?? {})) {
+    const prefix = glob.replace(/\*$/, '');
+    if (relPath.startsWith(prefix)) {
+      const rest = relPath.slice(prefix.length).replace(/\.tsx?$/, '');
+      return spec.endsWith('*') ? spec.replace(/\*$/, rest) : spec;
+    }
+  }
+  return './' + relPath.replace(/\.tsx?$/, '');
+}