OpenPencil 完整教學

1. 專案定位與核心價值

這是什麼？

OpenPencil 是一款 AI 原生的開源設計編輯器 (AI-native open-source design editor)，定位為 Figma 的開源替代方案。它不只是一個設計工具，更是一個 可程式化的設計平台 (programmable design platform)，讓設計工作能被 CLI 腳本、AI Agent、自動化 pipeline 所驅動。

為什麼值得關注？

核心價值

1. 設計民主化 (Design democratization)：MIT 授權，任何人都能使用、修改、分發
2. AI-first 設計工作流：用自然語言描述 → AI 自動建立 / 修改設計節點 (node)
3. 完全可程式化：每一個設計操作都能透過 CLI / API / MCP 執行
4. 跨平台：Web (PWA) + macOS + Windows + Linux，桌面 App 僅 ~7 MB (Tauri v2)
5. 即時協作：WebRTC P2P，零伺服器、零帳號

2. 安裝指南

方式一：macOS Homebrew（推薦）

1brew install openpencil

方式二：下載桌面 App

前往 Releases 頁面 下載對應平台安裝包（macOS / Windows / Linux）。

方式三：Web App（免安裝）

直接存取 https://app.openpencil.dev，無需安裝。

方式四：CLI 安裝

1# 使用 npm
2npm install -g @open-pencil/cli
3
4# 或使用 bun
5bun add -g @open-pencil/cli

方式五：MCP Server 安裝

1# 安裝 MCP package
2npm install -g @open-pencil/mcp
3
4# 加入 Claude Code
5claude mcp add --scope user open-pencil -- openpencil-mcp

方式六：開發環境建置

1git clone https://github.com/open-pencil/open-pencil.git
2cd open-pencil
3bun install
4bun run dev        # Dev server → localhost:1420
5bun run tauri dev  # 桌面 App（需 Rust 環境）

品質檢查：

3. 核心架構解析

系統架構圖

