一次 opencode + OpenPencil MCP 协同解析 .fig 文件的踩坑实录

前言

设计师给了一份 .fig 文件，我需要让 opencode 这个 AI 编程 Agent 自己读懂设计稿并产出前端代码。
听起来简单，做起来一波三折——本文把整个过程记录下来，包括为什么最终选了 @open-pencil/mcp 而不是最初的 fig2json，以及路上踩到的所有坑。

环境约束：Windows 11、Node 22（opencode 强制依赖）、无 MSVC、无 MinGW。

一、需求拆解

目标链路：

设计师的 .fig 文件  →  opencode AI 读懂  →  生成组件代码（React/Vue/HTML）

需要解决三个问题：

  1. 解析：.fig 是 Figma 私有二进制格式（Kiwi schema + Zstd + ZIP），没人公开 spec
  2. 集成：解析结果要被 opencode 的 LLM 上下文消费
  3. 部署：必须能跑在我的环境里（Node 22，Windows）

二、方案调研——四条候选路径

我先列出了所有可能的方向，并行调研：

路径 工具 优点 缺点
A kreako/fig2json (Rust CLI) 纯离线、无账号、一行命令 要 Rust + 链接器（MSVC/MinGW）
B Figma 官方 Remote MCP 官方、写回画布、Code Connect 只支持 Figma URL，不支持 .fig 本地文件
C open-pencil/mcp (Node MCP) 100+ 工具、本地优先 需要跑 OpenPencil 桌面 app
D Open Design (Node 桌面) 全工作流、品牌系统 强制 Node 24，与 Node 22 冲突

我当时选了 Path A (fig2json) ——最直接，一个 CLI 转 JSON 就完事。

三、Path A 的崩溃与路径切换

fig2json 在 GitHub Releases 上没有预编译的 Windows 二进制。要装就只能 cargo install fig2json。

我兴冲冲打开终端：

npm install -g @open-pencil/mcp  # ← 先装着备用的
cargo install fig2json

然后——

error: linker `link.exe` not found

我的环境既没有 MSVC 也没有 MinGW。要编译 fig2json 得先装 Visual Studio Build Tools（几个 GB）。

这是个真实的工程痛点：Rust 生态在 Windows 上的"开箱即用"远不如 macOS/Linux。一个 5MB 的 CLI 工具，要装几 GB 的 toolchain 才能编译，不值。

决策：Pivot 到 Path C（@open-pencil/mcp）

回头看 MCP 包：

$ npm install -g @open-pencil/mcp
added 166 packages in 1m

$ npm view @open-pencil/mcp engines
# (empty — 没声明 Node 版本约束)

$ node -e "require('@open-pencil/mcp/package.json').version"
# 0.13.2

纯 Node.js 包。没有任何 native module。Node 22 直接跑。

代价：需要 OpenPencil 桌面 app 一起跑（~7MB）。但这是 Tauri 应用，跨平台、单文件、双击就开——比装 Visual Studio Build Tools 友好得多。

四、最终架构

自然语言指令

stdin/stdout JSON-RPC

ws://127.0.0.1:7601

解析二进制

👤 用户调用
'用 D:/design.fig 实现落地页'

🛠️ opencode (Node 22 + LLM)
• 内置 Skill: figma-fig-to-code
• • SKILL.md 触发: description 含 .fig / Figma
• MCP client (stdin/stdout JSON-RPC)

@open-pencil/mcp server (Node 22)
• 106 个工具: list_pages, get_jsx, get_node ...
• 通过 WebSocket 与桌面 app 通信

🖥️ OpenPencil 桌面 app (Tauri, ~7MB)
• 真正的 .fig 二进制解析器 (Kiwi + Zstd + WASM)

📄 designer.fig

五、实施步骤

1. 安装 MCP server

npm install -g @open-pencil/mcp

2. 注册到 opencode

编辑 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "open-pencil": {
      "type": "local",
      "command": ["node", "D:/App/nodejs/node_modules/@open-pencil/mcp/dist/stdio.mjs"],
      "environment": { "OPENPENCIL_MCP_ROOT": "D:/App" },
      "enabled": true
    }
  }
}

3. 启动 OpenPencil 桌面 app

去 https://openpencil.dev/ 下载安装，启动。

4. 创建全局 Skill

在 ~/.config/opencode/skills/figma-fig-to-code/ 下创建：

figma-fig-to-code/
• - SKILL.md                       # 触发条件 + 工作流
• - references/
•   • - flex-mapping.md            # Figma auto-layout → CSS Flexbox
•   • - tool-quickref.md           # 106 个工具速查
•   • - output-stacks.md           # React/Vue/Svelte 输出模板
• - scripts/
    • - install.ps1                # Windows 一键装
    • - install.sh                 # Unix 一键装
    • - full-e2e.mjs               # 端到端验证脚本

SKILL.md 的 frontmatter：

---
name: figma-fig-to-code
description: Use this skill when the user provides a Figma `.fig` file ... triggers on phrases like "实现这个 figma", "解析 .fig", "design to code"...
license: MIT
metadata:
  author: your-name
  version: "1.3.0"
