mini-figma-code-connect 0.1.0

package/.claude/skills/mini-code-connect/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: mini-code-connect
+description: 把 Figma 组件 schema.json（单个或数组）映射成 (a) 消费方项目里的 .figma.ts 模板，(b) 纯数据版的 figma-mapping-table.json（供其他项目/skill 直接查表，不依赖运行时）。用户提到"映射"、"mapping"、提供 schema.json，或要求"跑一下 mini-code-connect"时使用。**跟官方 figma-code-connect skill 的区别**：不需要 Organization/Enterprise plan，读的是插件导出的 schema.json（不是实时 Figma MCP），产出格式是 defineTemplate/code，不是官方 figma.connect()/parser 格式——两者不兼容，不要混用。
+disable-model-invocation: false
+---
+
+# Mini Code Connect
+
+将 Figma 组件 schema 关联到真实代码组件，生成 `.figma.ts`（`defineTemplate`/`code` 格式，区别于官方 `figma.connect()` 格式，见下方“格式参考”）。
+
+**这个 skill 本身（`mini-figma-code-connect` 引擎）不装真实映射数据**——它是被各个消费方项目（比如 `trex-website/apps/rexy`）以 npm 依赖（或本地 `link:`）装进去用的一个纯引擎包。真正的 `.figma.ts`、`figma-mapping-table.json`、`figma-mapping.config.json` 都应该生成在**消费方项目自己的目录里**，不是这个引擎仓库里。执行前先确认当前要处理的是哪个消费方项目（通常从用户的上下文或已打开的项目判断；如果不确定，问一句）。
+
+这是 agent 驱动的工作流，不是脚本——由 agent 直接阅读代码判断组件对应关系。`scripts/figma-mapping/` 下有一套本地正则打分 CLI 作为无 agent 场景的兜底方案，运行时以**当前工作目录**（即消费方项目根目录，而不是这个引擎仓库）为准来读 config、写 `.figma.ts`。
+
+## 输入
+
+单个 `ComponentSchema`，或其数组（插件"导出全部 schema.json"的产出）。数组按顺序逐个处理：完成一个（写入文件）再处理下一个；遇到需要用户确认的项先跳过，继续处理数组中其余可确定的项，待遇到的问题集中在最后一并询问，避免整批阻塞。
+
+## 步骤
+
+1. **查重。** 检查消费方项目 `figma-mappings/*.figma.ts` 中是否已存在同名或同 key 的 `match`（`registry.generated.ts` 是自动生成的，不体现实际列表，查重要看 `.figma.ts` 文件本身）。已存在时询问用户保留、覆盖还是作为新映射处理——同一批 schema 可能混合了已处理和未处理的项，不查重会导致重复生成。
+
+2. **定位候选组件。** 读取消费方项目根目录下 `figma-mapping.config.json` 的 `codeConnect.paths`（不存在就复制引擎包的 [figma-mapping.config.example.json](../../../figma-mapping.config.example.json) 到消费方项目根目录创建一份——内容都是项目内相对路径，可以直接提交 git）。**注意文件名是 `figma-mapping.config.json` 不是 `figma.config.json`**——后者是官方 Figma Code Connect CLI 认的文件名，消费方项目里可能已经有一份官方的（比如 `trex-website/apps/rexy` 就有一份官方 `figma.config.json` + 顶层 `Button.figma.ts`，那是完全独立的另一套东西，不要混淆也不要覆盖）。拿到 `paths` 后遍历这些目录下的 `.ts`/`.tsx` 文件（排除 `.figma.ts`），阅读 Props 定义判断语义是否对应——组件名相似度仅供参考，Props 语义一致性才是判定依据。没有合适候选时明确说明，不做牵强匹配。
+
+3. **映射属性。** 按 [handle.ts](../../../src/main/handle.ts) 的 accessor 对应关系处理：
+
+   | Figma 类型 | accessor |
+   |---|---|
+   | TEXT | `getString('属性名')` |
+   | BOOLEAN | `getBoolean('属性名')`——若代码侧是其他形式（例如从某个枚举拆分出的 disabled/loading），按实际语义处理 |
+   | VARIANT | `getEnum('属性名', {...})`，字典须覆盖 `variantOptions` 的每一个值，遗漏会静默返回 undefined |
+   | INSTANCE_SWAP | `getInstanceSwap('属性名')` + `.executeTemplate()?.example`，使用前需判断 `.type === 'INSTANCE'` |
+
+   无法确定的判断仍需给出结论，但要在文件头部注释中注明"此处为推测"。确实无法推断的情况（缺少精确对应的图标组件、无法确定文案图层名）应停下询问用户，不得生成语法正确但语义错误的内容。禁止编造代码中不存在的 prop。
+
+4. **生成 `.figma.ts`**，格式见下方“格式参考”。写到消费方项目根目录的 `figma-mappings/<组件名>.figma.ts`。`meta.source` 字段填写真实组件文件相对消费方项目根目录的路径。`imports` 按 `figma-mapping.config.json` 的 `importPaths` 做前缀匹配换算。
+
+5. **同步写入一条 `figma-mapping-table.json` 记录。** 该文件面向本仓库之外的消费方（其他 skill、其他项目查表使用），与 `.figma.ts` 内容对应但格式不同——纯数据，不含 `defineTemplate`/`getEnum` 等仅本仓库运行时可识别的内容。默认文件名为 `figma-mapping-table.json`（与 `buildPlugin` / `scaffold-plugin` 默认一致）。记录结构：
+
+   ```json
+   {
+     "figmaComponentName": "...",
+     "figmaComponentKey": "...",
+     "codeComponent": "...",
+     "codeSource": "相对候选组件所在仓库根目录的路径",
+     "codeImportSpecifier": "真实 import 使用的 specifier",
+     "props": [
+       { "figmaProp": "...", "figmaType": "...", "codeProp": "..." 或 null,
+         "valueMap": {...} 或 null, "confidence": "matched" | "guessed" | "unmatched",
+         "note": "判断依据，guessed/unmatched 必须填写" }
+     ],
+     "unmappedNotes": ["属性完全无法推断时记录在此，例如缺少 TEXT 属性导致拿不到文案图层名"]
+   }
+   ```
+
+   `codeSource`/`codeImportSpecifier` 需与该记录来源的候选目录对应（消费方项目里 `figma-mapping.config.json` 声明的候选目录）；`props` 逐条对应第 3 步的判断结果，`confidence`/`note` 为必填字段。**此步骤需保持幂等**：按 `figmaComponentKey`（缺失时按 `figmaComponentName`）检查 `figma-mapping-table.json` 中是否已有同一条记录，存在则整条替换，不存在则追加，不产生重复记录。
+
+6. **落盘前向用户展示结果**，标注所有推测性判断，待确认后再写入。
+
+7. **写入范围限定在当前消费方项目**：`figma-mappings/*.figma.ts`、`figma-mapping-table.json`。**绝不写入这个引擎仓库（`mini-figma-code-connect`）自己**——它不装任何真实映射数据，只提供 `defineTemplate`/`code` 运行时和 CLI/构建脚本。如果当前上下文涉及多个候选消费方项目、不确定该往哪个项目写，先问用户。
+
+8. **全部处理完成后统一验证一次**，而非逐个组件执行——在**消费方项目**里跑它自己的类型检查 + 插件构建脚本（例如 `trex-website/apps/rexy` 是）：
+
+   ```bash
+   pnpm --filter rexy run type-check
+   pnpm --filter rexy run figma:build
+   ```
+
+   `figma:build` 背后调用的是引擎包导出的 `buildPlugin()`，会自动先重新扫描消费方项目的 `figma-mappings/**/*.figma.ts` 生成 `registry.generated.ts`——新建/修改的 `.figma.ts` 会自动被收录，不需要手动加 import。出现编译错误须就地修复。通过后提示用户回到 Figma 插件面板，通过"重新读取"或"扫描页面"确认效果。
+
+## 格式参考
+
+```ts
+import { defineTemplate, code } from 'mini-figma-code-connect'
+
+export default defineTemplate({
+  meta: {
+    url: 'https://www.figma.com/design/FILE_KEY/...?node-id=NODE_ID',
+    source: '相对消费方项目根目录的真实组件文件路径',
+    component: 'Button',
+  },
+  id: 'button',
+  match: { componentName: 'Button', componentKey: 'FIGMA_COMPONENT_KEY' },
+
+  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',
+    }
+  },
+})
+```
+
+- INSTANCE_SWAP 嵌套写法、无属性组件、推测性判断标注等更复杂的实际案例，参考已经生成在消费方项目里的 `.figma.ts` 文件本身（比如 `trex-website/apps/rexy/figma-mappings/`），不再维护在这个引擎仓库里。
+- [types.ts](../../../src/runtime/types.ts) 的 `InstanceLike`——accessor 类型定义（`getString`/`getBoolean`/`getEnum`/`getInstanceSwap`/`findText`）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elaine.ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# mini-figma-code-connect
+
+**Local Code Connect for Figma Professional** — 无 Org / Enterprise 也能做确定性的 `f(instance) → snippet`。
+
+面向 Pro 档团队的轻量替代引擎：Figma 插件 + 将设计组件映射到消费方真实代码库的工作流。
+
+官方 Code Connect 与 Builder.io Design System Intelligence 均要求 Organization / Enterprise 订阅；团队当前为 Professional，相关 MCP 绑定工具不可用。本引擎在本地实现等价的「组件绑定 + 属性映射」：映射进消费方仓库、执行在 Figma 插件，不依赖云端 publish。插件沙箱无法读写本地代码，因此映射生成在沙箱外（agent / CLI）完成，再经构建打包进插件。
+
+完整背景评估、引擎仓库本地开发、系统架构与核心实现见本地 [核心实现.md](核心实现.md)（不纳入版本控制）；方案对比见 [参考.md](参考.md)。
+
+---
+
+## 消费方接入
+
+面向将 `mini-figma-code-connect` 接入自身项目、并开始建立 Figma 组件映射的使用者。下文以 `trex-website/apps/rexy` 为例，所有命令默认在消费方子项目目录（例如 `apps/rexy`，而非 monorepo 根目录）下执行。
+
+### 前置条件
+
+- 消费方项目为 npm/pnpm 项目（存在 `package.json`），且位于 git 仓库内——脚手架命令依赖 `.git` 定位仓库根目录。
+- Node.js ≥ 18。
+
+### 接入步骤
+
+#### 1. 安装依赖
+
+```bash
+pnpm add -D mini-figma-code-connect
+# 或：npm install -D mini-figma-code-connect
+```
+
+本地开发引擎时仍可用 `link:` / `file:` 指向仓库路径。包尚未安装时，后续 CLI 命令均不存在。
+
+#### 2. 执行一次性脚手架
+
+```bash
+pnpm exec mini-code-connect-scaffold-plugin --id <manifest-id>
+```
+
+`--id` 为必填参数，同一 Figma 账号内不可与已导入的其他插件重复（引擎仓库自身的 demo 插件 id 为 `simple-code-connect-demo`）。`--name` 为可选参数，默认值为 `"Mini Code Connect"`；仅当账号内同时安装了多个消费方插件、需要在 Figma 插件列表中加以区分时才需传入。
+
+该命令具备幂等性：已存在的文件不会被覆盖，重复执行不会影响后续的手动修改；如需强制重新生成，附加 `--force` 参数。执行内容如下：
+
+| 步骤 | 目标位置 | 说明 |
+|---|---|---|
+| 安装 skill | `<仓库根>/.claude/skills/mini-code-connect/`（若 `<仓库根>/.agents/skills/` 存在，同时写入一份） | 自动从当前目录向上查找 `.git` 所在的仓库根——pnpm monorepo 中子包目录并非仓库根，写入错误位置会导致 Claude Code 无法发现该 skill |
+| 候选组件目录配置 | `<cwd>/figma-mapping.config.json` | 默认假设组件位于 `<cwd>/components`，可通过 `--components <dir>` 调整 |
+| Manifest | `<cwd>/manifest.json` 与 `manifest.codegen.json` | `main`/`ui` 字段指向 `--out` 参数指定的目录（默认 `figma-plugin-dist`） |
+| 构建脚本 | `<cwd>/scripts/build-figma-plugin.mjs` | 调用引擎包导出的 `buildPlugin()` |
+| package.json | 新增 `scripts.figma:build` 与 `figma:watch` | 已存在的同名 script 不会被覆盖 |
+| `.gitignore` | 新增构建产物目录的忽略规则 | 已存在同一条规则则跳过 |
+| 首次构建 | `<cwd>/<outDir>/`（默认 `figma-plugin-dist/`） | 命令结束时自动执行一次构建，产出可直接导入 Figma 的插件——无需额外手动执行 `pnpm run figma:build` |
+
+命令执行完毕即可直接导入 Figma（见步骤 4），无需再手动构建一次。
+
+如需单独执行其中某一步（例如仅重新生成 manifest），可使用以下更细粒度的命令——`scaffold-plugin` 内部即调用这两者：
+
+```bash
+pnpm exec mini-code-connect-install-skill                          # 仅执行 skill 安装
+pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id>   # 仅执行 manifest 生成
+```
+
+#### 3. 按需调整候选组件目录
+
+若项目的组件目录并非 `components/`，或 import 写法并非 `@/` 别名，打开步骤 2 生成的 `figma-mapping.config.json` 修改 `paths`/`importPaths`：
+
+```json
+{
+  "codeConnect": {
+    "paths": { "components": "components" },
+    "importPaths": { "components/*": "@/components/*" }
+  }
+}
+```
+
+文件内容均为项目内相对路径，可直接提交至 git。修改该文件不影响已生成的插件产物，不需要重新构建——它仅在建立映射时（步骤 5）由 skill/CLI 读取，用于定位候选组件。
+
+#### 4. 导入 Figma
+
+**Figma 桌面版 → 菜单 → Plugins → Development → Import plugin from manifest…**，选择 `<cwd>/manifest.json`。
+
+如需 Dev Mode Code 区形态，以相同方式导入 `manifest.codegen.json`（`id` 不同，为独立记录，二者可同时导入）。
+
+此时插件已可运行，但尚无真实映射数据，所有实例均显示为「未映射」。
+
+#### 5. 建立真实映射
+
+1. 在插件面板中选中未映射实例，点击「导出 schema.json」（候选列表页可使用「导出全部 schema.json」批量导出）。
+2. 在该消费方项目的 Claude Code 会话中（而非引擎仓库的会话），提供 schema.json 路径，或直接描述映射需求，以触发 `/mini-code-connect` skill。该 skill 将执行查重、扫描步骤 3 配置的候选目录、生成 `figma-mappings/*.figma.ts` 与 `figma-mapping-table.json`，写入位置为当前消费方项目，不写入引擎仓库。
+3. 执行 `pnpm run figma:build`，将新生成的映射重新打包进插件。
+4. 返回插件面板，点击「重新读取」或「扫描页面」，确认状态变为「已映射」。
+
+无 agent 可用时，`pnpm exec figma-mapping <schema.json>` 提供本地正则打分作为兜底方案（同样支持批量 schema 数组与 `--ai` 模式），判断准确度低于 agent 现场读取代码，但落盘规则保持一致。
+
+### 命令参考
+
+| 命令 | 必填参数 | 作用 |
+|---|---|---|
+| `mini-code-connect-scaffold-plugin` | `--id` | 执行完整一次性脚手架（详见步骤 2） |
+| `mini-code-connect-install-skill` | 无 | 仅将 skill 复制至项目。`--root <path>` 显式指定仓库根，`--no-claude-mirror` 仅写入 `.agents/skills/`，`--force` 覆盖已存在内容 |
+| `mini-code-connect-scaffold-manifest` | `--id` | 仅生成 manifest.json 与 manifest.codegen.json。`--out <dir>` 指定产物目录 |
+| `figma-mapping` | `<schema.json>` | 本地正则打分 CLI，agent 缺席时的兜底方案。`--ai` 调用本机 `claude` CLI 以无头模式执行判断 |
+
+### 常见问题
+
+#### `EACCES: spawn <command>`
+
+通常由以下两种原因之一导致：
+
+1. **脚本文件缺少可执行权限**。正常情况下不应出现（引擎仓库内相关脚本均为 `-rwxr-xr-x`）；若出现，问题大概率在引擎侧，应向引擎仓库反馈。
+2. **bin 软链未生成**。引擎包的 `package.json` 新增了 `bin` 条目，但消费方项目在此后未重新执行安装，`node_modules/.bin/` 中缺少对应命令。执行以下命令刷新：
+   ```bash
+   pnpm install
+   ```
+
+#### `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL`
+
+该错误通常表示 `pnpm exec` 是在 monorepo 根目录执行的，触发了对所有工作区包的递归遍历，其中部分包并未安装该依赖。切换至具体子项目目录（例如 `apps/rexy`）后重新执行。
+
+#### 与项目中已有的其他 Figma Code Connect 相关 skill/config 是否存在冲突
+
+`mini-code-connect` 这一 skill 名称与 `figma-mapping.config.json` 这一配置文件名，均刻意与官方 Figma Code Connect（`figma-code-connect` skill、`figma.config.json`、`.figma.ts` + `figma.connect()`/`figma.code` 官方格式）区分。两者格式不兼容，不应混用，也不应将本手册的步骤应用于官方格式的文件。若项目中两者并存，`.claude/skills/`（及 `.agents/skills/`，如适用）下应可见 `mini-code-connect` 与 `figma-code-connect` 两个独立目录，互不覆盖。
+
+#### 修改 manifest 后 Figma 无变化
+
+`editorType`/`capabilities` 由 Figma 在插件注册时读取一次并缓存，修改 manifest 文件本身不会自动生效，必须在 Figma 中删除该开发插件并重新导入。构建产物（`figma-plugin-dist/` 下的 `code.js`/`ui.html`）则会在插件每次运行时重新读取，无需删除重导。
+
+---
+
+## 项目结构
+
+```
+manifest.json                     Figma 插件清单（面板形态）——本仓库自身 demo 用，产物零映射
+manifest.codegen.json             Figma 插件清单（Dev Mode Code 区形态）——同上
+figma-mapping.config.example.json 消费方接入时复制到自身项目根目录的配置模板
+esbuild.config.mjs                本仓库以 buildPlugin() 自举打包自身（零映射，用于验证引擎可用性）
+
+.claude/skills/mini-code-connect/
+└── SKILL.md                      工作流的完整步骤定义，agent 依此执行——写入目标是消费方项目，而非本仓库
+
+scripts/figma-mapping/            插件沙箱之外的工作流实现（CLI 以调用时的 cwd 作为 ROOT，即消费方项目根目录）
+├── index.mjs                        CLI 入口：本地正则打分选取候选 + 交互确认，agent 缺席场景下的兜底方案
+├── lib.mjs                           读取消费方项目的 figma-mapping.config.json，扫描候选目录，提取组件信息并打分
+├── scaffold.mjs                      根据打分选中的候选生成 .figma.ts 内容
+├── registry.mjs                      重新生成 registry.generated.ts（薄封装，核心逻辑位于 scripts/generate-registry.mjs）
+└── ai-generate.mjs                   --ai 模式：调用本机 claude CLI 进行判断（存在 OAuth 阻塞风险，不推荐；agent 在场时应直接使用 skill）
+
+scripts/
+├── build-plugin.mjs                导出 buildPlugin({cwd, mappingsGlob, mappingTablePath, outDir, watch})
+├── generate-registry.mjs           导出 generateRegistry({cwd, mappingsGlob, outFile})，扫描 .figma.ts 生成 registry.generated.ts
+├── copy-mapping-table.mjs          将消费方的 figma-mapping-table.json 复制至包自身 src/main/ 下，供 code.ts 静态引入
+├── install-skill.mjs               bin: mini-code-connect-install-skill
+├── scaffold-manifest.mjs           bin: mini-code-connect-scaffold-manifest
+├── scaffold-plugin.mjs             bin: mini-code-connect-scaffold-plugin —— 单条命令完成上述两项 + 候选目录配置 + 构建脚本 + package.json scripts
+└── is-cli-entrypoint.mjs           内部工具：判定"是否被直接作为 CLI 执行"（process.argv[1] 与 import.meta.url 的朴素比较通常不成立，详见文件内注释）
+
+src/
+├── runtime/                      轻量级 Code Connect 运行时（与 Figma API 无关，可独立测试）——包的公开入口
+│   ├── index.ts                      导出 defineTemplate/code/类型定义，消费方通过 `import { defineTemplate, code } from 'mini-figma-code-connect'` 引入
+│   ├── types.ts                      ResultSection / ComponentSchema / Template / InstanceLike
+│   ├── tagged.ts                     figma.code`...` 的简化实现：切分 section，展平嵌套结构
+│   ├── render.ts                     ResultSection[] 转字符串
+│   ├── define.ts                     defineTemplate()，用于类型收窄
+│   ├── registry.generated.ts         自动生成（已加入 .gitignore），由 scripts/generate-registry.mjs 扫描消费方 .figma.ts 产出；本地 build/typecheck 前生成
+│   └── registry.ts                   componentKey / componentName 到模板的查找；templates 数组从 registry.generated 转出
+├── main/                         插件主线程（可访问 figma.* API）
+│   ├── code.ts                       六步流水线与面板消息处理，详见核心实现.md
+│   ├── schema.ts                     组件到属性 schema 的提取
+│   ├── handle.ts                     InstanceHandle：访问器层与递归执行
+│   ├── validate.ts                   Step 6 自检的自动化实现
+│   ├── mapping-table.generated.json  自动生成（已加入 .gitignore），构建时从消费方的 figma-mapping-table.json 复制
+│   └── messages.ts                   主线程与 UI 间的消息类型定义
+├── ui/                            插件面板
+│   ├── ui.html
+│   └── ui.ts
+└── dev/
+    ├── demo.ts                       独立示例模板，使用模拟实例渲染，不依赖 Figma 或任何消费方数据
+    └── export.ts                     生成 codeconnect.json
+```
+
+---
+
+## 与官方 Code Connect 的差异
+
+以下差异均为刻意设计，而非未实现的功能缺口：
+
+| | 官方 Code Connect | 本实现 |
+|---|---|---|
+| 订阅计划要求 | Organization / Enterprise，需 Full 或 Dev 席位 | 无要求，任意计划均可运行 |
+| 模板存储位置 | 发布至 Figma 服务端（CLI `publish` 或 MCP `add_code_connect_map`） | 构建时打包进插件 |
+| 模板执行方 | Figma 侧沙箱，在 Dev Mode / MCP 读取时执行 | 插件主线程，选中实例时执行 |
+| 模板入口 | 模块顶层 `const instance = figma.selectedInstance` | `render(instance)` 函数参数 |
+| 三行绑定注释 | 构建时解析 `// url= // source= // component=` | 保留注释供人工阅读，同时在 `meta` 字段中显式声明 |
+| 组件发布状态要求 | 必须已发布 | 不要求，未发布时退回按组件名匹配 |
+| SLOT 属性 | 支持 `getSlot()` | 未实现，仅支持 TEXT / BOOLEAN / VARIANT / INSTANCE_SWAP |
+| 多框架支持 | 通过 `label` 枚举，单一设计组件可挂载多条并行映射 | 仅支持 React 一条 |
+| 穷举校验 | 不提供，缺值静默 | 提供，`validate()` 自动对账 |
+| 绑定关系判定方 | Figma 服务端存储的映射，或人工在 Code Connect UI 中手动指定 | agent 现场读取代码判断（mini-code-connect skill），或本地正则打分兜底 |
+
+---
+
+## 已知限制
+
+- **尚未接入基于 REST API 与 Personal Access Token 的 schema 拉取能力**。该方案理论可行（通用 Figma REST API 不受 Code Connect 订阅限制），但目前唯一的数据来源仍是插件手动导出的 schema.json。
+- **不提供跨消费方的数据新鲜度检查**。某个消费方代码库更新后，此前标记为 `guessed` / `unmatched` 的映射条目是否已可补全，需人工发起新一轮映射流程，引擎本身不做追踪。
+
+> 构建时生成的 `registry.generated.ts` / `mapping-table.generated.json` 写在消费方 `outDir/.generated/`（默认 `figma-plugin-dist/.generated/`），经 esbuild 插件注入，不会改写 `node_modules` 内的包文件，多消费方可并行构建。
+
+消费方项目自身映射数据的具体缺口（未映射的组件、置信度较低的属性推断），记录于消费方 `figma-mapping-table.json` 的 `unmappedNotes` / `note` 字段中，不属于本文档的追踪范围。

