Figma → Android Compose 转换器

Figma → Android Compose 转换器 能够将 Figma 中的任意画框一键转化为生产级 Jetpack Compose / Kotlin Android 工程，同时提供视觉回归检测与 LLM 智能修复能力。项目以 Node CLI、VS Code 扩展及 MCP/HTTP 服务三种形态交付，全面覆盖本地单机与远程协同工作流。

English README

快速上手：npm run convert "https://www.figma.com/design/<fileKey>/<name>?node-id=<nodeId>"

✨ 核心特性

• 🎯 像素级精准输出：基于确定性 JSON → Compose 代码生成，输出 MainScreen.kt、各组件 Composable 函数以及 output/ 下可直接编译的完整 Android 工程。
• 🖼️ 视觉回归流水线：通过 compose-render/ 中无头 Compose Multiplatform Preview（ImageComposeScene + @Preview）渲染截图，与 Figma 原图进行 SSIM + ResNet18 特征级对比，输出 0–100% 匹配分数。VS Code 向导中截图验证已默认开启。
• 🧪 AI 智能修复：开启后，匹配分数偏低的组件可自动调用 LLM（LLM_API_KEY / LLM_BASE_URL / LLM_MODEL）完成布局与样式的智能修复。
• 🧩 VS Code 深度集成：配套扩展在编辑器侧栏提供四步向导——导出生成、自动优化、按要求调整、截图验证——并实时展示流水线进度，支持可选的远程 MCP/HTTP 分体工作流。
• 🌐 MCP / HTTP 服务：mcp-service/ 对外暴露 HTTP 与 MCP 接口，便于与支持 Model Context Protocol 的工具链无缝集成。

🧱 Monorepo 结构

| 路径 | 包名 / 职责 | | :--- | :---------- | | . | 根包 figma-to-compose（CLI 入口、模板、预构建的 dist/） | | extension/ | VS Code 扩展 figma-to-compose-vscode（客户端工作流） | | plugin/ | Android Studio / IntelliJ 插件（Java UI + 内嵌 TypeScript 远程 runner） | | mcp-service/ | figma-convert-mcp-service HTTP + MCP 服务 | | compose-render/ | 无头 Compose Multiplatform Preview 截图渲染器 | | scripts/ | Python 视觉对比及 RL 辅助脚本（visual_compare.py、visual_fix_rl.py） | | src/android-template/ | 复制到 output/ 的 Android Gradle 工程模板 |

🛠️ 流水线工作原理

从工程化视角看，本流水线是一组可复现的、分阶段的确定性变换：Figma 矢量语义 → 结构化布局图 → Compose 代码 → 渲染图像 → 定量相似度指标。可选的修复层（LLM 或 Agent CLI）叠加在确定性核心之上，不侵入代码生成路径本身。

分体架构总览

远程 / MCP 工作流的核心设计是职责分离——客户端负责与 Figma 交互，服务端负责代码生成与像素评分。下图以 两列 形式呈现，║ 为硬分隔符：左侧为本仓库客户端代码，右侧为本仓库服务端代码。跨列箭头指向本仓库定制的 mcp-service MCP/REST API，而非 Figma 官方 MCP。

