Communitygithub.com

ZSeven-W/openpencil-skill

使用 `op` CLI 和 MCP 工具,透過 OpenPencil 進行向量設計的 LLM 技能。

openpencil-skill 是什麼?

這是一個專為 AI 代理設計的技能,使其能夠透過 OpenPencil 平台進行生產級的向量設計。它利用 `op` 命令列介面和 MCP 工具,以結構化的 PenNode JSON 格式來建立、讀取、更新和刪除設計節點。此技能支援多種設計方法,包括使用 `op insert` 進行精確的節點操作、使用批次設計 DSL 進行快速佈局,以及使用 JavaScript 進行數據驅動的腳本生成,特別適合重複性的 UI 元素。 該技能涵蓋了完整的設計工作流程,從創建框架和文字,到處理圖示、圖片和程式碼生成。它與 Claude Code、Cursor 和 Codex 等平台相容,透過標準化介面與 OpenPencil 互動。其核心優勢在於提供明確的 JSON 規則和安全的設計模式,確保生成的向量設計品質穩定,並能有效避免常見的語法錯誤。對於需要在設計工具中自動化 UI 生成的開發者和 AI 代理來說,這是一個必備的工具。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add ZSeven-W/openpencil-skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

OpenPencil 設計

透過撰寫 PenNode JSON 結構樹,產生生產級品質的向量設計。使用 op CLI 或 MCP 工具在 OpenPencil 畫布上建立、讀取、更新和刪除節點。

使用時機

  • 在 .op 檔案中建立或修改 UI 設計
  • 使用 op CLI 來腳本化設計操作
  • 透過 MCP 工具進行設計(batch_design、insert_node、design_skeleton)
  • 需要參考 PenNode 結構、角色或佈局規則時

快速參考 — op CLI

# 應用程式控制
op start [--desktop|--web]           # 啟動應用程式
op stop                              # 停止執行中的實例
op status                            # 檢查是否在執行中

# 文件
op open [file.op]                    # 開啟檔案或連接到即時畫布
op save <file.op>                    # 儲存目前文件
op get [--depth N] [--pretty]        # 取得文件樹
op selection [--depth N]             # 取得目前畫布選取內容
op read-nodes [id...] [--depth N] [--vars]  # 讀取節點子樹(可選變數解析)
op layout [--parent P] [--depth N]   # 快照佈局樹與計算後的位置
op find-space [--direction D] [--width N] [--height N]  # 在畫布上尋找空白區域

# 節點操作
op insert '<json>' [--parent P]     # 插入節點(--index N, --post-process)
op update <id> '<json>'              # 更新節點
op delete <id>                       # 刪除節點
op move <id> <parent> [index]        # 移動節點
op copy <id> <parent>                # 深度複製節點
op replace <id> '<json>'             # 取代節點

# 批次設計
op design '<dsl>'                    # 批次設計 DSL(內聯、@file 或 stdin)[--canvas-width N]
op design @ui.js                     # 沙盒化 JS 腳本:I(parent, obj) + 迴圈(.js/.mjs 隱含 --script)
op design '<js>' --script            # 相同,內聯/stdin(旗標必須緊跟在 payload 之後)

# 分層工作流程
op design:skeleton '<json>'          # 建立區段結構
op design:content <id> '<json>'      # 填入區段內容
op design:refine --root-id <id>      # 驗證 + 自動修正(解析圖示)[--canvas-width N]

# 匯入
op import:svg <file.svg> [--parent P]       # 匯入 SVG 為可編輯節點
op import:figma <file.fig> [--out out.op]   # 將 Figma .fig 轉換為 .op 文件

# 頁面
op page list                         # 列出所有頁面
op page add [--name N]               # 新增頁面
op page remove <id>                  # 刪除頁面
op page rename <id> '<name>'         # 重新命名頁面
op page reorder <id> <index>         # 將頁面移動到指定位置
op page duplicate <id>               # 複製頁面並產生新 ID

