mini-figma-code-connect 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +43 -129
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,13 +6,41 @@
6
6
 
7
7
  官方 Code Connect 与 Builder.io Design System Intelligence 均要求 Organization / Enterprise 订阅；团队当前为 Professional，相关 MCP 绑定工具不可用。本引擎在本地实现等价的「组件绑定 + 属性映射」：映射进消费方仓库、执行在 Figma 插件，不依赖云端 publish。插件沙箱无法读写本地代码，因此映射生成在沙箱外（agent / CLI）完成，再经构建打包进插件。
8
8
 
9
- 完整背景评估、引擎仓库本地开发、系统架构与核心实现见本地 [核心实现.md](核心实现.md)（不纳入版本控制）；方案对比见 [参考.md](参考.md)。
9
+ ---
10
+
11
+ ## 与官方 Code Connect 的差异
12
+
13
+ 以下差异均为刻意设计，而非未实现的功能缺口：
14
+
15
+ | | 官方 Code Connect | 本实现 |
16
+ |---|---|---|
17
+ | 订阅计划要求 | Organization / Enterprise，需 Full 或 Dev 席位 | 无要求，任意计划均可运行 |
18
+ | 模板存储位置 | 发布至 Figma 服务端（CLI `publish` 或 MCP `add_code_connect_map`） | 构建时打包进插件 |
19
+ | 模板执行方 | Figma 侧沙箱，在 Dev Mode / MCP 读取时执行 | 插件主线程，选中实例时执行 |
20
+ | 模板入口 | 模块顶层 `const instance = figma.selectedInstance` | `render(instance)` 函数参数 |
21
+ | 三行绑定注释 | 构建时解析 `// url= // source= // component=` | 保留注释供人工阅读，同时在 `meta` 字段中显式声明 |
22
+ | 组件发布状态要求 | 必须已发布 | 不要求，未发布时退回按组件名匹配 |
23
+ | SLOT 属性 | 支持 `getSlot()` | 未实现，仅支持 TEXT / BOOLEAN / VARIANT / INSTANCE_SWAP |
24
+ | 多框架支持 | 通过 `label` 枚举，单一设计组件可挂载多条并行映射 | 仅支持 React 一条 |
25
+ | 穷举校验 | 不提供，缺值静默 | 提供，`validate()` 自动对账 |
26
+ | 绑定关系判定方 | Figma 服务端存储的映射，或人工在 Code Connect UI 中手动指定 | agent 现场读取代码判断（mini-code-connect skill），或本地正则打分兜底 |
27
+
28
+ ---
29
+
30
+ ## 已知限制
31
+
32
+ - **尚未接入基于 REST API 与 Personal Access Token 的 schema 拉取能力**。该方案理论可行（通用 Figma REST API 不受 Code Connect 订阅限制），但目前唯一的数据来源仍是插件手动导出的 schema.json。
33
+ - **不提供跨消费方的数据新鲜度检查**。某个消费方代码库更新后，此前标记为 `guessed` / `unmatched` 的映射条目是否已可补全，需人工发起新一轮映射流程，引擎本身不做追踪。
34
+
35
+ > 构建时生成的 `registry.generated.ts` / `mapping-table.generated.json` 写在消费方 `outDir/.generated/`（默认 `figma-plugin-dist/.generated/`），经 esbuild 插件注入，不会改写 `node_modules` 内的包文件，多消费方可并行构建。
36
+
37
+ 消费方项目自身映射数据的具体缺口（未映射的组件、置信度较低的属性推断），记录于消费方 `figma-mapping-table.json` 的 `unmappedNotes` / `note` 字段中，不属于本文档的追踪范围。
10
38
 
11
39
  ---
12
40
 
13
41
  ## 消费方接入
14
42
 
15
- 面向将 `mini-figma-code-connect` 接入自身项目、并开始建立 Figma 组件映射的使用者。下文以 `trex-website/apps/rexy` 为例，所有命令默认在消费方子项目目录（例如 `apps/rexy`，而非 monorepo 根目录）下执行。
43
+ 面向将 `mini-figma-code-connect` 接入自身项目、并开始建立 Figma 组件映射的使用者。所有命令默认在消费方项目目录（含 `package.json` 的目录）下执行；若为 monorepo，请进入已安装该依赖的子包目录，勿在仓库根目录执行。
16
44
 
17
45
  ### 前置条件
18
46
 
@@ -36,27 +64,15 @@ pnpm add -D mini-figma-code-connect
36
64
  pnpm exec mini-code-connect-scaffold-plugin --id <manifest-id>
