OpenPencil 完全指南：开源 .fig/.pen 设计编辑器的可编程 CLI、AI 与 MCP 实战

• 前端
• 桌面应用
• AI 应用
• MCP 服务

OpenPencil 是一个开源的 AI-native 设计编辑器，原生读写 Figma 的.fig文件与自有.pen格式，内置 AI 助手，并以「可编程工具包」的形态交付：headless CLI、XPath 查询、Figma Plugin API、MCP 服务器与 headless Vue SDK 一应俱全。阅读本文，你将掌握 OpenPencil 的安装方式、CLI 全命令实战（树形浏览、XPath 查询、多格式导出、HTML/CSS/Tailwind 导入、lint 与设计 token 分析）、AI/MCP 接入方案以及本地开发与桌面构建流程。

项目定位与现状

OpenPencil 的核心定位是「开源设计编辑器 + 可编程工具包」：既能像传统设计工具一样打开.fig和.pen设计文件（读/写原生 Figma 文件、在应用或系统文件浏览器中打开受支持的 Pencil 文档、在应用之间复制粘贴节点），又是一个完全可脚本化的引擎——headless CLI、XPath 查询、通过eval暴露的 Figma Plugin API、面向 AI Agent 的 MCP 服务器，以及面向桌面 Agent（Claude Code、Codex、Gemini CLI）的集成能力。

项目处于活跃开发状态（README 标注 "Active development. Usable today, with some rough edges"），License 为 MIT（见 LICENSE），版权归属 Danila Poyarkov 与 OpenPencil contributors。

安装方式

桌面应用 / Web 应用

• macOS（Homebrew）：brew install --cask openpencil
• 直接下载：从项目的 releases 页面下载对应平台安装包
• 免安装使用：直接使用 Web 应用版本

CLI

npm install -g @open-pencil/cli # 或：bun add -g @open-pencil/cli

从源码看，CLI 主入口定义在 packages/cli/src/index.ts，基于citty框架注册了analyze、convert、documents、eval、export、import、find、formats、fonts、info、lint、libraries、node、pages、query、selection、tree、variables共 18 个子命令，元信息为 "OpenPencil CLI — inspect, export, and lint OpenPencil design documents"。

核心能力总览

• 打开.fig和.pen文件：原生读写 Figma 文件，从应用或系统文件浏览器打开受支持的 Pencil 文档，跨应用复制粘贴节点。
• AI 构建设计：在聊天中描述需求，100+ 工具创建与修改节点；支持连接 OpenRouter、Anthropic、OpenAI、Google AI、DeepSeek、Z.ai、MiniMax 或兼容端点。
• 完全可编程：headless CLI、XPath 查询、通过eval使用 Figma Plugin API、面向 AI Agent 的 MCP 服务器，以及 Claude Code、Codex、Gemini CLI 的桌面 Agent 集成。
• Lint、转换与 token 提取：检查文档，lint 命名/布局/无障碍，在支持的格式间转换，分析颜色/排版/间距/聚类，提取设计 token。
• 组件与变体：创建可复用组件、将变体分组为组件集、以实例形式插入本地资源、在检查器中切换变体。
• 图片矢量化：通过 Recraft 或 fal.ai 将图片图层转换为可编辑矢量图层。
• 设计转代码导出：将选区导出为 JSX/Tailwind、生成 token 输出、将设计映射到面向组件化的代码工作流。
• Vue SDK 自定义编辑器：headless 组件与 composables，可将 OpenPencil 嵌入其他应用或构建特定工作流的编辑界面。
• 实时协作：基于 WebRTC 的 P2P 协作，无需服务器、无需账号，支持光标、在线状态、跟随模式。
• 自动布局与 CSS Grid：通过 Yoga WASM 实现 flex 与 grid 布局，支持 gap、padding、alignment、track sizing。
• 约 15 MB 桌面应用：基于 Tauri v2，支持 macOS、Windows、Linux，同时可作为 PWA 在浏览器中运行。