graph TB
    subgraph "使用者入口 (User Entry)"
        WebApp["Web App
(Vue 3 + PWA)"]
        Desktop["Desktop App
(Tauri v2 / Rust)"]
        CLI["CLI
(@open-pencil/cli)"]
        MCP["MCP Server
(@open-pencil/mcp)"]
        AIChat["AI Chat Panel
(⌘J)"]
    end

    subgraph "前端層 (Frontend Layer)"
        VueSDK["Vue SDK
(@open-pencil/vue)"]
        Components["UI Components
(Reka UI + Tailwind 4)"]
        EditorCanvas["Editor Canvas
(Vue composables)"]
    end

    subgraph "核心引擎 (Core Engine - @open-pencil/core)"
        SceneGraph["Scene Graph
(節點樹 / 屬性)"]
        Renderer["Renderer
(Skia CanvasKit WASM)"]
        Layout["Layout Engine
(Yoga WASM — flex + grid)"]
        Tools["AI Tools Registry
(100+ tools)"]
        IO["File I/O
(.fig / .pen / SVG / PNG)"]
        Text["Text Engine
(字型載入 / 渲染)"]
        Vector["Vector Engine
(路徑 / 布林運算)"]
    end

    subgraph "協作層 (Collaboration Layer)"
        Yjs["Yjs CRDT
(文件同步)"]
        Trystero["Trystero
(WebRTC P2P)"]
    end

    subgraph "AI 層 (AI Layer)"
        MultiProvider["Multi-Provider
(Anthropic / OpenAI / Google / OpenRouter)"]
        ToolAdapter["AI Tool Adapter
(schema + execution)"]
        ACP["Agent Client Protocol
(Claude Code / Codex / Gemini CLI)"]
    end

    subgraph "檔案格式 (File Format)"
        Kiwi["Kiwi Binary"]
        Zstd["Zstd 壓縮"]
        ZIP["ZIP 封裝"]
    end

    WebApp --> VueSDK
    Desktop --> VueSDK
    CLI --> SceneGraph
    MCP --> Tools
    AIChat --> MultiProvider

    VueSDK --> Components
    VueSDK --> EditorCanvas
    EditorCanvas --> SceneGraph

    SceneGraph --> Renderer
    SceneGraph --> Layout
    SceneGraph --> IO
    Tools --> SceneGraph
    ToolAdapter --> Tools

    MultiProvider --> ToolAdapter
    ACP --> MCP

    IO --> Kiwi
    Kiwi --> Zstd
    Zstd --> ZIP

    SceneGraph --> Yjs
    Yjs --> Trystero

    SceneGraph --> Text
    SceneGraph --> Vector

架構設計要點

1. Monorepo 分層：packages/core 是零 UI 依賴的純引擎，packages/vue 在其上提供 headless Vue composables，src/ 是含 UI 的完整 App
2. WASM 驅動渲染：Skia CanvasKit 編譯為 WASM，提供接近原生效能的 2D 渲染；Yoga 同樣 WASM 化處理排版
3. Scene Graph 核心：所有設計節點以樹狀結構管理，是 renderer、layout、I/O、AI tools 的共用資料層
4. Tool Registry 模式：AI 工具分為 core (~30 tools, ~3K schema tokens) 與 extended，依場景動態載入
5. P2P 協作：透過 Trystero 建立 WebRTC 連線 + Yjs CRDT 解衝突，完全無中心伺服器

4. 主要功能與 API 詳解

4.1 CLI 操作

瀏覽節點樹

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

XPath 查詢

 1# 所有 frame 節點
 2openpencil query design.fig "//FRAME"
 3
 4# 寬度小於 300px 的 frame
 5openpencil query design.fig "//FRAME[@width < 300]"
 6
 7# 名稱含 'Button' 的文字節點
 8openpencil query design.fig "//TEXT[contains(@name, 'Button')]"
 9
10# section 內的所有文字
11openpencil query design.fig "//SECTION//TEXT"

匯出

1openpencil export design.fig                           # PNG
2openpencil export design.fig -f jpg -s 2 -q 90        # JPG 2x, 品質 90
3openpencil export design.fig -f fig --page "Page 1"   # 匯出單頁為 .fig
4openpencil export design.fig -f jsx --style tailwind   # Tailwind JSX
5openpencil convert design.pen output.fig               # 格式轉換

設計 Lint

1openpencil lint design.fig
2openpencil lint design.pen --preset strict
3openpencil lint design.fig --rule color-contrast
4openpencil lint design.fig --list-rules

設計 Token 分析

1openpencil analyze colors design.fig
2openpencil analyze typography design.fig
3openpencil analyze spacing design.fig
4openpencil analyze clusters design.fig
5openpencil variables design.fig

Figma Plugin API (eval)

1# 讀取
2openpencil eval design.fig -c "figma.currentPage.children.length"
3
4# 修改並寫回
5openpencil eval design.fig -c "figma.currentPage.selection.forEach(n => n.opacity = 0.5)" -w

控制運行中的 App

1# 當桌面 App 執行時，省略檔案參數 → 透過 RPC 操作即時畫布
2openpencil tree
3openpencil export -f png
4openpencil eval -c "figma.currentPage.name"

所有指令都支援 --json 輸出格式。

4.2 MCP Server

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

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

HTTP 模式（腳本、CI）：

1openpencil-mcp-http   # 啟動於 http://localhost:3100/mcp

檔案存取範圍：設定 OPENPENCIL_MCP_ROOT 環境變數限制可操作目錄。

4.3 AI Chat

按 ⌘J（macOS）或 Ctrl+J 開啟 AI 助手面板，支援 provider：

• OpenRouter
• Anthropic (Claude)
• OpenAI (GPT)
• Google AI (Gemini)
• Z.ai
• MiniMax
• 任何相容端點

自帶 BYOK (Bring Your Own Key) 模式，無需後端、無需帳號。

4.4 Coding Agent 整合

桌面 App 可直接嵌入 Claude Code / Codex / Gemini CLI，agent 透過 MCP 存取全部 100+ 設計工具。

Claude Code 設定：

1# 安裝 ACP adapter
2npm install -g @agentclientprotocol/claude-agent-acp
3
4# 加入 MCP 權限
5# ~/.claude/settings.json:
6# { "permissions": { "allow": ["mcp__open-pencil__*"] } }

4.5 即時協作

1. 點右上角分享按鈕
2. 分享產生的連結 (app.openpencil.dev/share/<room-id>)
3. 協作者即時看到游標、選取範圍、編輯變更
4. 點擊對方頭像可跟隨其視角

技術實作：Trystero (WebRTC P2P) + Yjs (CRDT)，無中心伺服器。

4.6 Vue SDK

headless components + composables，用於將 OpenPencil 嵌入自訂應用程式。

1npm install @open-pencil/vue

SDK 文件：https://openpencil.dev/programmable/sdk/

5. 應用場景與實戰範例

場景一：CI/CD 中的設計品質門檻 (Design Quality Gate)

1#!/bin/bash
2# 在 CI pipeline 中自動 lint 設計檔
3openpencil lint design.fig --preset strict --json > lint-results.json
4ERRORS=$(jq '.errors | length' lint-results.json)
5if [ "$ERRORS" -gt 0 ]; then
6  echo "設計 lint 失敗：$ERRORS 個錯誤"
7  exit 1
8fi

場景二：AI Agent 自動生成 UI 設計

1# Claude Code 透過 MCP 建立設計
2claude mcp add --scope user open-pencil -- openpencil-mcp
3
4# 在 Claude Code 對話中：
5# "在目前的畫布上建立一個登入表單，包含 email 和 password 欄位，
6#  使用 Material Design 3 風格，圓角 16px"

場景三：設計 Token 自動提取

1# 從 Figma 檔案提取色彩 token
2openpencil analyze colors design.fig --json > colors.json
3
4# 提取 typography token
5openpencil analyze typography design.fig --json > typography.json
6
7# 產生 CSS variables / Tailwind theme
8openpencil variables design.fig

場景四：批次轉換與匯出

1# 將所有 .pen 檔轉為 .fig
2for f in *.pen; do
3  openpencil convert "$f" "${f%.pen}.fig"
4done
5
6# 批次匯出 PNG
7openpencil export design.fig -f png -s 2

場景五：協作式設計審查

1# 啟動 MCP HTTP server 供遠端 agent 操作
2openpencil-mcp-http
3
4# 多個 AI agent 同時透過 MCP 審查設計品質
5# Agent 1: lint 命名規範
6# Agent 2: 檢查 accessibility (color-contrast)
7# Agent 3: 分析 spacing 一致性

6. 資安掃描報告

掃描範圍

對 /tmp/open-pencil 的 TypeScript / JavaScript / Shell 原始碼進行關鍵字掃描，排除測試檔案與 node_modules。

發現項目

🟡 中風險：硬編碼 API Key

檔案：packages/core/src/constants.ts:341

1export const GOOGLE_FONTS_API_KEY = 'AIzaSyD1tYDR_dUEiV-Tw1vksEhZbUytgKW5pc8'

說明：Google Fonts API Key 被硬編碼在原始碼中。雖然 Google Fonts API key 通常僅限字型查詢用途、無法存取其他 Google 服務，且此 key 是 public repo 的一部分（MIT License），但硬編碼 API key 本身仍不符合最佳實務。

建議：若此 key 僅用於公開字型列表查詢（無 billing 風險），標注為 public key 即可；否則改用環境變數 (environment variable)。

🟡 中風險：CLI eval 指令

檔案：packages/cli/src/commands/eval.ts

1const result = await rpc('eval', { code })

說明：CLI 的 eval 指令允許執行任意 Figma Plugin API 程式碼。此功能是設計上的特性（Design by feature），用於腳本自動化。但當搭配 -w 旗標時會寫回檔案，需注意在 CI pipeline 中限制執行權限。

建議：在自動化環境中，設定 OPENPENCIL_MCP_ROOT 限制檔案操作範圍，避免 eval 影響非預期目錄。

🟡 中風險：Automation Auth Token

檔案：src/app/automation/bridge/server.ts

1const token = authToken ?? randomHex(32)

說明：自動化橋接 (automation bridge) 使用隨機 hex token 進行 WebSocket 認證。token 在 runtime 動態產生，長度 32 hex（128 bits），安全性可接受。但 WebSocket 連線本身是否經過 TLS 加密取決於部署環境。

建議：確認 WebSocket 連線在 production 環境使用 wss://（TLS）。

🟢 低風險：P2P 協作連線

檔案：src/app/collab/room.ts

說明：使用 Trystero 透過 MQTT signaling 建立 WebRTC P2P 連線。WebRTC 本身使用 DTLS 加密，資料傳輸安全。MQTT signaling 階段透過公開 relay，但只交換連線後設資料 (connection metadata)，不含設計內容。

建議：若處理機密設計檔，建議使用 self-hosted signaling server 取代公開 MQTT relay。

🟢 低風險：GitHub CI Token 使用

檔案：tools/pr-review-guidance/src/index.ts

說明：PR review guidance workflow 使用 GITHUB_TOKEN 環境變數進行 API 認證，遵循 GitHub Actions 標準實務，無硬編碼。

整體評估

總評：安全性良好。無高風險項目。主要風險點為設計上的功能特性（eval / automation），非安全漏洞。Google Fonts API key 為公開用途、影響有限。建議在 production 環境中注意 WebSocket TLS 與 eval 執行範圍限制。

7. FAQ 常見問題

Q1: OpenPencil 能完全取代 Figma 嗎？

A: 目前還不行。專案自述為「Active development, not ready for production use」。核心設計功能已可運作（shapes / text / components / auto layout / variants），但 Figma 的某些進階特性（interactive prototyping / advanced typography features）仍在 roadmap 中。請參考 官方 roadmap 了解相容性差距。

Q2: CJK (中日韓) 字型支援如何？

A: 已知存在問題。Issues #324 (CJK text rendering failures)、#291 (Korean text renders as boxes)、#346 (Chinese fonts display issue) 正在處理中。使用時建議自行放置字型檔於 public/ 目錄。

Q3: 可以在沒有網路的環境使用嗎？

A: 可以。桌面 App 和 PWA 都支援離線使用。AI 功能需要網路連接到 LLM provider，但基礎設計功能完全離線可用。協作功能需要 WebRTC 連線。

Q4: eval 指令安全嗎？

A: eval 執行 Figma Plugin API 程式碼，作用域限制在設計文件操作。搭配 -w 旗標會寫回檔案。在 CI 環境中建議設定 OPENPENCIL_MCP_ROOT 限制可操作目錄。

Q5: 如何在 Claude Code 中使用 OpenPencil？

A: 安裝 MCP package 後加入 Claude Code：

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

然後在 ~/.claude/settings.json 加入 "mcp__open-pencil__*" 權限。

Q6: 支援哪些檔案格式？

A: 讀取/寫入 .fig (Figma) 和 .pen (OpenPencil 原生格式)。匯出支援 PNG / JPG / WEBP / SVG / JSX。可在 .fig ↔ .pen 之間互轉。

8. 進階技巧與最佳實踐

8.1 XPath 進階查詢技巧

1# 找出所有圓角大於 0 的節點
2openpencil query design.fig "//*[@cornerRadius > 0]"
3
4# 組合條件：特定寬度範圍的 frame
5openpencil query design.fig "//FRAME[@width > 100 and @width < 500]"
6
7# 巢狀結構查詢
8openpencil query design.fig "//SECTION//FRAME//TEXT"

8.2 Design Token 工作流

1# 1. 分析色彩系統
2openpencil analyze colors design.fig --json | jq '.colors[:10]'
3
4# 2. 提取 design variables
5openpencil variables design.fig --json > tokens.json
6
7# 3. 匯出為 Tailwind theme
8openpencil export design.fig -f jsx --style tailwind

8.3 自動化腳本模式

當桌面 App 運行時，CLI 透過 RPC 連接至 live canvas：

1# 即時操作運行中的編輯器
2openpencil tree                               # 即時文件結構
3openpencil export -f png                      # 截圖目前畫布
4openpencil eval -c "figma.currentPage.name"   # 查詢編輯器狀態

8.4 MCP Server 多用途部署

1# 方式 1: stdio — 給 Claude Code / Cursor
2openpencil-mcp
3
4# 方式 2: HTTP — 給腳本與 CI
5openpencil-mcp-http   # http://localhost:3100/mcp
6
7# 限制檔案操作範圍
8export OPENPENCIL_MCP_ROOT="/path/to/designs"
9openpencil-mcp

8.5 Vue SDK 嵌入自訂應用

1import { createEditor } from '@open-pencil/vue'
2
3// 建立 headless editor instance
4const editor = createEditor({
5  // 設定選項
6})

SDK 提供 headless composables，可嵌入任何 Vue 3 應用程式中。

9. 整合進其他工作流

9.1 與 CI/CD Pipeline 整合

1# GitHub Actions 範例
2- name: Lint design files
3  run: |
4    npm install -g @open-pencil/cli
5    openpencil lint design.fig --preset strict --json > lint.json
6    
7- name: Export assets
8  run: |
9    openpencil export design.fig -f png -s 2

9.2 與 AI Coding Agent 整合

OpenPencil 的 MCP Server 可與多種 AI agent 搭配：

9.3 與 Design System 工具鏈整合

1# 提取 token → 產生 CSS variables
2openpencil variables design.fig > tokens.css
3
4# 分析設計一致性
5openpencil analyze clusters design.fig --json

9.4 AI Agent Skill 安裝

1# 為 AI coding agent 安裝 OpenPencil skill
2npx skills add open-pencil/skills@open-pencil

支援文件感知 (documentation-aware) agent 的 llms.txt 與 llms-full.txt。

10. 重點摘要 Checklist

快速評估

• MIT License，完全免費開源
• 原生讀寫 .fig 檔案（Figma 格式相容）
• 100+ AI 設計工具（MCP Server + CLI + eval API）
• 多家 LLM provider 支援（OpenRouter / Anthropic / OpenAI / Google AI）
• P2P 即時協作（WebRTC，無伺服器）
• 桌面 App ~7 MB（Tauri v2）
• Vue SDK 可嵌入自訂應用
• 設計 Lint / Token 分析 / XPath 查詢
• 設計轉程式碼（JSX / Tailwind）
• ⚠️ 尚未 production-ready（官方聲明）
• ⚠️ CJK 字型渲染仍有已知問題
• ⚠️ 協作功能穩定性待改善（#339, #342）

適合場景

11. 進一步閱讀

官方資源

• 官網
• 線上 Demo
• 文件站
• SDK 文件
• MCP 工具參考
• Roadmap
• llms.txt
• CONTRIBUTING.md

相關技術

• Skia CanvasKit — 渲染引擎
• Yoga Layout — Flex / Grid 排版引擎
• Tauri v2 — 桌面 App 框架
• Yjs — CRDT 協作框架
• Trystero — WebRTC P2P 程式庫
• MCP (Model Context Protocol) — AI Agent 工具協定

相關替代方案

• Figma — 商業設計工具（封閉平台）
• Penpot — 另一款開源設計工具（SVG-based，非 Figma 格式相容）
• Excalidraw — 開源白板工具（手繪風格）

12. 與 AI-Knowledge Template (AIKT) 的關聯性

概述

OpenPencil 作為一款 AI 原生、完全可程式化的設計編輯器，與 AIKT 的 22 層架構 (22-layer architecture) 有多處互補潛力。以下從三個核心 layer 分析整合可能性。

與 Layer 4 (graphify) 的互補性

graphify 將程式碼 / 文件轉為 knowledge graph (知識圖譜)，產出 GRAPH_REPORT.md + wiki/index.md。OpenPencil 可作為知識圖譜的 視覺化前端 (visualization frontend)：

整合路徑：graphify JSON → 腳本呼叫 OpenPencil CLI eval → 自動產生架構設計圖 → export -f png 輸出為 AIKT 文件素材。

與 Layer 7 (quarkdown) 的互補性

quarkdown 負責 Markdown → 排版精美的 HTML/PDF 文件。OpenPencil 可在兩個面向互補：

1. 設計素材產生器：quarkdown 文件中常需要架構圖、流程圖等圖片素材。OpenPencil 可作為 headless 圖片產生器 — 透過 CLI 建立設計 → 匯出 PNG/SVG → 嵌入 quarkdown 文件
2. Design Token 與 quarkdown 主題同步：OpenPencil analyze colors 提取的色彩系統可轉為 quarkdown CSS theme token，確保設計與文件風格一致

整合路徑：

1# 從 .fig 提取色彩 → 轉為 quarkdown 主題
2openpencil analyze colors brand.fig --json | jq -r '.colors[] | "--\(.name): \(.hex);"' >> theme.css
3
4# headless 匯出設計截圖 → 嵌入 quarkdown 文件
5openpencil export wireframe.fig -f png -s 2 -o docs/assets/

與 Layer 12 (gh-tutorial-qd) 的互補性

gh-tutorial-qd 將 GitHub repo 轉為教學文件 + HTML 打包。OpenPencil 特別適合作為此 workflow 的 標的 repo (target repo) 與 輔助工具：

• 作為標的 repo 時：其豐富的 CLI 命令、MCP 整合、Vue SDK 等面向，非常適合產出多章節教學
• 作為輔助工具時：其 MCP skill (npx skills add open-pencil/skills@open-pencil) 可讓 AI agent 在教學撰寫過程中自動產生設計截圖

新 Layer 潛力評估

總結

OpenPencil 對 AIKT 的價值不在於取代現有 Layer，而在於為 graphify (知識圖視覺化) 和 quarkdown (文件素材產生) 提供 可程式化的設計能力。其 CLI + MCP + eval API 三管齊下的程式化介面，特別適合 AIKT 這類以自動化為核心的知識管理系統。建議先以 gh-tutorial-qd 的教學標的 + graphify 輸出視覺化這兩條路線進行小規模驗證。