Communitygithub.com

OpenPencil 设计技能

通过 op CLI 和 MCP 工具,使用 PenNode JSON 树生成生产级矢量设计的 LLM 技能。

OpenPencil 设计技能 是什么?

这是一个专门为 AI 代理(如 Claude Code、Cursor、Codex)设计的技能,用于通过 OpenPencil 的 `op` 命令行工具和 MCP(模型上下文协议)工具进行矢量设计。该技能允许开发者使用 PenNode JSON 树来创建、读取、更新和删除画布上的节点,从而实现从简单 UI 组件到复杂数据驱动布局的完整设计流程。它支持三种构建设计的方法:`op insert` 用于逐节点精确控制、批量设计 DSL 用于快速原型设计、以及 JavaScript 脚本模式用于处理重复性结构(如表格行或导航项)。该技能特别强调生成严格有效的 JSON,并提供了关于 PenNode 模式(包括容器、文本、图标、图片等属性)的详细参考,以及丰富的 CLI 和 MCP 工具命令参考。

兼容平台~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(标志必须跟在负载之后)

# 分层工作流
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 必须跟在负载之后

通过 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

相关技能