CLI 实战：不打开编辑器也能操作设计文件

1. 查看设计文件

浏览节点树、按名称或类型搜索、深入查看属性——全程无需打开编辑器：

openpencil tree design.fig openpencil find design.pen --type TEXT openpencil node design.fig --id 1:23 openpencil info design.fig

tree输出示例（页面 / section / frame 层级一目了然）：

[0] [page] "Getting started" (0:46566) [0] [section] "" (0:46567) [0] [frame] "Body" (0:46568) [0] [frame] "Introduction" (0:46569) [0] [frame] "Introduction Card" (0:46570) [0] [frame] "Guidance" (0:46571)

从 packages/cli/src/commands/tree.ts 的实现看，tree支持--page（指定页面名称，默认第一页）与--depth（最大深度，默认不限），并通过agentfmt格式化树形输出；info命令（packages/cli/src/commands/info.ts）则输出页数、总节点数、各页面节点直方图、类型统计与字体列表。

2. XPath 查询

使用 XPath 选择器按类型、属性和结构查找节点：

openpencil query design.fig "//FRAME" # 所有 frame openpencil query design.fig "//FRAME[@width < 300]" # 宽度小于 300px 的 frame openpencil query design.fig "//TEXT[contains(@name, 'Button')]" # 名称含 'Button' 的文本 openpencil query design.fig "//*[@cornerRadius > 0]" # 圆角节点 openpencil query design.fig "//SECTION//TEXT" # section 内的文本

packages/cli/src/commands/query.ts 中，query支持--page（页面名称，默认全部页面）与--limit（最大结果数，默认 1000），是自动化审查与批量改名的利器。

3. 导出

渲染为 PNG、JPG、WEBP、SVG、PDF、PPTX、HTML、JSX 或.fig——也可以将选区/页面导出为.fig，并在支持的格式间转换整个文档：

openpencil export design.fig # PNG openpencil export design.fig -f jpg -s 2 -q 90 # JPG at 2x, quality 90 openpencil export design.fig -f fig --page "Page 1" # 将页面导出为 .fig openpencil export design.fig -f jsx --style tailwind # Tailwind JSX openpencil export design.fig -f html --css tailwind # Tailwind HTML fragment openpencil export design.fig -f html --html standalone --assets external # HTML + assets openpencil convert design.pen output.fig # 文档格式转换 openpencil import page.html --css styles.css -o page.fig # HTML/CSS → 可编辑 .fig

根据 packages/cli/src/commands/export.ts 的参数定义，export的全部可选参数如下（含默认值与取值范围）：

实现细节：文件模式下，export通过@open-pencil/core/io的IORegistry完成写入与内容导出；HTML 导出走@open-pencil/dom-css的exportHTMLBundle，支持将入口文件与资源文件（assets目录）一并写出，控制台会打印Exported <path> (x KB)与资源文件数量。JSX/HTML/FIG/PPTX 格式目前仅在文件模式下可用，连接运行中应用时仅支持 PNG/JPG/WEBP/SVG/PDF（packages/cli/src/commands/export.ts 中exportViaApp的处理逻辑）。

4. HTML/CSS/Tailwind 导入

DOM/CSS 输入经过@open-pencil/dom-css处理，因此 HTML、手写 CSS 与 Tailwind 工具类都能变成可编辑的 OpenPencil 图层：

openpencil import card.html --css card.css -o card.fig openpencil import card.html --tailwind "flex flex-col gap-3 w-80 p-6 rounded-xl bg-white" -o card.fig

<div className="flex flex-col gap-4 p-6 bg-white rounded-xl"> <p className="text-2xl font-bold text-[#1D1B20]">Card Title</p> <p className="text-sm text-[#49454F]">Description text</p> </div>

