Pencil Basics

Pencil 基础

介绍如何使用 Pencil MCP 服务器读取、修改和创建设计，并提供 .pen 文件的相关操作方法。

核心概念

.pen 文件结构

.pen 文件是一种用于存储设计数据的加密格式。必须仅使用 Pencil MCP 工具访问。

重要：不要使用 Read、Grep、Write 工具直接读取或写入 .pen 文件。始终使用 Pencil MCP 工具。

节点类型

类型	用途	主要属性
frame	容器、布局	layout、gap、padding、fill
text	文本内容	content、fontSize、fontWeight、textColor
rectangle	矩形	fill、stroke、cornerRadius
ellipse	圆形/椭圆	fill、stroke
ref	组件实例	ref（引用组件 ID）
image	图像框架	使用 G() 操作应用
icon_font	图标	icon、iconSize

布局系统

自动布局属性：

layout: "horizontal" | "vertical" | "grid"
gap: number (자식 간 간격)
padding: number | [top, right, bottom, left]
alignItems: "start" | "center" | "end" | "stretch"
justifyContent: "start" | "center" | "end" | "space-between"

指定尺寸：

width: number | "fill_container" | "hug_contents"
height: number | "fill_container" | "hug_contents"

核心工具

1. get_editor_state

获取当前编辑器状态和所选节点信息。

mcp__pencil__get_editor_state(include_schema: boolean)

开始设计工作前，始终调用此工具以确认活动文件和选择状态。

2. batch_get

搜索节点或按 ID 读取节点。

mcp__pencil__batch_get(
  filePath: string,
  patterns?: [{ reusable?: boolean, type?: string, name?: string }],
  nodeIds?: string[],
  readDepth?: number,
  searchDepth?: number
)

使用示例：

• 可复用组件列表：patterns: [{ reusable: true }]
• 读取特定节点：nodeIds: ["nodeId1", "nodeId2"]
• 搜索文本节点：patterns: [{ type: "text" }]

3. batch_design

执行设计修改操作。

mcp__pencil__batch_design(
  filePath: string,
  operations: string  // JavaScript 유사 구문
)

4. get_screenshot

获取节点的屏幕截图，以便进行视觉验证。

mcp__pencil__get_screenshot(filePath: string, nodeId: string)

完成设计工作后，始终通过屏幕截图检查结果。

batch_design 操作

插入（I）

插入新节点。

// 기본 삽입
frame1=I("parentId", { type: "frame", layout: "vertical", gap: 16 })
text1=I(frame1, { type: "text", content: "Hello", fontSize: 16 })

// 컴포넌트 인스턴스 삽입
button=I("parentId", { type: "ref", ref: "ButtonComponentId" })

更新（U）

更新现有节点的属性。

// 직접 업데이트
U("nodeId", { fill: "#FF0000", padding: 16 })

// 컴포넌트 인스턴스 내부 노드 업데이트
U("instanceId/labelId", { content: "New Label" })

复制（C）

复制节点。

// 단순 복사
copy1=C("sourceId", "parentId", { x: 100, y: 100 })

// 속성 오버라이드와 함께 복사
copy2=C("sourceId", "parentId", {
  descendants: {
    "labelId": { content: "Copied Label" }
  }
})

替换（R）

将节点替换为新节点。

newNode=R("oldNodeId", { type: "text", content: "Replaced" })

删除（D）

删除节点。

D("nodeId")

移动（M）

将节点移动到其他位置。

M("nodeId", "newParentId", 0)  // index는 선택사항

生成图像（G）

将图像应用到框架。

// AI 생성 이미지
imgFrame=I("parentId", { type: "frame", width: 400, height: 300 })
G(imgFrame, "ai", "modern office workspace")

// 스톡 이미지
G("existingFrameId", "stock", "nature landscape")

工作流模式

创建新屏幕

1. 使用 get_editor_state 确认当前状态
2. 使用 batch_get 查看可用组件
3. 使用 get_guidelines 加载设计指南
4. 使用 get_style_guide_tags + get_style_guide 获取风格灵感
5. 使用 batch_design 构建屏幕
6. 使用 get_screenshot 验证结果

修改组件

1. 使用 batch_get 了解目标节点结构
2. 使用 batch_design 的 U() 操作修改属性
3. 使用 get_screenshot 检查更改

解决布局问题

1. 使用 snapshot_layout 分析布局结构
2. 检查溢出和裁剪问题
3. 使用 batch_design 进行修改
4. 使用 get_screenshot 验证

最佳实践

应做事项

• 每次执行 batch_design 后，都使用 get_screenshot 进行验证
• 分批执行操作（最多 25 个）
• 每次都创建新的绑定名称
• 修改组件时使用实例路径（instanceId/childId）

不应做事项

• 使用 Read、Write、Grep 直接访问 .pen 文件
• 一次执行过多操作
• 重复使用绑定名称
• 直接指定 id 属性（系统会自动生成）

其他资源

参考文件

• references/node-properties.md - 所有节点类型的详细属性
• references/layout-examples.md - 布局模式示例