# 變數與主題
op vars / op vars:set '<json>'       # 變數(使用 --replace 取代所有)
op themes / op themes:set '<json>'   # 主題(使用 --replace 取代所有)
op theme:save <file.optheme>         # 將目前主題儲存為預設檔案
op theme:load <file.optheme>         # 載入主題預設檔案
op theme:list <directory>            # 列出目錄中的 .optheme 預設

# 程式碼生成管線
op codegen:plan '<json>'             # 提交程式碼生成計劃(框架、rootIds、選項)
op codegen:submit '<json>'           # 為某個節點提交程式碼區塊
op codegen:assemble [--framework F]  # 將所有提交的區塊組裝成最終輸出
op codegen:clean                     # 清除程式碼生成狀態

全域旗標:--file <path>、--page <id>、--pretty。輸入方式:內聯字串、@filepath 或 -(stdin)。

建立設計 — 三種方法

方法 1:op insert(建議使用)

最可靠的建立設計方式。使用 --parent 指定父節點。擷取回傳的 nodeId 以供後續參考。始終以 design:refine 結束,以解析圖示並驗證佈局。

# 建立根框架,擷取其 ID
ROOT=$(op insert '{"type":"frame","name":"Page","width":375,"height":812,"layout":"vertical"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['nodeId'])")

# 使用 --parent 插入子節點
op insert --parent "$ROOT" '{"type":"text","content":"Hello","fontSize":28,"fontWeight":700}'

# 後處理:解析圖示、驗證佈局
op design:refine --root-id "$ROOT"

方法 2:批次設計 DSL

每行一個操作。使用 name= 綁定結果以供後續參考。最適合簡單、扁平的結構。

限制: DSL 解析器無法處理深度巢狀的 JSON(例如,包含巢狀物件的 children 陣列,或多層陣列巢狀)。請將每個 I() 呼叫保持在單層巢狀。對於具有子節點的複雜節點,請為父節點和子節點使用單獨的 I() 呼叫,或使用 op insert --parent。

root=I(null, { "type": "frame", "width": 1200, "layout": "vertical" })
nav=I(root, { "type": "frame", "role": "navbar", "height": 72 })
U(nav, { "fill": [{"type": "solid", "color": "#FFFFFF"}] })
card2=C(card1, grid, { "name": "Card 2" })
M(sidebar, main, 0)
D(old_section)
R(old_btn, { "type": "rectangle", "role": "button" })
操作語法動作
Iname=I(parent, { node })插入
UU(ref, { updates })更新
Cname=C(source, parent, { overrides })複製
Rname=R(ref, { node })取代
MM(ref, parent, index?)移動
DD(ref)刪除
Gname=G(parent, "search", "query")透過搜尋生成圖片

DSL 安全模式 — 始終分開插入父節點和子節點:

btn=I(form, {"type":"rectangle","role":"button","width":"fill_container","height":50,"cornerRadius":12,"fill":[{"type":"solid","color":"#111111"}],"layout":"horizontal","justifyContent":"center","alignItems":"center"})
I(btn, {"type":"text","content":"Submit","fontSize":16,"fontWeight":600,"fill":[{"type":"solid","color":"#FFFFFF"}]})

方法 3:腳本模式(迴圈與資料驅動 — 建議用於重複結構)

op design @ui.js                 # .js / .mjs 檔案隱含腳本模式
op design '<js code>' --script   # 內聯或 stdin;--script 必須緊跟在 payload 之後

透過 MCP:使用 script 參數呼叫 batch_design(每次呼叫只能精確選擇 nodes_json | operations | script 其中一個)。這與 OpenPencil 內部設計代理使用的協議相同;請遵循相同的合約:

撰寫一個 JavaScript 程式(無散文、無 markdown 圍欄),透過呼叫全域函數 I(parent, node) 來建立設計:

const id = I(parent, { ...node... });   // 插入節點,回傳其 id(字串)

parent 對於根框架為 null,否則為先前 I(...) 呼叫回傳的 id。僅當你對 X 呼叫 I(X, {...}) 時,節點才是 X 的子節點。

I(...) 是唯一可用的函數 — 沒有 console,也沒有其他建構器。不要呼叫 console.log 或任何輔助函數;只需呼叫 I(...)。腳本模式僅支援插入操作;更新/移動/刪除請使用 DSL 操作(方法 2)。

使用真正的 JavaScript — const/let、資料陣列以及 for...of / .forEach 迴圈 — 透過遍歷資料陣列來生成重複結構(表格行、導航項目、卡片、清單項目)。優先使用迴圈,而不是複製貼上幾乎相同的 I(...) 呼叫。

每個節點物件以 type("frame"/"text"/"rectangle"/"ellipse""/"path"/"icon_font")開頭,並使用駝峰式屬性(cornerRadius、fontSize、fontWeight、justifyContent、alignItems、clipContent)。不要在佈局框架內的子節點上設定 x/y。

範例:

const sec = I(null, {type:"frame", name:"Clients", layout:"vertical", width:"fill_container", gap:0});
const tbl = I(sec, {type:"frame", layout:"vertical", width:"fill_container"});
const rows = [{name:"Alice Chen", status:"Active"}, {name:"Bob Ito", status:"VIP"}];
for (const r of rows) {
  const row = I(tbl, {type:"frame", layout:"horizontal", width:"fill_container", padding:[12,16]});
  const c1 = I(row, {type:"frame", width:"fill_container"}); I(c1, {type:"text", content:r.name});
  const c2 = I(row, {type:"frame", width:"fill_container"}); I(c2, {type:"text", content:r.status});
}

為每一行/卡片/項目生成真實的數值。僅輸出 JavaScript 程式。

CLI/MCP 注意事項:

  • 巢狀的 children 陣列在此處是安全的 — 引擎會將每個物件序列化為完美的單行 JSON,因此 DSL 的單層巢狀限制不適用。但當你需要父節點綁定時,仍然建議使用單獨的 I() 呼叫。
  • 節點 ID 在插入時會重新映射 — 在呼叫後不要參考自行指定的 "id";只有回傳的綁定才有意義,且僅在此腳本內有效。
  • 限制: 256 KiB 原始碼、4096 次插入、8 MiB 記錄輸出、2 秒 CPU、64 MiB 記憶體。一個在語句中截斷的腳本會盡力修復(完整的字首部分仍然會執行)。

嚴格的 JSON 規則

當發出 PenNode JSON 時(透過 op insert、op design、batch_design、insert_node),你必須產生嚴格有效的 JSON。常見的破壞解析錯誤:

  • 每個屬性必須同時有鍵和值。絕對不要發出 ": 50 或 : 50 而沒有鍵名。這通常發生在你截斷/重新格式化時 — 請雙重檢查。
  • 每個鍵必須是雙引號括起來的非空字串。
  • fill 始終是陣列:"fill": [{"type": "solid", "color": "#hex"}]。像 "fill": "#hex" 這樣的簡寫也有效,但陣列形式是標準形式。
  • stroke 是一個帶有 fill 陣列的物件:"stroke": {"thickness": 1, "fill": [{"type": "solid", "color": "#hex"}]}。絕不要使用 "stroke": {"thickness": 1, "color": "#hex"} 或 "stroke": "#hex"(解析器會自動轉換這些,但正確的形式是首選)。
  • 結尾不要有逗號在 } 或 ] 之前。
  • JSON 內不要有註解(// 或 /* */)。
  • 使用直的雙引號 ",不要使用智慧/彎曲引號。
  • 文字內容使用 content,不是 text:{"type": "text", "content": "Hello"}。
  • 圖示使用 iconFontName,不是 iconName 或 icon:{"type": "icon_font", "iconFontName": "lock"}。
  • 在最終確定 JSON 之前,在心裡驗證:每個鍵都有值,每個值都有鍵,所有括號都匹配。

PenNode 結構

通用屬性

{
  "type": "frame|rectangle|text|ellipse|line|polygon|path|image|icon_font|group|ref",
  "name": "顯示名稱",
  "role": "語義角色",
  "x": 0, "y": 0,
  "rotation": 0, "opacity": 1, "visible": true
}

容器屬性(frame、rectangle、group、ellipse)

{
  "width": 400,              // number | "fill_container" | "fit_content"
  "height": 300,
  "layout": "vertical",      // "none" | "vertical" | "horizontal"
  "gap": 16,
  "padding": [16, 24],       // number | [v, h] | [top, right, bottom, left]
  "justifyContent": "center", // "start" | "center" | "end" | "space_between" | "space_around"
  "alignItems": "center",    // "start" | "center" | "end"
  "clipContent": true,
  "cornerRadius": 12,        // number | [tl, tr, br, bl]
  "fill": [{ "type": "solid", "color": "#FFFFFF" }],
  "stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }], "align": "inside", "dashPattern": [5, 3] },
  "effects": [{ "type": "shadow", "offsetX": 0, "offsetY": 4, "blur": 12, "spread": 0, "color": "rgba(0,0,0,0.08)" }],
  "children": []
}

文字

{
  "type": "text",
  "content": "Hello",          // string 或 StyledTextSegment[]
  "fontSize": 16, "fontFamily": "Inter", "fontWeight": 600,
  "textAlign": "center",       // "left" | "center" | "right"
  "textGrowth": "fixed-width", // "auto" | "fixed-width" | "fixed-width-height"
  "lineHeight": 1.5, "letterSpacing": 0,
  "fill": [{ "type": "solid", "color": "#111111" }]
}

富文字:"content": [{ "text": "Bold ", "fontWeight": "bold" }, { "text": "normal" }]

圖示 — 兩種選擇

選擇 A:icon_font(建議使用 — 直接渲染,無需後處理)

{ "type": "icon_font", "name": "Lock Icon", "iconFontName": "lock",
  "width": 20, "height": 20,
  "fill": [{ "type": "solid", "color": "#6B7280" }] }

欄位是 iconFontName(不是 iconName,不是 icon)。 值為小寫 kebab-case 的 Lucide 名稱:mail、lock、eye、eye-off、chrome、apple、message-circle、x、arrow-right、search、heart、star、check、plus、bell、home、user、settings、chevron-right、download、globe、layers、zap、shield、play。

適用於所有情境:CLI、MCP 工具或直接 .op 檔案 — 無需 design:refine。

選擇 B:path(需要後處理)

{ "type": "path", "name": "HeartIcon", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

使用帕斯卡命名法 + "Icon" 後綴。在後處理期間從 Lucide 集合自動解析。

路徑圖示需要後處理。 插入路徑節點後,執行 op design:refine --root-id <id> 或使用 op insert --post-process。如果沒有這個,路徑圖示將無法視覺化渲染。獨立的 MCP 伺服器(由 ACP 代理使用)沒有註冊鉤子實作,因此路徑圖示無法在那裡解析 — 在 MCP 情境中建議使用 icon_font。

圖片

{ "type": "image", "src": "https://example.com/photo.jpg", "width": 400, "height": 300,
  "objectFit": "crop", "cornerRadius": 12 }

AI 圖片佔位符(由 design:refine 解析):

{ "type": "image", "width": 400, "height": 300,
  "imagePrompt": "A modern office workspace with natural light",
  "imageSearchQuery": "modern office workspace" }

圖片調整(所有值範圍 -100 到 100):exposure、contrast、saturation、temperature、tint、highlights、shadows。

多邊形

{ "type": "polygon", "polygonCount": 6, "width": 80, "height": 80, "cornerRadius": 4,
  "fill": [{ "type": "solid", "color": "#6366F1" }] }

圖示字體

{ "type": "icon_font", "iconFontName": "lucide:home", "width": 24, "height": 24,
  "fill": [{ "type": "solid", "color": "#111111" }] }

線條

{ "type": "line", "x2": 200, "y2": 0,
  "stroke": { "thickness": 1, "fill": [{ "type": "solid", "color": "#E5E7EB" }] } }

填色類型

{ "type": "solid", "color": "#3B82F6" }
{ "type": "lin

…

[內容已截斷以進行翻譯]

相關技能