packages/cli/src/commands/import.ts 展示了完整的导入参数体系：--css（CSS 文件）、--css-text（内联 CSS 文本）、--tailwind（Tailwind 工具类候选串）、--tailwind-file（包含工具类的文件）、--page-name（场景图页面名，默认DOM/CSS）、--format（输出格式fig或json，默认fig）。内部通过createHeadlessCSSRuntime创建无头 CSS 运行时，调用htmlToDesignDocument/tailwindHTMLToDesignDocument完成转换——这意味着你可以把设计稿从代码侧反哺回设计工具。

5. Lint 设计文件

从终端捕获命名、布局、结构与无障碍问题：

openpencil lint design.fig openpencil lint design.pen --preset strict openpencil lint design.fig --rule color-contrast openpencil lint design.fig --list-rules

packages/cli/src/commands/lint.ts 显示：lint使用@open-pencil/core/lint的createLinter，内置三个预设——recommended（默认）、strict、accessibility；--rule可指定单个/多个规则（可重复），--list-rules列出全部规则后退出。输出按error/warn/info三档着色，并附上节点路径、节点名与 ID 及修复建议（suggest）；若存在 error 级问题，进程以退出码 1 结束，便于接入 CI。lint 规则集的完整实现位于 packages/core/src/lint（共 24 个文件）。

6. 分析与提取设计 token

从终端审计整个设计系统——发现不一致、提取真实调色板、找出待抽取的组件：

openpencil analyze colors design.fig openpencil analyze typography design.fig openpencil analyze spacing design.fig openpencil analyze clusters design.fig openpencil analyze overlaps design.fig openpencil variables design.fig

输出示例（颜色直方图 + 组件聚类）：

#1d1b20 ██████████████████████████████ 17155× #49454f ██████████████████████████████ 9814× #ffffff ██████████████████████████████ 8620× #6750a4 ██████████████████████████████ 3967× 3771× frame "container" (100% match) size: 40×40, structure: Frame > [Frame] 2982× instance "Checkboxes" (100% match) size: 48×48, structure: Instance > [Frame]

analyze子命令族定义在 packages/cli/src/commands/analyze/index.ts，包含colors、typography、spacing、clusters、overlaps五个子命令。以 packages/cli/src/commands/analyze/colors.ts 为例：--limit（最多展示颜色数，默认 30）、--threshold（相似颜色聚类的距离阈值 0–50，默认 15）、--similar（展示可合并的相似色簇）。输出中每个颜色会标注是否来自变量（$variableName），并汇总 unique colors / from variables / hardcoded 数量——直接可用来发现「硬编码颜色 vs 设计变量」的比例。

7. 使用 Figma Plugin API 脚本化

eval提供完整的 Figma Plugin API。修改文件并写回：

openpencil eval design.fig -c "figma.currentPage.children.length" openpencil eval design.fig -c "figma.currentPage.selection.forEach(n => n.opacity = 0.5)" -w

packages/cli/src/commands/eval.ts 的实现细节：代码可通过-c/--code传入，也可用--stdin从标准输入读取；未以return开头的代码会被包装为return (async () => { ... })()执行。文件模式下会先loadDocument加载文档并populateWholeDocument铺开全量节点，再实例化@open-pencil/core/figma-api的FigmaAPI作为figma全局对象注入。-w/--write将变更写回原文件，-o/--output则写到另一个文件（两参数分别对应io.writeDocument('fig', graph)的结果落盘）。这为批量重命名、批量改样式、导出资产等自动化脚本提供了完全等同于 Figma 插件的编程接口。

8. 控制运行中的应用

当桌面应用正在运行时，省略文件参数即可——CLI 通过 RPC 连接并操作实时画布。这对自动化脚本、CI 流水线或需要与编辑器交互的 AI Agent 非常有用：

openpencil tree # 检查实时文档 openpencil export -f png # 截取当前画布 openpencil eval -c "figma.currentPage.name" # 查询编辑器