package/figma-mapping.config.example.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "复制这份文件到你自己项目的根目录，改名 figma-mapping.config.json，改成真实的组件目录。内容都是项目内相对路径，可以直接提交 git —— 不用像绝对路径那样每人一份本地覆盖。",
+  "codeConnect": {
+    "paths": {
+      "components": "components"
+    },
+    "importPaths": {
+      "components/*": "@/components/*"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "mini-figma-code-connect",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local Code Connect for Figma Professional — 无 Org 也能做确定性的 f(instance) → snippet。",
+  "license": "MIT",
+  "author": "elaine.ma <elaine.ma@aspendigital.co>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elainema0215/mini-figma-code-connect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elainema0215/mini-figma-code-connect/issues"
+  },
+  "homepage": "https://github.com/elainema0215/mini-figma-code-connect#readme",
+  "keywords": [
+    "figma",
+    "code-connect",
+    "figma-plugin",
+    "design-to-code",
+    "figma-mappings"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.html",
+    "scripts",
+    ".claude/skills/mini-code-connect",
+    "figma-mapping.config.example.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/runtime/index.ts",
+    "./build": "./scripts/build-plugin.mjs",
+    "./generate-registry": "./scripts/generate-registry.mjs",
+    "./install-skill": "./scripts/install-skill.mjs",
+    "./scaffold-manifest": "./scripts/scaffold-manifest.mjs",
+    "./scaffold-plugin": "./scripts/scaffold-plugin.mjs"
+  },
+  "bin": {
+    "figma-mapping": "scripts/figma-mapping/index.mjs",
+    "figma-code-connect-build": "scripts/build-plugin.mjs",
+    "mini-code-connect-install-skill": "scripts/install-skill.mjs",
+    "mini-code-connect-scaffold-manifest": "scripts/scaffold-manifest.mjs",
+    "mini-code-connect-scaffold-plugin": "scripts/scaffold-plugin.mjs"
+  },
+  "scripts": {
+    "build": "node esbuild.config.mjs",
+    "watch": "node esbuild.config.mjs --watch",
+    "pretypecheck": "npm run generate:registry && npm run generate:mapping-table",
+    "typecheck": "tsc --noEmit",
+    "generate:registry": "node scripts/generate-registry.mjs 'figma-mappings/**/*.figma.ts' src/runtime/registry.generated.ts",
+    "generate:mapping-table": "node -e \"import('./scripts/copy-mapping-table.mjs').then(m => m.copyMappingTable({ cwd: process.cwd(), mappingTablePath: 'figma-mapping-table.json', outFile: 'src/main/mapping-table.generated.json' }))\"",
+    "demo": "esbuild src/dev/demo.ts --bundle --platform=node --format=esm --outfile=dist/demo.mjs --log-level=warning && node dist/demo.mjs",
+    "preexport": "npm run generate:registry",
+    "export": "esbuild src/dev/export.ts --bundle --platform=node --format=esm --outfile=dist/export.mjs --log-level=warning && node dist/export.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "devDependencies": {
+    "@figma/plugin-typings": "^1.109.0",
+    "typescript": "^5.6.3",
+    "@types/node": "^22.10.0"
+  }
+}

