夜雨聆风OpenPencil 值得你深度关注
在设计工具领域，Figma 长期占据主导，但其云端订阅模式、插件生态的局限性，以及对本地优先、AI 深度集成和全编程接口的需求，催生了开源替代品。OpenPencil（GitHub: open-pencil/open-pencil）正是其中最激进且务实的一个： AI 原生（AI-native）、Figma 兼容的开源设计编辑器，不仅支持原生 .fig文件的读写 round-trip，还内置 100+ AI 工具、提供完整的 CLI + MCP + Vue SDK 可编程层、P2P 实时协作，以及极致的本地优先体验（~7MB 桌面应用，无需账号、无需后端）。
一、核心功能
OpenPencil 的功能围绕“设计 + AI + 编程 + 协作”四大支柱构建，所有功能均基于统一的核心引擎。
1. 文件支持与 Figma 兼容性
●原生打开/读写 .fig文件（Figma 官方格式）和 .pen文档。
●Kiwi 二进制 codec实现高保真 round-trip（ZIP + Zstd 压缩，194 个 schema 定义，~390 字段/NodeChange）。
●支持 Figma 剪贴板互操作（copy & paste nodes between apps）。
●导出为 .fig（指定 page）、PNG/JPG/WEBP/SVG、JSX（Tailwind 或 OpenPencil 风格）。
●局限性（务实提醒）：部分特性为 partial 支持（椭圆弧、复杂文本样式、变量绑定、masks、patterns、variable fonts 等）；prototyping（连接、触发、动画、present mode）、comments、version history、branching、Dev Mode annotations、Code Connect、共享库等暂不支持或 round-trip 受限。适合大多数 UI/设计系统工作，但复杂 FigJam 或高保真原型可能需手动调整。
2. AI 原生设计生成（100+ Tools）
●快捷键 ⌘J（mac）或 Ctrl+J打开内置聊天。
●90~100+ 内置工具：创建/修改形状、设置 fills/strokes、auto-layout 管理、组件/变量操作、布尔运算、token 分析、资产导出等。
●Bring Your Own Key：支持 OpenRouter、Anthropic、OpenAI、Google AI、Z.ai、MiniMax 或兼容 endpoint，无后端、无账号。
●AI 可直接操作画布（create shapes, set properties, analyze clusters 等）。
3. 全栈可编程层（CLI + MCP + eval + SDK）
OpenPencil 区别于其他设计工具的核心竞争力。
CLI (@open-pencil/cli)：
●●●bash npm install -g @open-pencil/cli
# 或 bun add -g @open-pencil/cli
核心命令（支持 --json机器可读输出）：
●openpencil tree design.fig/ --page/ --depth
●openpencil find design.fig --type TEXT --name "Button"
●openpencil query design.fig "//FRAME[@width < 300]"（XPath，支持 name、width、cornerRadius、text 等属性）
●openpencil export design.fig -f jsx --style tailwind（输出示例见后）
●openpencil lint design.fig --preset strict --rule color-contrast
●openpencil analyze colors/typography/spacing/clusters design.fig（带使用频率直方图、组件聚类）
●openpencil variables design.fig
●openpencil eval design.fig -c "figma.currentPage.children.length" -w（完整 Figma Plugin API 执行，可写回文件）
●省略文件参数时通过 RPC（WebSocket port 7601）控制正在运行的桌面 App（适合自动化脚本）。
MCP Server (@open-pencil/mcp，90+ Tools)：
●暴露几乎所有设计操作给 AI Agents（Claude Code、Cursor、Windsurf、Codex、Gemini CLI 等）。
●传输：stdio（推荐 Claude Code 等）或 HTTP（openpencil-mcp-http，默认 localhost:3100/7600）。
●工具分类：Document（open/save/new）、Read（get_selection、get_page_tree、find_nodes）、Create（create_shape、render JSX、create_component/instance）、Modify（set_fill/stroke/layout/effects/text/update_node）、Structure（delete/clone/reparent）、Analyze/Export 等。
●安全：通过 OPENPENCIL_MCP_ROOT环境变量限定文件操作范围。
●设置示例（Claude Code）：
●●●bash npm install -g @agentclientprotocol/claude-agent-acp
# ~/.claude/settings.json 添加 permissions
然后在 App 内 Ctrl+J 选择 Claude Code provider。
Vue SDK (@open-pencil/vue)：
●Headless 组件 + composables（useI18n、useOkHCL 颜色模型、useVariables CRUD、useVariablesTable、useViewportKind 等）。
●用于将 OpenPencil 引擎嵌入自定义应用，或构建领域特定编辑器（workflow-specific editing surfaces）。
4. 组件、Variants 与设计系统
●创建 Component / Component Set，支持 Variants 分组。
●实例插入本地资产、inspector 切换 Variants、⌥⌘Bdetach instance。
●变量（color/number/string/boolean）管理 + 模式/别名。
5. 设计转代码与分析
●JSX + Tailwind 导出（可 diff，用于版本控制）。
●Token 提取与聚类分析（颜色使用频率直方图、重复结构检测）。
●Lint 规则（naming、layout、accessibility、contrast）。
6. 实时协作（P2P）
●WebRTC（Trystero）+ Yjs CRDT，无服务器、无账号。
●光标、presence、follow mode。
●分享链接即可共同编辑。
7. 布局、矢量、文本与其他 UI 功能
●Auto Layout + CSS Grid：Yoga WASM（自定义 fork 支持 Grid），gap/padding/alignment/track sizing。
●矢量：Pen 工具（Bézier）、Vector Networks、布尔运算、flatten、text/stroke outline。
●文本：完整编辑（IME 支持）、字体搜索、per-character 样式。
●效果：Drop/Inner Shadow、Layer/Background/Foreground Blur。
●画布：无限 workspace、Space + drag / 中键 / H 工具平移、⌘+scroll 缩放、profiler HUD（FPS、CPU/GPU 时间、draw calls、node count）。
●Sections（自动收养重叠 sibling）、Frames（clip content）、丰富 context menu + 键盘快捷键（几乎所有操作都有对应快捷键）。
二、安装方法
推荐方式（macOS）：
●●●bash brew install openpencil
或从 Releases 下载（Tauri v2 打包，macOS/Windows/Linux）。
Web/PWA：直接访问 https://app.openpencil.dev（无需安装，适合快速试用或演示）。
CLI：
●●●bash npm install -g @open-pencil/cli
# 或 bun（推荐，项目主要使用 Bun）
bun add -g @open-pencil/cli
MCP Server：
●●●bash npm install -g @open-pencil/mcp
openpencil-mcp # stdio 模式
openpencil-mcp-http # HTTP 模式
三、从源码安装与构建
项目为 Bun + Vite + Tauri v2 monorepo。
●●●bash git clone https://github.com/open-pencil/open-pencil.git
cd open-pencil
bun install # 安装所有依赖（包括 WASM 模块）
开发运行：
●bun run dev→ 编辑器 Web 版（默认 :1420）
●bun run docs:dev→ 文档站（:5173）
构建桌面 App：
●需要 Rust + Tauri CLI。
●典型流程：先构建前端（bun run build），再 cd desktop && tauri build（或 root 脚本封装 bun run tauri:build）。
●desktop/ 目录包含 tauri.conf.json、Cargo.toml、build.rs等标准 Tauri 配置。
构建/发布 CLI 与 MCP：
●cd packages/cli && bun build（或对应脚本生成 bin）
●类似处理 packages/mcp
●可使用 npm link或打包发布。
测试：
●bun run test:unit（764+ unit tests，bun:test）
●bun run test/ bun run test:update（188+ E2E Playwright 视觉回归）
●bun run test:figma（Figma CDP 参考测试）
●Linting: bun run lint（oxlint）、bun run format（oxfmt）、bun run typecheck（tsgo）
源码结构速览：
●packages/core/：引擎核心（scene-graph/、renderer.ts、layout.ts、kiwi/ codec、vector/、undo.ts 等）
●packages/vue/：Headless SDK + composables
●packages/cli/& packages/mcp/：可编程层
●src/：Vue 前端 App（components、stores、composables）
●desktop/：Tauri Rust 包装
●tests/：大量单元 + E2E + 视觉回归测试
构建产物小巧（~7MB 桌面 App 得益于 WASM 按需与 Tauri 优化）。
四、高效使用方法与实战场景
日常设计流程：
1.打开 App 或 Web → ⌘J 让 AI 先搭框架（“Create a SaaS dashboard with sidebar and metrics cards”）。
2.手动精细调整（矢量、文本、variants）。
3.使用 CLI analyze clusters发现可提取的组件模式。
4.export -f jsx --style tailwind转代码，或用 SDK 嵌入内部工具。
CLI 自动化 workflow（CI / 设计系统维护）：
●●●bash # 批量 lint + token 审计
openpencil lint design.fig --preset strict --json > lint-report.json
openpencil analyze colors design.fig --limit 20 --json
# 导出所有页面为高质图片
for page in $(openpencil pages design.fig --json | jq -r '.[].name'); do
openpencil export design.fig -f png -s 2 --page "$page" -o "exports/$page.png"
done
AI Agent 驱动设计修改：
●安装 MCP + Claude Code → 在聊天中直接说 “把所有 primary buttons 改成 #6750A4 并统一 cornerRadius=8”
●Agent 通过 MCP tools 实时修改画布或 .fig 文件。
●结合 eval执行复杂 Figma Plugin API 脚本。
协作场景：
●分享链接 → 多人 P2P 编辑（无延迟、无服务器成本）。
●适合远程团队或开源设计贡献。
性能与调试：
●打开 Profiler HUD 查看 FPS、draw calls、GPU 时间。
●大文档用 tree --depth 2+ XPath 精准定位，而非全加载。
●批量操作用 CLI/MCP 而非手动。
Edge Cases 处理：
●复杂文本或 mask 不完美 roundtrip → 先在 OpenPencil 完成主要工作，再必要时回 Figma 微调。
●需要 prototyping → 当前暂不支持，建议结合其他工具。
●大团队共享库 → 暂不支持，适合个人/小团队或内部设计系统。
五、技术原理与架构深度剖析
本地优先、统一引擎、可编程一切、AI 作为一等公民。
Scene Graph：采用 flat Map<string, Node>+ parentIndex实现 O(1) 查找与高效遍历（优于传统树递归）。支持 18+ NodeType（FRAME、RECTANGLE、TEXT、VECTOR、BOOLEAN_OPERATION、COMPONENT、INSTANCE、SECTION 等），完整 transform、paints、effects、cornerRadius（独立圆角 + smoothing）、layout props 等。
渲染管线：Skia CanvasKit WASM（GPU 加速），支持渐变、图像填充、多种效果。离屏渲染用于高质量导出。Profiler 集成 WebGL timer query。
布局引擎：Yoga WASM（fork 增加 CSS Grid 支持），将 Figma auto-layout 属性映射到 flex/grid 语义，支持 hug/fill/fixed sizing、wrap 等。增量失效优化。
文件格式：.fig= ZIP(Zstd) + Kiwi 二进制消息。Codec 处理 194 schema，实现 Figma 剪贴板兼容。导出时生成缩略图。
协作：Trystero（WebRTC P2P，MQTT signaling）+ Yjs CRDT，实现无服务器实时同步。光标与 presence 低开销。
Undo/Redo：Inverse command pattern + snapshot，拖拽等操作批量合并。
JSX 作为中间表示：AI、CLI、export 统一使用声明式 <Frame w={320} flex="col" gap={16} ...><Text ... /></Frame>，便于 diff 与版本控制。
MCP/CLI 架构：工具用 Zod schema 定义，通过 stdio/HTTP 暴露。CLI 使用 RPC 连接桌面 App。Eval 在沙箱中执行 Figma Plugin API（figma global）。
整体分层：
●Core Engine（packages/core）：场景图、渲染、布局、codec、vector networks。
●UI Layer（src/ + Vue）：响应式面板、工具栏、快捷键、i18n。
●Programmable Layer：CLI（命令行接口）、MCP（Agent 接口）、Vue SDK（嵌入式）。
●Collaboration & AI：独立但深度集成。
让“同一个引擎”同时服务桌面 App、CLI 脚本、AI Agent 和自定义嵌入编辑器，极大提升复用与扩展性。
OpenPencil 是一个 本地优先、可深度编程、AI 原生的设计基础设施。特别适合：
●追求隐私/本地 workflow 的独立设计师与小团队。
●需要设计 token 自动化、批量导出、CI 集成的开发者。
●构建 AI Agent 驱动设计工具的开发者（MCP + SDK 是杀手级特性）。
●想贡献或基于引擎定制专用编辑器的人（Vue SDK + core 模块化）。
上手建议：先用 Web 版或 Homebrew 安装体验 AI 聊天与基本编辑；再装 CLI/MCP 尝试自动化；