所有命令都支持--json输出机器可读结果。这种「文件模式 + 应用模式」的双模设计贯穿全部命令：如tree.ts中通过loadRPCData(args.file, 'tree', ...)实现——提供文件时走 headless 解析，省略文件时走 RPC 通道连接运行中的应用（isAppMode判定）。

AI 与 MCP

内置聊天

按⌘J（Windows/Linux 为CtrlJ）打开 AI 助手。它拥有 100+ 工具，可创建形状、设置填充与描边、管理自动布局、操作组件与变量、执行布尔运算、分析设计 token、导出资产。自带 API Key 即可连接 OpenRouter、Anthropic、OpenAI、Google AI、DeepSeek、Z.ai、MiniMax 或兼容端点——无后端、无账号。

需要注意的是：并非所有提供商都能在浏览器中正常工作，也并非所有模型都能正确流式输出工具调用。各提供商与模型的实测兼容性见 docs/programmable/byok-provider-compatibility.md（项目欢迎贡献实测结果）。

桌面编码代理

可在聊天面板中直接使用 Claude Code、Codex 或 Gemini CLI。Agent 连接到编辑器的 MCP 服务器，使用全部 100+ 设计工具。需要本地安装桌面应用与 Agent CLI。

Pi 也可作为可选的 AI SDK Harness 提供商：执行npm install -g @open-pencil/harness安装配套 CLI，然后在Settings → AI & agents中添加Pi模型配置。配套 CLI 单独安装，是为了避免为未启用 Harness 提供商的用户捆绑 JavaScript 运行时。

Claude Code 接入步骤：

1. 安装 ACP 适配器：npm install -g @agentclientprotocol/claude-agent-acp
2. 在~/.claude/settings.json添加 MCP 权限：

   { "permissions": { "allow": ["mcp__open-pencil__*"] } }

3. 打开桌面应用 →⌘J→ 在提供商下拉框中选择Claude Code

MCP 服务器

连接 Claude Code、Cursor、Windsurf 或任何 MCP 客户端，即可 headless 地检查、修改与导出设计文档，提供 100+ 工具。完整文档见 docs/programmable/mcp-server.md。

Stdio 模式（Claude Code、Cursor、Windsurf）：

npm install -g @open-pencil/mcp claude mcp add --scope user open-pencil -- openpencil-mcp

其他 MCP 客户端：

{ "mcpServers": { "open-pencil": { "command": "openpencil-mcp" } } }

HTTP 模式（脚本、CI）：

openpencil-mcp-http # macOS/Linux 上使用 Unix socket + http://127.0.0.1:7600/mcp

本地客户端会自动发现私有 Unix socket 并回退到 localhost TCP；在 macOS/Linux 上设置PORT=0可禁用 TCP。

文件访问控制：设置OPENPENCIL_MCP_ROOT可将文件操作（open_file、new_document、导出path参数）限定在指定目录内，默认值为当前工作目录。MCP 服务器的实现位于 packages/mcp/src（含 stdio 与 HTTP 传输、RPC 类型、认证等模块）。

AI Agent Skill

通过 skill 教你的 AI 编码代理使用 OpenPencil——检查设计、导出资产、分析 token、修改 .fig 文件：

npx skills add open-pencil/open-pencil

适用于 Claude Code、Cursor、Windsurf、Codex 以及任何支持 skills 的 Agent。Skill 定义与参考文档在 skills/open-pencil/SKILL.md 与 skills/open-pencil/references/design-authoring.md。面向文档感知型 Agent，文档站点还发布了llms.txt、llms-full.txt以及按页生成的 Markdown 文件（文档源位于 docs 目录）。

实时协作

分享链接即可实时共同编辑。无服务器、无账号——对等端通过 WebRTC 直接连接：

1. 点击右上方面板中的分享按钮
2. 分享生成的链接（app.openpencil.dev/share/<room-id>）
3. 协作者实时看到你的光标、选区与编辑
4. 点击某个协作者的头像即可跟随其视口