---

description 里的触发关键词是 skill 能被自动加载的关键——opencode 的 loader 是基于关键词匹配的。

5. 重启 opencode 让配置生效

⚠️ 重要：opencode 的配置是启动时加载的，热更新不支持。改了 opencode.json 必须退出当前 session 重启。

6. 验证

opencode mcp list
# ✓ open-pencil connected

opencode debug skill | grep figma
# ✓ figma-fig-to-code

六、真实端到端测试

光有"连通"不算数。我用一个真实的 PPT 模板 .fig（7.6MB）跑全流程：

[probe] target: D:/App/figma-test/ppt模版浅色.fig
[OK 1852ms] open_file              ← 真的打开了 7.6MB 的文件
[OK 276ms]  list_pages             ← 列页面
{
  "current": "Page 1",
  "pages": [
    { "id": "0:3",   "name": "Page 1" },
    { "id": "0:520", "name": "Internal Only Canvas" }
  ]
}
[OK 5ms]    get_components
[OK 4ms]    list_fonts

✅ 你的 .fig 文件真的能识别——MCP 链路全打通，返回了真实的 page ID。

七、踩到的坑（决策日志）

我在 SKILL.md 里专门维护了 ## Decision log，记录 4 条关键决策：

D1 — 为什么不走 fig2json（最初的 Plan A）

Rust + MSVC 装不上 → 改 MCP。未来若 Rust/MSVC 装好，fig2json 仍值得重评——更简单。

D2 — 为什么 Node 22 兼容是硬约束

opencode 跑 Node 22。Open Design 要 Node 24 被排除了。MCP 路径是唯一不冲突的选项。

D3 — 为什么用 MCP 而不用 CLI

@open-pencil/cli 的源码第一行就是 Bun.XXX，Node 跑直接 Bun is not defined。装 Bun 会破坏 D2 的"不引入新运行时"原则。

D4 — 为什么不直接用 @open-pencil/core 编程 API

v0.13.2 有个无限递归 bug（io/formats/pen/read.js:288），任何非空 fixture 都触发 Maximum call stack size exceeded。MCP 走桌面 app 内部的 C++/WASM 路径，不受影响。

八、还存在的坑（实事求是）

验证项 结果 说明
MCP ↔ OpenPencil app RPC ✅ 通过 ws://127.0.0.1:7601
open_file / list_pages / get_jsx ✅ 通过 在真实 .fig 上返回真数据
端到端"opencode 读 .fig" ✅ 通过 在 SKILL 工作流设计层可走通
全自动（opencode AI 自主决策调工具） ❌ 待测 需在重启 opencode 后实测
get_page_tree 在 7.6MB 大文件上慢 ❌ 慢 设计就是分区域收敛，不是问题

九、经验总结

  1. Node 生态的"开箱即用"远超 Rust 在 Windows 上——一个 npm 包 60 秒装好，一个 Rust 工具要装几个 GB toolchain 才能编译。优先 Node。
  2. MCP 是 AI 工具集成的最佳模式：本地 stdio + 远程 WebSocket，AI 直接当工具用，比写胶水代码强多了。
  3. Skill 的 description 决定可发现性："Use this skill when..." 第三人称 + 触发关键词，opencode 才能自动加载。
  4. 配置文件改完必须重启——opencode 不热重载，省得以为是 bug。
  5. 上游 bug 不绕道就踩坑——遇到 @open-pencil/core 的栈溢出别浪费时间在 Node 上重试，直接用 MCP 路径。
  6. 诚实记录决策：如果路径变了没告诉用户，6 个月后的你会骂 6 个月前的自己。SKILL.md 的 ## Decision log 是这种"反自我"工具。

附：完整 skill 已开源

本项目所有代码（含 SKILL.md、scripts、references）已开源：

GitHub: https://github.com/1648298170/opencode-figma-skill

直接 gh repo clone 1648298170/opencode-figma-skill 或 git clone 就能用。

如果本文对你有帮助，欢迎 Star / Fork / 提 Issue。也欢迎在评论区分享你的 .fig → 代码 自动化经验。

# MCP
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

C语言指针进阶补充6：动态内存管理、mem系列内存函数、复杂指针声明，一次补齐指针的“三大盲区“

avatar MCP技术社区

【无标题】

LiveCam Hook by sbg 功能定制。LiveCam Hook插件开发。ios逆向hook插件开发。抖音无人直播录播方案。

avatar MCP技术社区

DeerFlow2.0 框架架构02：Lead Agent 任务总调度

本文深入探讨了DeerFlow 2.0的核心模块——Lead Agent，强调其作为任务调度中枢的设计理念，而非简单的聊天入口。Lead Agent专注于任务分发与协调，通过配置驱动和策略模式实现高灵活性，支持动态模型切换（如Qwen、OpenAI等）和中间件扩展。其架构分为三层（入口层、调度层、扩展层）和四大组件（配置解析、模型管理、中间件、任务调度），采用策略模式统一模型调用接口，并通过极简（

avatar MCP技术社区