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(标志必须跟在负载之后)
# 分层工作流
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 必须跟在负载之后
通过 MCP:使用 script 参数调用 batch_design(每次调用恰好使用 nodes_json、operations 或 script 之一)。这与 OpenPencil 内部设计代理使用的协议相同;遵循相同的约定:
编写一个 JavaScript 程序(无叙述,无 markdown 围栏),通过调用全局函数 I(parent, node) 来构建设计:
const id = I(parent, { ...node... }); // 插入节点,返回其 id(字符串)
parent 对于根框架为 null,否则为早期 I(...) 调用返回的 id。仅当你以 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,CPU 2 秒,内存 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": "semantic-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": "你好", // 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": "粗体 ", "fontWeight": "bold" }, { "text": "普通" }]
图标 — 两种选项
选项 A:icon_font(推荐 — 直接渲染,无需后处理)
{ "type": "icon_font", "name": "锁定图标", "iconFontName": "lock",
"width": 20, "height": 20,
"fill": [{ "type": "solid", "color": "#6B7280" }] }
字段是 iconFontName(不是 iconName,也不是 icon)。 值为小写短横线分隔的 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" }] }
PascalCase + "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": "一个具有自然采光的现代办公空间",
"imageSearchQuery": "现代办公空间" }
图像调整(全部范围 -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