协作的技术底座是 Trystero（WebRTC P2P 信令）+ Yjs（CRDT 数据同步），相关实现可参考 src/app/collab（room、session、awareness、yjs-sync 等模块）。

为什么选择 OpenPencil

Figma 是一个封闭平台，主动对抗程序化访问：其 MCP 服务器只读；社区项目 figma-use 曾通过 CDP 实现完整的读写自动化，但 Figma 126 版本移除了 CDP 远程调试端口，使依赖它的工作流一夜失效。设计文件是专有二进制格式，只有其自家软件能完整读取——这意味着你的工作流可能在某次点版本发布时被破坏。

OpenPencil 的答案恰好相反：MIT 开源、原生读取.fig文件、每个操作都可脚本化、数据从不离开你的机器。产品方向与当前 Figma 兼容性差距可参考 docs/development/roadmap.md。

开发者指南

本地开发环境

bun install bun run dev:portless # Web 编辑器：https://open-pencil.localhost bun run dev # 直接 Vite 服务：http://localhost:1420 bun run tauri dev # 桌面应用（需要 Rust）

首次运行 Portless 会创建并信任本地 HTTPS 证书。链接的 Git worktree 会自动获得分支前缀 URL（如https://fix-ui.open-pencil.localhost），使并发开发服务器不会争抢 1420 端口；其开发 MCP 桥接通过对应的兄弟 URL（如https://fix-ui.mcp.open-pencil.localhost）暴露，并配有隔离的 TCP 端口与运行时 socket 文件。若本地路由或证书信任失败，运行bunx portless doctor排查。

也可以在任何兼容 Dev Container 的工具中打开仓库：容器固定 Bun 版本、安装 workspace 依赖并转发 1420 端口的直接 Web 编辑器，容器就绪后执行bun run dev即可。注意 Dev Container 支持 Web 编辑器、packages、CLI 与自动化检查；原生 Tauri 开发仍需宿主环境（桌面窗口与平台 WebView 依赖不在容器内提供）。

质量门禁

项目结构

packages/ scene-graph/ @open-pencil/scene-graph — 节点、图元、命中测试、复制/吸附/撤销 pen/ @open-pencil/pen — Pencil 文档格式辅助 kiwi/ @open-pencil/kiwi — Kiwi 运行时与底层 .fig 容器解析 fig/ @open-pencil/fig — .fig 归档、SceneGraph 转换、实例、元数据 core/ @open-pencil/core — 编辑器引擎、渲染器、布局、工具、RPC、文档 I/O dom-css/ @open-pencil/dom-css — HTML/CSS/Tailwind 转可编辑设计文档 vue/ @open-pencil/vue — headless Vue SDK cli/ @open-pencil/cli — headless CLI mcp/ @open-pencil/mcp — MCP 服务器（stdio + HTTP） harness/ @open-pencil/harness — 编码代理 Harness 会话配套 CLI docs/ 文档站点 src/ Vue 应用（编辑器外壳、AI、协作、文档 I/O） desktop/ Tauri v2 桌面应用（Rust + 配置） skills/ Agent skill（npx skills add open-pencil/open-pencil） tools/ 仓库工具：CI、发布、lint、测试基础设施 tests/ E2E、视觉与引擎测试

技术栈

桌面构建

需要 Rust 工具链与平台前置依赖（参照 Tauri v2 官方 prerequisites 指南）：

bun run tauri build

桌面端配置与源码位于 desktop 目录（tauri.conf.json、Rust 源码main.rs/window.rs/menu.rs等），Linux 打包清单见 desktop/linux/main.desktop。

许可证

OpenPencil 基于 MIT License 开源，Copyright (c) 2026 Danila Poyarkov and OpenPencil contributors。仓库还提供 CONTRIBUTING.md、SECURITY.md 与 CHANGELOG.md 供贡献者与使用者查阅。

• 前端
• 桌面应用
• AI 应用
• MCP 服务