语言标注： 图中运行时以 «书名号» 标识，与下方图例表格中的 粗体 语言名对应。

    ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
    │  FIGMA → COMPOSE — 远程分体架构（路径均位于本 monorepo 内）                                     │
    └──────────────────────────────────────────────────────────────────────────────────────────────┘

                [ Figma Cloud ]               FIGMA_API_KEY 仅在客户端持有（v2 convert 服务端无需 Figma token）

    ╔═════════════════════════════════════════════════╦════════════════════════════════════════════════╗
    ║  客户端                                          ║  服务端                                        ║
    ║  extension/ · plugin/ · compose-render/         ║  mcp-service/ · scripts/ · mcp-service/src/    ║
    ╠═════════════════════════════════════════════════╬════════════════════════════════════════════════╣
    ║                                                 ║                                                ║
    ║  ┌───────────────────────────────────────────┐  ║  ┌───────────────────────────────────────────┐ ║
    ║  │ ① «TypeScript»                            │  ║  │ ② «Node» + «TypeScript»                   │ ║
    ║  │     extension/ (VS Code)                  │  ║  │     mcp-service/src/*.ts                  │ ║
    ║  │     plugin/src/remote-pipeline-node.ts    │  ║  │     定制 MCP/HTTP · jobs/JOBS_DIR         │ ║
    ║  │     Figma REST · 上传 bundle · SSE        │──║─►│     （非 Figma 官方 MCP）                  │ ║
    ║  └──────────────────┬────────────────────────┘  ║  │     产出 «Kotlin» + Android 资源          │ ║
    ║                     │                           ║  └──────────────────┬────────────────────────┘ ║
    ║                     │                           ║                     │                          ║
    ║                     │  GET artifact.zip         ║  ┌──────────────────▼───────────────────────┐  ║
    ║                     │  jvm/ 供 CMP 渲染         ◄──┤Kotlin 工程 zip (android/·jvm/·res/)       │  ║
    ║                     │                           ║  │服务端打包 · …/artifact.zip                │  ║
    ║                     │                           ║  └──────────────────┬───────────────────────┘  ║
    ║                     │                           ║                     │                          ║
    ║  ┌──────────────────▼────────────────────────┐  ║  ┌──────────────────▼────────────────────────┐ ║
    ║  │ ③ «Java» + «Gradle»                       │  ║  │ ④ «Python»                                │ ║
    ║  │     compose-render/                       │  ║  │     scripts/visual_compare.py             │ ║
    ║  │     plugin/（Gradle 渲染步骤）             │  ║  │     （mcp-service 调用本仓库）             │ ║
    ║  │     JDK 17+（推荐 21+）PNG 截图            │──║─►│     SSIM · ResNet18 · 可选 RL             │ ║
    ║  └──────────────────┬────────────────────────┘  ║  └──────────────────┬────────────────────────┘ ║
    ║                     │                           ║                     │                          ║
    ║                     │                           ║  ┌──────────────────▼────────────────────────┐ ║
    ║                     │                           ║  │ ⑤ «Node» + «TypeScript»                   │ ║
    ║                     │                           ║  │     mcp-service/src/（agent runner）      │ ║
    ║                     │                           ║  │     通过 ACP 拉起 agent CLI 子进程         │ ║
    ║                     │                           ║  │     ACP (Agent Client Protocol) NDJSON    │ ║
    ║                     │                           ║  └──────────────────┬────────────────────────┘ ║
    ║                     │                           ║                     │                          ║
    ║                     └────────────◄──────────────┴─────────────────────┘                          ║
    ║     服务端完成 → artifact URL（convert zip 或 agent 变更文件 zip）                                 ║
    ║                                                                                                  ║
    ║  ┌───────────────────────────────────────────────────────────────────────────────────────────┐   ║
    ║  │ ⑥ 仅客户端：HTTP GET artifact / 合并产物 — IDE 端不运行 agent CLI                           │   ║
    ║  │    «TypeScript» + «Java» · plugin/ UI · 合并至 Android 模块                                │   ║
    ║  └───────────────────────────────────────────────────────────────────────────────────────────┘   ║
    ╚═════════════════════════════════════════════════╩════════════════════════════════════════════════╝

Agent 修复 vs 产物下载： Agent（步骤 ⑤）仅在服务端运行——Node 在 JOBS_DIR 下解包工程，通过 ACP（Agent Client Protocol）启动 agent CLI（Cursor 或 Qoder），产出变更 zip。IDE 端（⑥）不在本地运行 agent，仅轮询任务状态与事件，下载 artifact 并合并至当前工程模块。

| 步骤 | 侧 | 技术栈 | 路径（monorepo） | 说明 | | :-: | :-: | :-- | :-- | :-- | | ① | 客户端 | TypeScript | extension/、plugin/src/remote-pipeline-node.ts | 仅调用 Figma REST；拉取 bundle → gzip-json / HTTP 至远程 mcp-service | | ② | 服务端 | Node、TypeScript、Kotlin（输出） | mcp-service/src/ | 定制 MCP + REST + JOBS_DIR；/api/v2/convert-design 无需 FIGMA_API_KEY | | — | 服务端→客户端 | （Kotlin zip） | GET /api/v1/jobs/:id/artifact.zip | 服务端打包 android/·jvm/·res/；客户端下载 jvm/ 供本地 compose-render / CMP Preview | | ③ | 客户端 | Java、Gradle | compose-render/、plugin/ | JDK 17+（推荐 21+）无头 Compose 截图 → 上传对比 | | ④ | 服务端 | Python | scripts/visual_compare.py | SSIM + ResNet18 特征对比 | | ⑤ | 服务端 | Node、TypeScript | mcp-service/src/ | Agent 修复仅在此处运行：ACP 启动 agent CLI，写入 artifact.zip | | ⑥ | 客户端 | TypeScript、Java | plugin/、extension/ | 仅下载与合并：拉取 artifactUrl，工作站不运行 agent |

本地全流程（CLI / 单机模式）

本地运行 npm run convert 时，步骤 ①–④ 合并到同一台机器上：Node 拉取 Figma 数据、生成 Kotlin 代码、可选 compose-render 截图、Python 对比——也可由 CLI 跳过视觉回归环节。

| 步骤 | 说明 | | :--- | :--- | | 拉取与转换 | TypeScript：Figma REST → design.json；图片与 SVG 携带稳定 ID | | Drawable 处理 | TypeScript：SVG → VectorDrawable（+ PNG 兜底）；Gradle 安全命名 | | JSON → Compose | 确定性生成（Kotlin）：MainScreen.kt、各组件、output/ 下工程模板 | | 视觉回归 | 可选：Java / Gradle CMP 无头 Preview PNG（默认 FIGMA_RENDER_BACKEND=preview）对比 Figma；Python SSIM + ResNet18 | | 转换后 Agent 修复 | --agent 在代码生成后运行本地 Agent Fix CLI | | Gradle 工程 emit | src/android-template 壳；可选 --build / RUN_BUILD=1 执行 gradlew build |

端到端使用场景

• 纯 CLI — TypeScript CLI（npm run convert）+ Figma URL；全流程本地执行；输出至 output/。
• VS Code 本地 — 扩展与 CLI 行为一致，在仓库内运行核心流水线，Activity Bar 向导实时展示进度。截图验证（第 4 步）默认勾选。
• VS Code + MCP 分体 — 扩展上传 gzip-json 至 mcp-service；服务端返回 Kotlin/资源；本地 Java/Gradle compose-render/ + Python 对比回传评分。可选 Agent Fix 在服务端执行；扩展仅下载产物。
• Android Studio 插件 — 与 VS Code 分体模式一致：TypeScript runner 负责打包上传，Java UI 展示进度；Gradle 渲染在本地完成。Agent Fix 在 remote mcp-service（步骤 ⑤）执行；插件下载产物并合并——不在本地运行 agent CLI。

🚀 快速上手

1. 克隆仓库

   git clone <your-repository-url>
   cd <your-checkout-folder>

2. 安装依赖并构建 CLI

   npm install
   npm run build

3. 安装 Java 与 Python 运行环境

   • Java：JDK 17+（推荐 21+），供 compose-render/ 使用（详见下文）。
   • Python：3.10+，通过 pip install -e . 或 uv 安装 scripts 依赖。

4. 配置环境变量

   cp .env.example .env
   # 编辑 .env，填入 FIGMA_API_KEY 及可选的 LLM_* 变量

5. 转换 Figma 画框

   npm run convert "https://www.figma.com/design/<fileKey>/<name>?node-id=<nodeId>"

   也可通过环境变量或 .env 中的 FIGMA_URL 简化调用：

   npm run convert link   # 简写：自动读取 FIGMA_URL
   npm run convert        # 未传 URL 参数时同样使用 FIGMA_URL

   省略协议前缀的 URL 同样有效（如 www.figma.com/design/...）。

CLI 入口说明： npm run convert 与 npm run convert:single 均运行 dist/index.js（经由 scripts/run-convert.mjs）。传入单个 Figma URL 时走完整单帧流水线；传入两个及以上 URL（或附加 --multi）则自动路由至共享多帧 emit。纯转换向导演示清单参见 extension/DEMO.md。

⚙️ 环境要求

| 依赖 | 版本 | 用途 | | :--- | :--- | :--- | | Node.js | 18+ | CLI、VS Code 扩展、MCP 服务 | | JDK | 17+ 必需（推荐 21+） | Gradle、AGP、CMP Preview 渲染（compose-render/） | | Python | 3.10+ | 视觉对比（scripts/） | | Figma API 密钥 | – | 通过 Figma REST API 拉取设计稿 | | 企业级 / OpenAI 兼容 LLM | – | 可选：命名推断（--naming / --rename）、资源语义翻译 |

Node 环境配置

推荐使用 Node.js 18+ LTS 版本。

npm install
npm run build          # 将 TypeScript 编译至 dist/，供 npm run convert 调用

CLI 入口为 node dist/index.js（即 npm run convert）。

Java 环境配置（compose-render/）

流水线通过 compose-render/ Gradle 工程中的 Compose Multiplatform Preview 渲染组件截图。运行依赖 JDK 17+（推荐 21+）及 Gradle Wrapper。默认渲染后端将源码暂存至 compose-render/build/figma-preview-sources/，classpath 上包含 ui-tooling + ui-tooling-preview。

compose-render/gradle.properties 默认设定 figmaComposeJavaVersion=21（可通过 FIGMA_TO_COMPOSE_JAVA_VERSION 或 FIGMA_TO_COMPOSE_JAVA_HOME 覆盖）。生成的 Android 工程仍以 Java 17 字节码为目标（src/android-template）。

macOS（Homebrew）— 推荐

brew install openjdk@21
export JAVA_HOME="$(/usr/libexec/java_home -v 21)"

最低版本（17）：

brew install openjdk@17

Linux

# Debian/Ubuntu — 推荐
sudo apt install openjdk-21-jdk

# 最低版本
sudo apt install openjdk-17-jdk

Windows

# winget — 推荐
winget install --id EclipseAdoptium.Temurin.21.JDK

# 最低版本
winget install --id EclipseAdoptium.Temurin.17.JDK

指定 Gradle 使用的 JDK（Android Studio 内置 JBR 在 17+ 时同样可用）：

# .env 或 shell 环境变量
FIGMA_TO_COMPOSE_JAVA_HOME=C:/Program Files/Eclipse Adoptium/jdk-21.x.x-hotspot

验证安装（Unix shell 或 Git Bash）

cd compose-render
./gradlew --version
# JVM 版本应为 21+（或至少 17）

验证安装（Windows PowerShell）

cd compose-render
.\gradlew.bat --version

快速冒烟测试（仓库根目录，仅编译，适合 CI）

编译 compose-render Kotlin 代码（不执行 renderScreenshot；仍需 compose-render/settings.gradle.kts 中配置的 Maven 仓库访问）。冒烟测试使用 compose-render/smoke-default-jvm/ 下的精简检入 bridge，不依赖上次本地 convert 产生的 tmp/compose-jvm。

npm run smoke:compose-render

技术栈版本：Kotlin 2.1.20 · Compose Multiplatform 1.8.2 · Gradle 8.10.2 · JVM 21（最低 17）。

Android SDK（output/ 工程的 Gradle 构建）

启用 Gradle 构建（--build、RUN_BUILD=1 或 SKIP_BUILD=0）时，output/ 下生成的工程会执行 gradlew build。默认情况下转换器跳过 Gradle 构建，仅输出/同步工程文件。

• 设置 ANDROID_HOME 或 ANDROID_SDK_ROOT 指向 SDK 根目录。代码生成时若检测到上述变量，工具会自动写入 output/local.properties 中的 sdk.dir=...。
• 或手动创建 output/local.properties：

sdk.dir=C:/Users/you/AppData/Local/Android/Sdk

Windows 下正斜杠路径同样有效。未配置 SDK 时，流水线跳过 Gradle 构建步骤并输出提示信息，而非因「0 Kotlin errors」报错退出。

Python 环境配置（scripts/）

视觉对比（SSIM + ResNet18）与可选的 RL 修复脚本位于 scripts/。

方式 A：pip install（推荐大多数用户）

cd scripts
pip install -e .

安装后提供两个控制台命令：

• figma-visual-compare — 执行视觉对比
• figma-visual-fix — 执行基于 RL 的视觉修复

方式 B：uv（极速、隔离环境）

安装 uv 后，首次执行视觉回归时 CLI 会从 scripts/ 调用 uv run，uv 将自动安装 Python 及所有依赖。

脚本与依赖

| 脚本 | 用途 | |------|------| | visual_compare.py | Figma 与 Compose 截图的 SSIM + 特征差异分析 | | visual_fix_rl.py | 可选的 RL 视觉修复（训练 / 应用） |

| 包 | 用途 | |----|------| | numpy | 图像数组运算 | | pillow | 图像加载与缩放 | | scikit-image | SSIM 结构相似度对比 | | scikit-learn | 差异区域聚类 | | torch + torchvision | ResNet18 特征提取 |

📦 根目录脚本参考

| 命令 | 说明 | | :--- | :--- | | npm run build | 构建根 TypeScript 至 dist/ | | npm run build:extension | 构建 VS Code 扩展工作区 | | npm run build:mcp | 构建 mcp-service 工作区 | | npm run build:all | 构建根、扩展与 mcp-service | | npm run build:plugin | 构建根 + Android Studio / IntelliJ 插件 | | npm run clean | 清理生成路径（output/、tmp/、dist/、compose-render/build/） | | npm run convert | 主 Figma → Compose CLI（传入 URL 参数或使用 FIGMA_URL） | | npm run convert:single | 强制单帧流水线 | | npm run convert:multi | 强制多帧共享 emit（--multi） | | npm run convert link | 简写模式：使用环境变量 / .env 中的 FIGMA_URL | | npm run smoke:compose-render | 使用检入的 smoke 源码编译 compose-render/ | | npm run verify:compose-render-bridge | 校验插件 bridge 副本与 src/lib/compose-render-bridge.ts 一致性 | | npm run verify:mirror-and-bridge | bridge 一致性 + vendored mirror 目录校验 | | npm run test | 运行扩展 Vitest 测试套件 | | npm run naming-inference | 运行完整命名推断流水线（见命名清理） | | npm run start:mcp | 启动 HTTP MCP 服务 | | npm run mcp:inspect | 通过 MCP Inspector 检查 stdio MCP 服务 |

CLI 选项

npm run convert <figma-url> [options]
npm run convert <url-1> <url-2> ...   （多帧共享 emit）
npm run convert link
npm run convert

Options:
  --output, -o <dir>   输出目录（默认：./output）
  --agent              代码生成后运行 Agent Fix（本地 agent CLI；依赖 monorepo + tsx）
  --build              代码生成后运行 Gradle build（或设置 RUN_BUILD=1）
  --naming, --rename   代码生成后执行命名推断（文件名/composable/drawable）
  --png1x              退出矢量优先：仅下载 PNG 1×（旧光栅模式）
  --png2x              额外下载矢量节点的 PNG 2× 光栅图（可选；或设置 FIGMA_PNG_2X=1）
  --drawable           已为 no-op（矢量优先已是默认行为）
  --full               启用逐组件视觉回归
  --help, -h           显示帮助信息

资源下载默认行为（矢量优先）：
  - 矢量节点默认下载 SVG（→ VectorDrawable XML）。位图填充与 SVG 导出失败的
    矢量节点自动回退为 PNG 1×。
  - 使用 --png2x 额外下载 2× 光栅图至 drawable-xxhdpi/。
  - 使用 --png1x 退出矢量模式，回到纯 PNG 1× 旧行为。

补充说明：
   - `link` 自动使用环境变量或 `.env` 中的 FIGMA_URL。
   - 未传入 URL 参数时自动使用 FIGMA_URL。
   - `www.figma.com/design/...` 会被自动补全为 `https://www.figma.com/design/...`。
   - IDE 进度输出：设置 FIGMA_CONVERT_JSON_PROGRESS=1，stderr 输出 NDJSON 阶段信息。
   - 仅扩展模式：FIGMA_CLI_MODE=compare-from-output | compose-screenshot-from-output
   - 转换时跳过视觉对比：FIGMA_CLI_SKIP_VISUAL_COMPARE=1
   - 渲染后端：FIGMA_RENDER_BACKEND=preview（默认，CMP）或 desktop（旧版 tmp/compose-jvm）
   - 无头渲染失败时中断 convert：FIGMA_COMPOSE_RENDER_STRICT=1（默认仅 warn）

output/ 下的 Android 工程

成功运行后，output/ 即为单模块 Android 应用（源自 src/android-template/），包含 build.gradle.kts、settings.gradle.kts、gradlew / gradlew.bat 及 src/main/...。包名与应用标签在代码生成时从 Figma 设计中提取。

-o / 输出根目录： 可传入任意目录路径。转换器将其视为 Android 模块 / 工程根目录——而非嵌套的 output/ 子目录（除非你刻意如此指定）。若目录为空或不构成有效的 Gradle emit 目标（缺少 build.gradle(.kts) + src/main/，且不含 settings.gradle* + app/ 结构），工具会先运行 android create（需配置 FIGMA_TO_COMPOSE_ANDROID_CLI / SDK），在该目录中初始化工程壳，随后拉取 Figma 并生成 Kotlin + src/main/res。转换后 Agent / --agent 仅在上述文件就绪后运行；命名清理仅在 --naming 或 --rename 时执行。

• JDK：Gradle / AGP 要求 17+（推荐 21+）。生成模板中的 Android 字节码目标版本仍为 17。

• 构建（Windows，仓库根目录）：

  cd output
  .\gradlew.bat build --no-daemon

  Unix：cd output && ./gradlew build --no-daemon。CLI 仅在传入 --build（或设置 RUN_BUILD=1）时运行 Gradle；默认跳过。

• Compose / compose-render：Android 端生成的 Kotlin 使用 painterResource(R.drawable.*) 引用资源。如需 JVM Preview 渲染，可设置 JVM_COMPOSE_OUTPUT=1，生成器将改用字符串形式的 painterResource（详见 .env.example）。

环境变量（.env）

# 必填
FIGMA_API_KEY=your_figma_api_key_here

# 可选 — 企业 LLM 配置（详见 src/llm-client.ts）
# LLM_API_KEY, LLM_BASE_URL, LLM_MODEL
# LITE_LLM_MODEL — 命名推断、资源重命名及中文 UI 标签优先使用此模型（回退至 LLM_MODEL）

# 可选 — IDE 进度输出
# FIGMA_CONVERT_JSON_PROGRESS=1
# 仅扩展内部模式
# FIGMA_CLI_MODE=compare-from-output | compose-screenshot-from-output
# 转换时跳过视觉对比
# FIGMA_CLI_SKIP_VISUAL_COMPARE=1
# 渲染后端选择
# FIGMA_RENDER_BACKEND=preview（默认）| desktop（旧版）
# compose-render 失败时中断 convert
# FIGMA_COMPOSE_RENDER_STRICT=1

# 可选 — 逐组件视觉回归（默认关闭）。CLI 推荐使用 --full。
# ENABLE_COMPONENT_VR=1

# 可选 — 代码生成后执行 Gradle build（默认关闭）。推荐使用 --build 或 RUN_BUILD=1。
# RUN_BUILD=1

# 可选 — compose-render 使用的 JDK（17+ 必需，推荐 21+）
# FIGMA_TO_COMPOSE_JAVA_HOME=C:/Program Files/Java/jdk-17
# FIGMA_TO_COMPOSE_JAVA_VERSION=21

# 可选 — 生成工程 Gradle build 所需的 Android SDK
# ANDROID_HOME=C:/Users/you/AppData/Local/Android/Sdk

完整变量列表见 .env.example。

输出结构

最终 output/（代码生成 + 可选 Gradle 构建成功后，或默认跳过构建时）：仅包含 Android 应用工程。

output/
├── build.gradle.kts, settings.gradle.kts, gradle.properties, proguard-rules.pro
├── gradlew / gradlew.bat / gradle/
├── local.properties                    可选 — 设置了 ANDROID_HOME 时自动生成
├── src/main/
│   ├── AndroidManifest.xml
│   ├── java/com/desaysv/<package>/   应用入口 + 生成的 Compose 代码
│   └── res/                            启动器图标 + 流水线 drawable（代码生成时复制）

转换过程中，生成的 Kotlin 写入 output/src/main/java/...。视觉回归所需的 JVM 适配 Preview 源码暂存于 compose-render/build/figma-preview-sources/（默认 FIGMA_RENDER_BACKEND=preview），旧版则位于 tmp/compose-jvm/（desktop）。流水线还会在 output/ 下写入 android/、images/、svg/、design.json 等中间产物，清理阶段会自动删除这些文件。

tmp/（仓库根目录——不在 output/ 内）

tmp/
├── compose-jvm/                         FIGMA_RENDER_BACKEND=desktop 时的旧版 JVM 源码
├── components_test/<ComponentName>/    figma + compose 截图及 comparison.json
├── full_screen/                         全屏视觉回归产物
├── mapping-report.json                  节点 → composable 覆盖率报告
├── pipeline-report.json                 代码生成摘要
└── gradle-build-last.log                可选：Gradle 构建失败日志尾部

获取 Figma URL

1. 在 Figma 中打开目标文件
2. 选中需要转换的画框
3. 右键 → Copy link to selection（复制选中项链接）
4. URL 格式如下：https://www.figma.com/design/ABC123/Name?node-id=1-23

URL 中必须包含 node-id 参数——转换器以单个画框为处理单元。

批量转换会根据链接目标自动展开：

| 链接目标 | 包含的屏幕 | |----------|------------| | 屏幕画框（显式链接） | 该画框整体，含叠加层兄弟节点（下拉菜单等），不拆分子节点 | | 叶子画框 | 仅该画框 | | Section | 该 Section 内直接子屏幕 | | 页面（Canvas） | 该页所有 Section 下的屏幕 | | 多个 URL | 各 URL 屏幕的并集 |

预览发现（不转换）：npm run convert -- --dry-run "<figma-url>"

项目布局概览

| 路径 | 职责 | |------|------| | 根目录 | Node 应用：npm install、npm run convert、src/（TypeScript） | | compose-render/ | Gradle 工程：编译生成的 Compose 代码、执行无头截图渲染（需 JDK 17+ / 推荐 21+） | | scripts/ | Python：visual_compare.py、visual_fix_rl.py；通过 pip install -e . 或 uv 安装 |

Compose 渲染原理

compose-render/ 是一个独立的 Kotlin/Gradle 工程，负责视觉回归中的无头截图渲染。

Preview 后端（默认）

当 FIGMA_RENDER_BACKEND=preview（CLI 与 VS Code 扩展的默认值）时：

1. 转换器将 JVM 适配的 Kotlin 源码暂存至 compose-render/build/figma-preview-sources/（含 components、screens 及 ComposeRenderBridge.kt）。
2. @Composable 函数名与文件名保持同步（如 SettingsCard.kt → fun SettingsCard），避免 unresolved reference 编译错误。
3. Gradle 使用 Compose Multiplatform Preview 工具链编译：
   • org.jetbrains.compose.ui:ui-tooling-preview
   • org.jetbrains.compose.ui:ui-tooling（无头渲染运行时 classpath）
4. MainKt 通过 JavaExec（renderScreenshot 任务）执行，利用 ImageComposeScene + LocalInspectionMode 渲染 @Preview 入口函数。

设置 FIGMA_RENDER_BACKEND=desktop 可切换至旧版 tmp/compose-jvm/ 布局。

修复已暂存的 Preview 源码

若已有的暂存目录因 composable 命名不一致出现 Unresolved reference 错误，可执行：

npm run build
node scripts/repair-preview-composable-names.mjs

随后在 compose-render/ 下重新运行 Gradle。全新转换会自动应用命名修复，无需手动干预。

Kotlin 2.1.20 · Compose Multiplatform 1.8.2 · Gradle 8.10.2 · JVM 21（最低 17）

SSL 说明

图片下载环节通过 NODE_TLS_REJECT_UNAUTHORIZED=0 禁用了 SSL 证书验证（在 npm 脚本中设置）。这在部分企业内网与代理环境下是必要的。

命名清理

转换完成后，可对资源文件与 composable 函数进行命名推断与清理。

# 1. 清理未引用资源（建议先 dry-run 预览）
node scripts/cleanup-unused-resources.mjs workspace --dry-run
node scripts/cleanup-unused-resources.mjs workspace

# 2. AI 命名推断（详见 run-naming-inference.ps1 或 npm run naming-inference）
# 流水线：inference-step1/2/3 → validate → apply-naming-mapping

# 3. 应用名称映射（建议先 dry-run 预览）
node scripts/apply-naming-mapping.mjs workspace --step all --dry-run
node scripts/apply-naming-mapping.mjs workspace --step all

也可从仓库根目录一键执行：

npm run naming-inference

相关文档

| 文档 | 说明 | | :--- | :--- | | README.md | 英文版 README | | extension/README.md | VS Code 扩展：本地/远程模式、向导、Agent Fix | | extension/DEMO.md | 纯转换向导演示清单 | | mcp-service/README.md | 分体客户端/服务端 HTTP + MCP 服务 | | plugin/README.md | Android Studio / IntelliJ 插件 | | scripts/README.md | Python 视觉对比脚本 |

许可证

MIT