37
65
  ```
38
66
 
39
- `--id` 为必填参数，同一 Figma 账号内不可与已导入的其他插件重复（引擎仓库自身的 demo 插件 id 为 `simple-code-connect-demo`）。`--name` 为可选参数，默认值为 `"Mini Code Connect"`；仅当账号内同时安装了多个消费方插件、需要在 Figma 插件列表中加以区分时才需传入。
67
+ `--id` 必填，同一 Figma 账号内不可与已导入插件重复。`--name` 可选（默认 `"Mini Code Connect"`），多插件并存时用于区分。
40
68
 
41
- 该命令具备幂等性：已存在的文件不会被覆盖，重复执行不会影响后续的手动修改；如需强制重新生成，附加 `--force` 参数。执行内容如下：
69
+ 命令幂等：已有文件不覆盖；需重建时加 `--force`。会写入 skill、候选组件配置、manifest、构建脚本与 `package.json` scripts，并自动完成首次构建，之后可直接导入 Figma（步骤 4）。
42
70
 
43
- | 步骤 | 目标位置 | 说明 |
44
- |---|---|---|
45
- | 安装 skill | `<仓库根>/.claude/skills/mini-code-connect/`（若 `<仓库根>/.agents/skills/` 存在，同时写入一份） | 自动从当前目录向上查找 `.git` 所在的仓库根——pnpm monorepo 中子包目录并非仓库根，写入错误位置会导致 Claude Code 无法发现该 skill |
46
- | 候选组件目录配置 | `<cwd>/figma-mapping.config.json` | 默认假设组件位于 `<cwd>/components`，可通过 `--components <dir>` 调整 |
47
- | Manifest | `<cwd>/manifest.json` 与 `manifest.codegen.json` | `main`/`ui` 字段指向 `--out` 参数指定的目录（默认 `figma-plugin-dist`） |
48
- | 构建脚本 | `<cwd>/scripts/build-figma-plugin.mjs` | 调用引擎包导出的 `buildPlugin()` |
49
- | package.json | 新增 `scripts.figma:build` 与 `figma:watch` | 已存在的同名 script 不会被覆盖 |
50
- | `.gitignore` | 新增构建产物目录的忽略规则 | 已存在同一条规则则跳过 |
51
- | 首次构建 | `<cwd>/<outDir>/`（默认 `figma-plugin-dist/`） | 命令结束时自动执行一次构建，产出可直接导入 Figma 的插件——无需额外手动执行 `pnpm run figma:build` |
52
-
53
- 命令执行完毕即可直接导入 Figma（见步骤 4），无需再手动构建一次。
54
-
55
- 如需单独执行其中某一步（例如仅重新生成 manifest），可使用以下更细粒度的命令——`scaffold-plugin` 内部即调用这两者：
71
+ 仅需其中一步时：
56
72
 
57
73
  ```bash