package/scripts/build-plugin.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import * as esbuild from 'esbuild';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isCliEntrypoint } from './is-cli-entrypoint.mjs';
+import { generateRegistry } from './generate-registry.mjs';
+import { copyMappingTable } from './copy-mapping-table.mjs';
+
+const PACKAGE_ROOT = path.resolve(fileURLToPath(import.meta.url), '../..');
+const MAIN_ENTRY = path.join(PACKAGE_ROOT, 'src/main/code.ts');
+const UI_ENTRY = path.join(PACKAGE_ROOT, 'src/ui/ui.ts');
+const UI_HTML = path.join(PACKAGE_ROOT, 'src/ui/ui.html');
+
+/**
+ * 把生成文件写到消费方 outDir/.generated/，再用 esbuild 插件把源码里的
+ * `./registry.generated` / `./mapping-table.generated.json` 指过去。
+ * 不能再写进包自己的 src/：npm/pnpm 装到 node_modules 后该目录只读或被多项目共享。
+ */
+function consumerGeneratedPlugin(genDir) {
+  const registryFile = path.join(genDir, 'registry.generated.ts');
+  const mappingTableFile = path.join(genDir, 'mapping-table.generated.json');
+  return {
+    name: 'consumer-generated',
+    setup(build) {
+      build.onResolve({ filter: /(?:^|[\\/])registry\.generated(?:\.ts)?$/ }, () => ({
+        path: registryFile,
+      }));
+      build.onResolve({ filter: /(?:^|[\\/])mapping-table\.generated\.json$/ }, () => ({
+        path: mappingTableFile,
+      }));
+    },
+  };
+}
+
+/**
+ * 把这套 Code Connect 插件引擎打包成消费方能装进 Figma 的 dist/code.js + dist/ui.html。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd 消费方项目根目录（.figma.ts 文件按这个目录算相对路径）
+ * @param {string} opts.mappingsGlob 相对 cwd 的 glob，例如 'mappings/**\/*.figma.ts'
+ * @param {string} [opts.mappingTablePath] 相对 cwd 的 figma-mapping-table.json 路径，
+ *   用于插件面板"下载 mapping-table.json"按钮（下载文件名仍为 mapping-table.json）；不存在时下载空数组
+ * @param {string} [opts.outDir] 相对 cwd 的产物目录，默认 'dist'
+ * @param {boolean} [opts.watch] watch 模式
+ */
+export async function buildPlugin({
+  cwd,
+  mappingsGlob,
+  mappingTablePath = 'figma-mapping-table.json',
+  outDir = 'dist',
+  watch = false,
+}) {
+  const absOutDir = path.resolve(cwd, outDir);
+  const genDir = path.join(absOutDir, '.generated');
+  const registryOut = path.join(genDir, 'registry.generated.ts');
+  const mappingTableOut = path.join(genDir, 'mapping-table.generated.json');
+
+  const { count } = generateRegistry({
+    cwd,
+    mappingsGlob,
+    outFile: registryOut,
+    typesImport: null,
+  });
+  console.log(`[build-plugin] 扫到 ${count} 条映射（${mappingsGlob}）`);
+  const { found } = copyMappingTable({ cwd, mappingTablePath, outFile: mappingTableOut });
+  if (!found) console.log(`[build-plugin] 没找到 ${mappingTablePath}，下载按钮会给空数组`);
+
+  const generatedPlugin = consumerGeneratedPlugin(genDir);
+
+  const inlineUi = {
+    name: 'inline-ui',
+    setup(build) {
+      build.onEnd(async (res) => {
+        if (res.errors.length) return;
+        const js = res.outputFiles
+          ? res.outputFiles[0].text
+          : await readFile(path.join(absOutDir, '.ui.tmp.js'), 'utf8');
+        const html = await readFile(UI_HTML, 'utf8');
+        await mkdir(absOutDir, { recursive: true });
+        await writeFile(path.join(absOutDir, 'ui.html'), html.replace('/*__UI_JS__*/', () => js));
+        console.log(`[inline-ui] ${path.join(outDir, 'ui.html')} 已更新`);
+      });
+    },
+  };
+
+  const codeOpts = {
+    entryPoints: [MAIN_ENTRY],
+    bundle: true,
+    format: 'iife',
+    target: 'es2020',
+    outfile: path.join(absOutDir, 'code.js'),
+    logLevel: 'info',
+    plugins: [generatedPlugin],
+  };
+
+  const uiOpts = {
+    entryPoints: [UI_ENTRY],
+    bundle: true,
+    format: 'iife',
+    target: 'es2020',
+    outfile: path.join(absOutDir, '.ui.tmp.js'),
+    logLevel: 'warning',
+    plugins: [inlineUi, generatedPlugin],
+  };
+
+  if (watch) {
+    const a = await esbuild.context(codeOpts);
+    const b = await esbuild.context(uiOpts);
+    await Promise.all([a.watch(), b.watch()]);
+    console.log('[build-plugin] watching...');
+    return { watching: true };
+  }
+
+  await esbuild.build(codeOpts);
+  await esbuild.build(uiOpts);
+  return { watching: false };
+}
+
+// 允许直接当 CLI 跑：node scripts/build-plugin.mjs <mappingsGlob> [--out dist] [--watch]
+if (isCliEntrypoint(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const watch = args.includes('--watch');
+  const outIdx = args.indexOf('--out');
+  const outDir = outIdx !== -1 ? args[outIdx + 1] : 'dist';
+  const mappingsGlob = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--out');
+  if (!mappingsGlob) {
+    console.error('用法: node scripts/build-plugin.mjs <mappingsGlob> [--out dist] [--watch]');
+    process.exit(1);
+  }
+  await buildPlugin({ cwd: process.cwd(), mappingsGlob, outDir, watch });
+}

package/scripts/copy-mapping-table.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 把消费方的 figma-mapping-table.json 复制到指定 outFile，供 code.ts 经 esbuild
+ * 插件静态 import。默认由 build-plugin 写到消费方 outDir/.generated/，不再写进包的 src/。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd 消费方项目根目录
+ * @param {string} opts.mappingTablePath 相对 cwd 的映射表路径（默认 figma-mapping-table.json）；不存在时写一个空数组
+ * @param {string} opts.outFile 生成文件的绝对路径
+ */
+export function copyMappingTable({ cwd, mappingTablePath, outFile }) {
+  const src = path.resolve(cwd, mappingTablePath);
+  const content = fs.existsSync(src) ? fs.readFileSync(src, 'utf8') : '[]\n';
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, content);
+  return { found: fs.existsSync(src) };
+}