OpenPencil 設計
透過撰寫 PenNode JSON 結構樹,產生生產級品質的向量設計。使用 op CLI 或 MCP 工具在 OpenPencil 畫布上建立、讀取、更新和刪除節點。
使用時機
- 在
.op檔案中建立或修改 UI 設計 - 使用
opCLI 來腳本化設計操作 - 透過 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" })
| 操作 | 語法 | 動作 |
|---|---|---|
I | name=I(parent, { node }) | 插入 |
U | U(ref, { updates }) | 更新 |
C | name=C(source, parent, { overrides }) | 複製 |
R | name=R(ref, { node }) | 取代 |
M | M(ref, parent, index?) | 移動 |
D | D(ref) | 刪除 |
G | name=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
…
[內容已截斷以進行翻譯]