58
- pnpm exec mini-code-connect-install-skill # 仅执行 skill 安装
59
- pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id> # 仅执行 manifest 生成
74
+ pnpm exec mini-code-connect-install-skill
75
+ pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id>
60
76
  ```
61
77
 
62
78
  #### 3. 按需调整候选组件目录
@@ -91,118 +107,16 @@ pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id> # 仅执行 m
91
107
 
92
108
  无 agent 可用时，`pnpm exec figma-mapping <schema.json>` 提供本地正则打分作为兜底方案（同样支持批量 schema 数组与 `--ai` 模式），判断准确度低于 agent 现场读取代码，但落盘规则保持一致。
93
109
 
94
- ### 命令参考
95
-
96
- | 命令 | 必填参数 | 作用 |
97
- |---|---|---|
98
- | `mini-code-connect-scaffold-plugin` | `--id` | 执行完整一次性脚手架（详见步骤 2） |
99
- | `mini-code-connect-install-skill` | 无 | 仅将 skill 复制至项目。`--root <path>` 显式指定仓库根，`--no-claude-mirror` 仅写入 `.agents/skills/`，`--force` 覆盖已存在内容 |
100
- | `mini-code-connect-scaffold-manifest` | `--id` | 仅生成 manifest.json 与 manifest.codegen.json。`--out <dir>` 指定产物目录 |
101
- | `figma-mapping` | `<schema.json>` | 本地正则打分 CLI，agent 缺席时的兜底方案。`--ai` 调用本机 `claude` CLI 以无头模式执行判断 |
102
-
103
110
  ### 常见问题
104
111
 
105
- #### `EACCES: spawn <command>`
106
-
107
- 通常由以下两种原因之一导致：
108
-
109
- 1. **脚本文件缺少可执行权限**。正常情况下不应出现（引擎仓库内相关脚本均为 `-rwxr-xr-x`）；若出现，问题大概率在引擎侧，应向引擎仓库反馈。
110
- 2. **bin 软链未生成**。引擎包的 `package.json` 新增了 `bin` 条目，但消费方项目在此后未重新执行安装，`node_modules/.bin/` 中缺少对应命令。执行以下命令刷新：
111
- ```bash
112
- pnpm install
113
- ```
114
-
115
- #### `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL`
112
+ 1. **Q:** 命令找不到 / `EACCES: spawn …`
113
+ **A:** 先在已安装依赖的目录执行 `pnpm install`，刷新 `node_modules/.bin`。若仍报错，多半是引擎包脚本权限问题，反馈给引擎仓库。
116
114
 
117
- 该错误通常表示 `pnpm exec` 是在 monorepo 根目录执行的，触发了对所有工作区包的递归遍历，其中部分包并未安装该依赖。切换至具体子项目目录（例如 `apps/rexy`）后重新执行。
115
+ 2. **Q:** `ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL`
116
+ **A:** 不要在 monorepo 根目录跑 `pnpm exec`；进入已安装 `mini-figma-code-connect` 的子包再执行。
118
117
 
119
- #### 与项目中已有的其他 Figma Code Connect 相关 skill/config 是否存在冲突
118
+ 3. **Q:** 和官方 Code Connect 会冲突吗？
119
+ **A:** 不会覆盖。本方案用 `mini-code-connect` skill 与 `figma-mapping.config.json`，官方用 `figma-code-connect` / `figma.config.json`；格式不兼容，勿混用。
120
120
 
121
- `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` 两个独立目录，互不覆盖。
122
-
123
- #### 修改 manifest 后 Figma 无变化
124
-
125
- `editorType`/`capabilities` 由 Figma 在插件注册时读取一次并缓存，修改 manifest 文件本身不会自动生效，必须在 Figma 中删除该开发插件并重新导入。构建产物（`figma-plugin-dist/` 下的 `code.js`/`ui.html`）则会在插件每次运行时重新读取，无需删除重导。
126
-
127
- ---
128
-
129
- ## 项目结构
130
-
131
- ```
132
- manifest.json Figma 插件清单（面板形态）——本仓库自身 demo 用，产物零映射
133
- manifest.codegen.json Figma 插件清单（Dev Mode Code 区形态）——同上
134
- figma-mapping.config.example.json 消费方接入时复制到自身项目根目录的配置模板
135
- esbuild.config.mjs 本仓库以 buildPlugin() 自举打包自身（零映射，用于验证引擎可用性）
136
-
137
- .claude/skills/mini-code-connect/
138
- └── SKILL.md 工作流的完整步骤定义，agent 依此执行——写入目标是消费方项目，而非本仓库
139
-
140
- scripts/figma-mapping/ 插件沙箱之外的工作流实现（CLI 以调用时的 cwd 作为 ROOT，即消费方项目根目录）
141
- ├── index.mjs CLI 入口：本地正则打分选取候选 + 交互确认，agent 缺席场景下的兜底方案
142
- ├── lib.mjs 读取消费方项目的 figma-mapping.config.json，扫描候选目录，提取组件信息并打分
143
- ├── scaffold.mjs 根据打分选中的候选生成 .figma.ts 内容
144
- ├── registry.mjs 重新生成 registry.generated.ts（薄封装，核心逻辑位于 scripts/generate-registry.mjs）
145
- └── ai-generate.mjs --ai 模式：调用本机 claude CLI 进行判断（存在 OAuth 阻塞风险，不推荐；agent 在场时应直接使用 skill）
146
-
147
- scripts/
148
- ├── build-plugin.mjs 导出 buildPlugin({cwd, mappingsGlob, mappingTablePath, outDir, watch})
149
- ├── generate-registry.mjs 导出 generateRegistry({cwd, mappingsGlob, outFile})，扫描 .figma.ts 生成 registry.generated.ts
150
- ├── copy-mapping-table.mjs 将消费方的 figma-mapping-table.json 复制至包自身 src/main/ 下，供 code.ts 静态引入
151
- ├── install-skill.mjs bin: mini-code-connect-install-skill
152
- ├── scaffold-manifest.mjs bin: mini-code-connect-scaffold-manifest
153
- ├── scaffold-plugin.mjs bin: mini-code-connect-scaffold-plugin —— 单条命令完成上述两项 + 候选目录配置 + 构建脚本 + package.json scripts
154
- └── is-cli-entrypoint.mjs 内部工具：判定"是否被直接作为 CLI 执行"（process.argv[1] 与 import.meta.url 的朴素比较通常不成立，详见文件内注释）
155
-
156
- src/
157
- ├── runtime/ 轻量级 Code Connect 运行时（与 Figma API 无关，可独立测试）——包的公开入口
158
- │ ├── index.ts 导出 defineTemplate/code/类型定义，消费方通过 `import { defineTemplate, code } from 'mini-figma-code-connect'` 引入
159
- │ ├── types.ts ResultSection / ComponentSchema / Template / InstanceLike
160
- │ ├── tagged.ts figma.code`...` 的简化实现：切分 section，展平嵌套结构
161
- │ ├── render.ts ResultSection[] 转字符串
162
- │ ├── define.ts defineTemplate()，用于类型收窄
163
- │ ├── registry.generated.ts 自动生成（已加入 .gitignore），由 scripts/generate-registry.mjs 扫描消费方 .figma.ts 产出；本地 build/typecheck 前生成
164
- │ └── registry.ts componentKey / componentName 到模板的查找；templates 数组从 registry.generated 转出
165
- ├── main/ 插件主线程（可访问 figma.* API）
166
- │ ├── code.ts 六步流水线与面板消息处理，详见核心实现.md
167
- │ ├── schema.ts 组件到属性 schema 的提取
168
- │ ├── handle.ts InstanceHandle：访问器层与递归执行
169
- │ ├── validate.ts Step 6 自检的自动化实现
170
- │ ├── mapping-table.generated.json 自动生成（已加入 .gitignore），构建时从消费方的 figma-mapping-table.json 复制
171
- │ └── messages.ts 主线程与 UI 间的消息类型定义
172
- ├── ui/ 插件面板
173
- │ ├── ui.html
174
- │ └── ui.ts
175
- └── dev/
176
- ├── demo.ts 独立示例模板，使用模拟实例渲染，不依赖 Figma 或任何消费方数据
177
- └── export.ts 生成 codeconnect.json
178
- ```
179
-
180
- ---
181
-
182
- ## 与官方 Code Connect 的差异
183
-
184
- 以下差异均为刻意设计，而非未实现的功能缺口：
185
-
186
- | | 官方 Code Connect | 本实现 |
187
- |---|---|---|
188
- | 订阅计划要求 | Organization / Enterprise，需 Full 或 Dev 席位 | 无要求，任意计划均可运行 |
189
- | 模板存储位置 | 发布至 Figma 服务端（CLI `publish` 或 MCP `add_code_connect_map`） | 构建时打包进插件 |
190
- | 模板执行方 | Figma 侧沙箱，在 Dev Mode / MCP 读取时执行 | 插件主线程，选中实例时执行 |
191
- | 模板入口 | 模块顶层 `const instance = figma.selectedInstance` | `render(instance)` 函数参数 |
192
- | 三行绑定注释 | 构建时解析 `// url= // source= // component=` | 保留注释供人工阅读，同时在 `meta` 字段中显式声明 |
193
- | 组件发布状态要求 | 必须已发布 | 不要求，未发布时退回按组件名匹配 |
194
- | SLOT 属性 | 支持 `getSlot()` | 未实现，仅支持 TEXT / BOOLEAN / VARIANT / INSTANCE_SWAP |
195
- | 多框架支持 | 通过 `label` 枚举，单一设计组件可挂载多条并行映射 | 仅支持 React 一条 |
196
- | 穷举校验 | 不提供，缺值静默 | 提供，`validate()` 自动对账 |
197
- | 绑定关系判定方 | Figma 服务端存储的映射，或人工在 Code Connect UI 中手动指定 | agent 现场读取代码判断（mini-code-connect skill），或本地正则打分兜底 |
198
-
199
- ---
200
-
201
- ## 已知限制
202
-
203
- - **尚未接入基于 REST API 与 Personal Access Token 的 schema 拉取能力**。该方案理论可行（通用 Figma REST API 不受 Code Connect 订阅限制），但目前唯一的数据来源仍是插件手动导出的 schema.json。
204
- - **不提供跨消费方的数据新鲜度检查**。某个消费方代码库更新后，此前标记为 `guessed` / `unmatched` 的映射条目是否已可补全，需人工发起新一轮映射流程，引擎本身不做追踪。
205
-
206
- > 构建时生成的 `registry.generated.ts` / `mapping-table.generated.json` 写在消费方 `outDir/.generated/`（默认 `figma-plugin-dist/.generated/`），经 esbuild 插件注入，不会改写 `node_modules` 内的包文件，多消费方可并行构建。
207
-
208
- 消费方项目自身映射数据的具体缺口（未映射的组件、置信度较低的属性推断），记录于消费方 `figma-mapping-table.json` 的 `unmappedNotes` / `note` 字段中，不属于本文档的追踪范围。
121
+ 4. **Q:** 改了 manifest，Figma 没变化？
122
+ **A:** `editorType` / `capabilities` 在导入时缓存。需在 Figma 里删掉该开发插件后重新导入。`figma-plugin-dist/` 下的 `code.js` / `ui.html` 每次运行都会重读，改构建产物不必重导。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mini-figma-code-connect",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
5
  "description": "Local Code Connect for Figma Professional — 无 Org 也能做确定性的 f(instance) → snippet。",
6
6
  "license": "MIT",