pen.dev 文档
中文完整指南

安装

原文:Getting Started / Installation

pen.dev 提供 IDE 扩展与独立桌面应用两种形态,按你的工作流选择即可。

VS Code 扩展

1. 打开 VS Code,进入扩展面板(Cmd/Ctrl + Shift + X)
2. 搜索 "pen.dev" 并点击 Install
3. 验证:新建一个 .pen 后缀文件(如 test.pen)并打开,编辑器右上角应出现 pen.dev 图标

Cursor 扩展

安装方式与 VS Code 相同:扩展面板搜索 "pen.dev" 安装,再新建 .pen 文件验证图标是否出现。

常见问题

• 扩展无法连接:确认 Claude Code 已登录(运行 claude)、完成激活流程、检查 pen.dev MCP 服务器已连接。
• 看不到提示输入框:检查激活/登录状态,重启 Cursor,仍不行则重装扩展。
• 提示 "You need Cursor Pro":可能与 Cursor 的套餐/工具限制有关,请检查订阅状态。

桌面应用

macOS

• 从官网或发布页下载最新 .dmg,拖入「应用程序」文件夹后启动。
• 首次启动如遇安全提示,右键 → 打开即可;随后完成激活,若要使用 AI 功能还需登录 Claude Code。

Linux

# .deb 包示例
sudo dpkg -i pencil-*.deb

# .AppImage 示例
chmod +x pencil-*.AppImage
./pencil-*.AppImage

Windows

pen.dev 可在 Windows 上运行;Windows 用户也可以直接使用 VS Code 或 Cursor 扩展,安装步骤与 macOS/Linux 完全一致。

Claude Code CLI

pen.dev 的 AI 功能依赖已安装并完成认证的 Claude Code:

# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code-cli

# 或使用官方安装脚本
curl https://claude.ai/cli/install.sh | sh

# 登录(跟随浏览器认证流程)
claude

# 验证登录状态
claude --version

MCP 服务器

pen.dev 的 MCP(Model Context Protocol)服务器会在你使用 pen.dev 时自动启动、本地运行,为 AI 助手提供读写 .pen 文件的工具,基础使用无需任何额外配置。

• Cursor 中验证:Settings → Tools & MCP,确认列表中出现 pen.dev。
• Codex CLI 中验证:先运行 pen.dev,再在 Codex 中执行 /mcp,pen.dev 应出现在 MCP 列表。

安装完成后

1. 完成激活 — 使用邮箱激活 pen.dev
2. 登录 Claude Code — AI 功能必需
3. 打开欢迎文件 — 画布右键 → Open Welcome File
4. 创建第一个设计 — 参见 .pen 文件

更新 pen.dev

• VS Code / Cursor 扩展:默认自动更新;手动更新在扩展面板找到 pen.dev 点击 Update。
• 桌面应用:有新版本时应用会提示,从官网下载安装最新版。

安装故障速查

• 扩展已装但不连接:确认 Claude Code 已登录 → 完成激活 → 重启 IDE。
• 收不到激活邮件:检查垃圾邮件;换一个邮箱;重装扩展。
• "Invalid API key" 或 "Please run /login":运行 claude 完成认证,并确保没有冲突的认证配置(环境变量密钥、自定义 Provider)。

认证与激活

原文:Getting Started / Authentication

pen.dev 需要两层身份验证:激活(使用 pen.dev 本身)+ Claude Code 认证(使用 AI 功能)。

pen.dev 激活

1. 首次启动时按提示输入邮箱
2. 查收邮件获取激活码
3. 在 pen.dev 中输入激活码完成激活

激活常见问题

• 收不到激活邮件:检查垃圾邮件文件夹;换邮箱;稍等几分钟(邮件可能延迟)。
• "Invite for your email address was not found. Please join the waitlist.":尝试重装 Cursor/VS Code 扩展,持续出现请联系支持。
• 反复要求激活:部分版本的已知问题——重启 IDE,持续出现则重装扩展。
• 迁移过程中激活卡住:重装扩展并清除扩展数据后重试。

Claude Code 认证

推荐通过 CLI 登录:

# 启动 Claude Code,跟随浏览器认证流程
claude

该流程会打开浏览器 → 使用 Anthropic 账号登录 → 将凭证保存在本地。验证方式:运行 claude --version,或在 pen.dev 中确认没有 "Claude Code not connected" 警告、AI 面板(Cmd/Ctrl + K)可正常使用。

常见认证问题

"Claude Code isn't connected / not logged in"

在项目目录打开终端 → 运行 claude 完成认证 → 回到 pen.dev 重试。

"Invalid API key" 或 "Please run /login"

原因:认证未完成;多种认证方式冲突(控制台登录 + 环境变量密钥 + 自定义 Provider);凭证过期。
解决:运行 claude 完成认证;若使用 CLI 认证,移除 ANTHROPIC_API_KEY 环境变量、清除不需要的自定义 Provider 配置;必要时重新干净登录一次。

"Claude CLI 正常,但 pen.dev 仍显示未登录"

通常由第三方/自定义 Provider 的认证冲突或扩展未识别 CLI 认证导致:保持一个干净的 Claude Code 登录会话(无自定义 Provider),认证后重启 IDE,并检查是否存在冲突的环境变量。

认证方式对比

一套可行的完整流程

1. 安装 pen.dev(扩展或桌面应用)
2. 完成 pen.dev 激活(邮箱验证码)
3. 安装 Claude Code CLI
4. 认证 Claude Code(claude 命令)
5. 在项目中创建 .pen 文件
6. 开始工作 — pen.dev 与 AI 功能均应就绪

权限与访问

• "pen.dev / Claude 无法访问其他文件夹":多为文件夹权限或系统安全设置所致——出现授权提示时接受;在系统设置中更新文件夹权限;以合适的权限运行 IDE/pen.dev。
• "从未看到权限弹窗":改在 pen.dev 之外的独立 Claude Code 会话中执行该操作;检查系统通知设置与 IDE 权限。

安全与隐私

• pen.dev MCP 服务器在本机运行;除使用 AI 功能(提示词发送给 Claude)外,设计数据不会发送到远程服务器。仓库目前为私有。
• 可在 IDE 中查看 MCP 工具定义:Cursor 为 Settings → Tools & MCP;VS Code 查看 MCP 配置。工具定义展示了 AI 能对你的设计做什么。

还有问题?

如果认证问题仍未解决:

• 查阅故障排查文档
• 确认你使用的是 pen.dev 与 Claude Code 的最新版本
• 尝试将 pen.dev 与 Claude Code CLI 都彻底重装一遍

AI 集成

原文:Getting Started / AI Integration

pen.dev 通过 MCP(Model Context Protocol)与 AI 助手深度集成,实现强大的设计自动化工作流。

支持的 AI 助手

Claude Code(CLI 与 IDE)、Claude Desktop、Cursor、Windsurf IDE(Codeium)、Codex CLI(OpenAI)、Antigravity IDE、OpenCode CLI。

MCP 是什么、如何工作

MCP 是一种让 AI 助手获得「操作你设计文件的工具」的协议——可以把它理解为一套让 AI 以编程方式读写 .pen 文件的 API。

1. pen.dev MCP 服务器本地运行 — 设计操作不依赖云端
2. AI 助手通过 MCP 连接 — pen.dev 运行时即可连上
3. AI 调用工具 — 读取、修改、生成设计
4. 你保持掌控 — AI 提议,你来批准

在 Claude Code 中使用

前置条件:安装 Claude Code CLI → 运行 claude 认证 → 保持 pen.dev 运行 → 打开一个 .pen 文件。

▶ 官方演示:在 Antigravity / VS Code 的 Claude Code 面板中使用 pen.dev

基本工作流

1. 按 Cmd/Ctrl + K 打开 AI 提示面板
2. 用自然语言描述需求,例如:"创建一个带邮箱和密码的登录表单"、"给这个页面加一个导航栏"
3. AI 通过 MCP 工具修改你的 .pen 文件
4. 修改即时反映在画布上

提示词示例

在 Cursor 中使用

1. 在 Cursor 安装 pen.dev 扩展并完成激活
2. 认证 Claude Code
3. 验证 MCP 连接:Settings → Tools & MCP

▶ 官方演示:在 Cursor 中使用 pen.dev 扩展

• 内联编辑:在 pen.dev 中选中元素,用 Cursor 的 AI 聊天修改,变更直接写入 .pen 文件。
• 代码库感知:Cursor 能同时看到代码和设计,可要求它在两者间同步组件、自动保持一致。

在 Codex CLI 中使用

1. 先运行 pen.dev(桌面应用或 IDE 扩展)
2. 在终端打开 Codex,执行 /mcp 验证连接
3. pen.dev 应出现在 MCP 服务器列表中

终端里即可直接下设计指令,好处是命令行工作流、可脚本化的设计生成、可与构建工具集成。

可用的 MCP 工具

2026-07-27 起官方文档把工具集从 5-6 个细分工具收拢成 5 个(执行/取状态/截图/导出/加载指南),完整新旧对照与「文档已改但你环境可能还没升级」的提醒见「pen.dev CLI」章 · 支持的 MCP 工具。

高级工作流

• 自动化设计生成:指定风格("按 Material Design 原则创建仪表盘");批量操作("为这个按钮组件生成 5 个变体"、"设计一整页含 Hero、功能、定价与页脚的落地页")。
• 设计系统管理:一致性约束("确保所有按钮使用主色变量"、"给所有元素应用 8px 间距网格");组件库("创建含全部变体的按钮组件"、"生成文本/下拉/复选/单选等表单输入组件")。
• 代码-设计联动:导入既有应用("在 pen.dev 中重建 src/components 下的全部组件"、"从 Tailwind 配置导入设计系统");同步变更("让所有 React 组件与 pen.dev 设计保持一致"、"在 CSS 与 pen.dev 之间同步字体变量")。

官方最佳实践

• 够具体:❌ "弄好看点" → ✅ "按钮内边距加到 16px,颜色改为蓝色"
• 给上下文:❌ "加个表单" → ✅ "添加登录表单:邮箱、密码、记住我复选框和提交按钮"
• 引用设计系统:"用我们现有的按钮组件"、"遵循变量里的间距阶梯"、"和 Header 组件风格保持一致"
• 迭代式设计:先框架("创建仪表盘布局")→ 细化("加带导航项的侧边栏")→ 打磨("导航项加 hover 态")→ 收尾("间距对齐 8px 网格")
• 验证:AI 修改后,在画布上目视检查 → 在图层面板核对结构 → 必要时让 AI 截图核验复杂布局

AI 集成故障排查

• 连接问题:"Claude Code not connected" → 运行 claude 登录、重启 pen.dev;MCP 服务器不出现 → 确认 pen.dev 在运行、检查 IDE 的 MCP 设置、把 pen.dev 和 AI 助手都重启一遍。
• 权限问题:接受权限弹窗;检查系统文件夹权限;弹窗不出现时改用独立 Claude Code 会话执行。
• 输出问题:"Invalid API key" → 重新认证、清理冲突环境变量;AI 改得不符合预期 → 提示词更具体、要求先解释再执行、必要时用版本控制回滚。

示例会话

# 1. 启动 pen.dev 与 Claude Code
claude
# 2. 在 IDE 中打开 design.pen;按 Cmd+K 开始设计
用户: "创建一个现代风格的落地页 Hero 区域"
AI:   [生成含主标题、副标题、CTA 按钮的 Hero]
用户: "在下方添加一个三列的功能特性区"
AI:   [在 Hero 下方添加功能区]
用户: "CTA 按钮使用我们的主色变量"
AI:   [按钮改为引用颜色变量]
用户: "为整个页面生成 React 代码"
AI:   [导出为 React + Tailwind 组件]
# 3. 审查、微调,提交 Git
git add design.pen src/pages/landing.tsx
git commit -m "Add landing page design and implementation"

.pen 文件

原文:Core Concepts / .pen Files

.pen 是 pen.dev 的设计文件格式,三个关键特征:

• 基于 JSON — 结构化、可读的数据格式
• 版本控制友好 — 像代码文件一样纳入 Git 管理
• 可移植 — 跨团队、跨平台共享

想以编程方式读写 .pen 文件?参见 .pen 文件格式(开发者)。

设计即代码 Design as Code

原文:Core Concepts / Design as Code

因为 .pen 是文本格式,设计文件可以完全按代码的方式协作与管理版本——这是 pen.dev 区别于 Figma 等云端设计工具的根本理念。

• 同仓库 — .pen 与代码放进同一个 Git 仓库,设计和实现共享一套版本历史;
• 可 diff — 设计变更在 PR 里以文本 diff 呈现,评审设计改动像评审代码一样;
• 可分支合并 — 设计跟着功能分支走,一起合并、一起回滚,设计与代码永不漂移;
• 单一事实源 — 不再有「Figma 里是一套、代码里是另一套」的双事实来源问题。

pen.dev 界面

原文:Core Concepts / pen.dev Interface

无限画布

画布提供不设边界的工作空间,交互习惯与专业设计工具一致,上手即熟悉。按住空格拖拽平移画布;用触控板或按住 Cmd/Ctrl 滚动进行缩放。

Frame(框架)

Frame 是设计的容器:归组相关元素、界定屏幕边界。Cmd/Ctrl + Option/Alt + G 可对选区应用 Flex 布局。

选择与高亮

点击或框选画布元素,选中后的包围框颜色标识元素类型:

• 蓝色 — 常规元素:Frame、形状、文本
• 品红色 — 组件源(origin):唯一事实来源,在这里的修改会自动应用到所有实例
• 紫色 — 组件实例(instance)

图层面板

位于屏幕左侧,列出画布上的所有元素,让你在复杂嵌套结构中清晰浏览、编辑、组织设计层级。双击图层可重命名;点击 "Layers" 图标可开关面板。

属性面板

选中一个或多个元素时出现在屏幕右侧,可查看和编辑对齐、布局、外观、填充、描边、效果等属性。支持将选区导出为 PNG / JPEG / WEBP / PDF;点击右上角图标可最小化。

AI 聊天

pen.dev 的 AI 聊天是「凭感觉设计(vibe-designing)」的入口:可以让它从零设计,也可以编辑画布上的现有设计。聊天面板内置于桌面应用;在 IDE 里使用扩展时,则通过 IDE 自带的聊天与 AI 协作。

• 画布上的选区会自动加入上下文。
• 点击 "New Agent" 可开启新会话并清空上下文窗口。

撤销 / 重做

Cmd/Ctrl + Z 撤销,Cmd/Ctrl + Shift + Z 重做。注意:撤销/重做能力可能比常规设计编辑器有限。

变量 Variables

原文:Core Concepts / Variables

pen.dev 的变量类似 CSS 自定义属性或设计令牌(design tokens):颜色 HEX、间距/圆角/尺寸数值、字体名称字符串——只定义一次,到处引用。在变量面板修改变量,所有引用处即时更新。

创建变量的三种方式

• 手动创建 — 点击工具栏变量图标打开面板,直接定义变量并为不同主题设值。
• 从 CSS 导入 — 让 AI 代理基于你的 globals.css 创建变量,自动提取颜色、间距和字体。
• 从 Figma 导入 — 粘贴变量表截图让 AI 在 pen.dev 中建好;也可以直接从 Figma 复制单个令牌值。

使用变量

• 应用到元素 — 用变量引用代替硬编码值;变量一改,所有引用元素自动更新。
• 主题化 — 在变量面板新增一列即可创建亮色/暗色等主题;在属性面板切换主题,即时预览设计的适配效果。

与代码同步

变量可以在 pen.dev 和代码库之间保持同步:让 AI 根据 pen.dev 文件更新 CSS 变量,或把 CSS 的改动导回 pen.dev——这是双向设计-代码工作流的基础。

组件 Components

原文:Core Concepts / Components

为什么用组件

组件保证设计一致性:编辑一次主组件,所有实例自动更新。组件是构建设计系统的基石。

创建组件

任何标准设计元素(Frame、形状、文本)都能转换为可复用组件:

1. 选中元素
2. 按 Cmd/Ctrl + Option/Alt + K,或点属性面板顶部的 "Create component" 按钮
3. 该元素即成为组件源(origin),选中时显示品红色包围框

更复杂的结构可以创建嵌套组件。

使用组件

直接在画布上复制组件源即可创建实例;实例选中时显示紫色包围框。点击属性面板的 "Go to component" 按钮可快速跳回组件源。

插槽 Slots

原文:Core Concepts / Slots

插槽是组件内部预留的可投放区域,用来在组件里定义灵活、可自定义的内容区。

创建插槽

1. 创建一个 Frame 并将其转为组件(Cmd/Ctrl + Option/Alt + K 或属性面板 "Create component")
2. 按需设置样式
3. 点击属性面板顶部的 "Make a slot" 按钮

建议的插槽组件

同一 .pen 文件中的其他组件可以被标记为某插槽的「建议组件」。例如 table 组件的插槽可以建议 table-row 作为预期内容——这给人类和 AI 设计师都提供了「这个槽该放什么」的指引。

1. 在组件源中选中带插槽的图层
2. 点击属性面板顶部 "Slots" 行的 + 按钮
3. 选择要设为建议的组件

向插槽投放元素

创建组件实例后,把元素拖拽或复制粘贴进插槽即可填充内容。

画布上的代码 Code on Canvas

原文:Core Concepts / Code on Canvas

pen.dev 通过 Script 节点把代码带上画布:放一个节点、指向一个 .js 文件,脚本输出即渲染为嵌套图层——饼图、网格、装饰纹样,凡是能用代码描述的都行。适合手工搭建很繁琐的结构:数据驱动、带变化的重复、或希望用几个「旋钮」交互调参的场景。

快速上手

1. 创建 Script 节点:工具栏打开形状下拉 → 选 Script(</> 图标)→ 点击画布放置一个 200×200 节点(未关联文件前显示绿色 "No script file selected" 占位)
2. 关联 .js 文件:在属性面板脚本字段输入路径;路径相对于 .pen 文件解析,同目录文件直接写 chart.js
3. 画布上调参:拖拽手柄改尺寸,脚本实时重跑重排;每个 @input 都会在属性面板生成控件;保存 .js 文件画布即更新

不必手写脚本,两条捷径:去 highagency/pencil-scripts 拿官方维护的现成示例(图表、网格、纹样等);或打开 AI 面板直接描述需求,AI 会创建 .js 并关联到选中的 Script 节点。

最小示例

/**
 * @schema 2.11
 *
 * @input columns: number(min=1) = 3
 * @input color: color = #3B82F6
 */
const cols = Math.floor(pencil.input.columns);
const cellW = pencil.width / cols;

const nodes = [];
for (let c = 0; c < cols; c++) {
  nodes.push({
    type: "rectangle",
    x: c * cellW,
    y: 0,
    width: cellW - 4,
    height: pencil.height,
    fill: pencil.input.color,
  });
}
return nodes;

工作机制要点

• .js 文件独立于 .pen 文件,节点只存路径;多个节点可指向同一文件,各自维护尺寸与输入值。
• 输入在文件头部注释以 @input 声明;改名或删除后属性面板自动更新。
• 脚本必须返回节点数组,每个对象遵循 .pen 格式,作为 Script 节点的子级插入。
• 输出是派生状态:每次运行重新渲染,不进撤销历史;要手工编辑生成内容,点属性面板底部的「Convert to layers」转为普通图层快照。
• 脚本在沙箱中运行:无 DOM、网络、文件系统访问,必须同步执行(无 async / setTimeout)。
• Math.random() 是确定性的(每次运行重新播种):相同输入必得相同输出。
• 报错和缺失文件直接显示在节点上并高亮出错行,无需开控制台。

API 速查

文件头

/**
 * @schema <version>     // 必填,当前 schema 版本为 2.14
 * @input <name>: <type>[(<args>)] [= <default>]   // 0 或多个
 */

输入类型

pencil 全局对象

设计库 Design Libraries

原文:Core Concepts / Design Libraries

设计库是可被其他 .pen 文件导入的组件集合。修改库文件中的组件,变更会同步到所有使用处。

创建设计库

1. 新建一个 .pen 文件并填充组件
2. 在左侧图层面板点击 "Libraries" 图标
3. 点击底部 "Turn this file into a library"

导入库到文件

图层面板 → "Libraries" 图标 → 选择要导入的库(也可从默认库中选取)。

使用库资产

图层面板 → "Assets" 图标 → 在网格中滚动浏览或按名称搜索 → 拖拽或点击放置到画布。

导入与导出

原文:Core Concepts / Import & Export

导入

导出

• 设计转代码:按 Cmd/Ctrl + K 打开 AI 聊天,让它基于设计生成代码。
• 导出单个元素:选中元素 → 属性面板底部选择尺寸与格式(PNG / JPEG / WEBP / PDF)→ 点击 Export layer 选择位置保存。

键盘快捷键

原文:Core Concepts / Keyboard Shortcuts

AI 聊天

工具

编辑

选择

组件

画布导航

画布设置与文件操作

设计 ↔ 代码

原文:Design and Code / Design ↔ Code

pen.dev 支持设计与代码之间的双向工作流:设计 → 代码(从 pen.dev 设计生成组件)、代码 → 设计(把既有代码导入 pen.dev)。

设计 → 代码

1. 在 pen.dev 画布上设计屏幕、布局或单个 UI 组件
2. 把 .pen 文件保存在项目工作区内
3. 按 Cmd/Ctrl + K 打开 AI 聊天
4. 让 pen.dev 生成代码

代码 → 设计

代码库中已有的组件,pen.dev 可以在画布上可视化重建。前提:.pen 文件与代码在同一工作区,AI 代理能同时访问两者。

Recreate the Button component from src/components/Button.tsx
Import the LoginForm from my codebase into this design
Add the Header component from src/layouts/Header.tsx

会导入什么:组件结构与层级、布局与定位、样式(颜色、字体、间距)。

双向同步

最强大的工作流是两个方向结合:

1. 从代码开始 — 把既有组件导入 pen.dev
2. 在 pen.dev 中做视觉改进
3. 让 AI 把改动写回代码
4. 循环迭代

变量与设计令牌同步

• CSS → pen.dev:"Create pen.dev variables from my globals.css" / "Import design tokens from src/styles/tokens.css"
• pen.dev → CSS:"Update globals.css with these pen.dev variables" / "Sync these design tokens to my CSS"

最佳实践

文件组织:把 .pen 放进仓库

my-project/
├── src/
│   ├── components/
│   └── styles/
├── design.pen           ← 设计文件
└── package.json

好处:AI 代理同时看得到设计与代码;版本控制统一跟踪两者;同步维护更容易。

工作流建议

• 新功能:先在 pen.dev 设计 → 生成初版代码 → 打磨实现 → 需要时回写设计。
• 改既有功能:组件导入 pen.dev → 修改设计 → 同步回代码。
• 设计系统维护:在 pen.dev 定义变量 → 同步到 CSS → 设计与代码共用变量 → 一处更新、处处生效。

常用技术栈

pen.dev 不绑定框架,可要求 AI 面向任意技术栈生成代码。常见选择:框架(React / Next.js / Vue / Svelte / 纯 HTML+CSS)、样式(Tailwind CSS / CSS Modules / Styled Components / 纯 CSS)、组件库(shadcn/ui / Radix UI / Chakra UI / Material UI / 自有组件)。在提示词中写明你的技术栈,例如:"Generate Next.js 14 code with Tailwind CSS"。

图标库

pen.dev 内置 Material Symbols(Outlined/Rounded/Sharp)、Lucide、Feather、Phosphor,自有 SVG 图标可按图片方式导入。生成代码时在提示词指定偏好库(Lucide、Heroicons、FontAwesome、React Icons 等),例如:"Generate this design using Lucide icons"。

故障排查

原文:Troubleshooting

安装与设置

• 扩展已装但不工作(无图标 / 打不开 .pen):确认 Claude Code 已登录(claude)→ 完成邮箱激活 → 检查 MCP 已连接(Settings → MCP)→ 新建 .pen 文件试开 → 重启 IDE → 仍不行则重装。
• 看不到 pen.dev 图标:新建并打开 .pen 文件;检查扩展版本;命令面板搜 "pen.dev";确认扩展已启用。

认证与激活

• 收不到激活邮件:查垃圾邮件 → 等几分钟 → 换邮箱 → 卡住就重装扩展。
• "Invite not found":重装扩展重新激活,持续出现联系支持。
• 反复要求激活:重启 IDE、重新激活一次、必要时重装。
• Claude Code 连接类问题:见认证与激活一节的完整排查步骤。

IDE 相关

• Cursor:提示框不出现 → 检查激活/登录、重启、验证 MCP、重装;"You need Cursor Pro" → 检查订阅,或先用基础功能。
• VS Code:扩展不激活 → 确保打开了 .pen 文件、检查扩展启用状态、看开发者工具控制台报错、重装。

欢迎文件与新项目

• 没拿到欢迎文件:画布任意处右键 → Open Welcome File(可能在独立窗口打开)。
• 新项目接入 pen.dev 的推荐姿势:在工作区创建 design.pen → 在 IDE 打开 → 激活 pen.dev → 让 .pen 与代码同仓库,AI 才能两边都看到。

画布与界面

• 嵌套元素难选中:Cmd/Ctrl + 点击 直选最深层;Shift + Enter 选父级;或直接用图层面板。
• 选择框颜色含义:蓝色 = 普通元素;品红/紫色 = 可复用组件及其实例。
• 转组件后没显示品红框:先取消选择再重新选中即可出现。

导入与导出

• macOS 图片导入失败:File 菜单方式可能失败——改用拖拽,各平台都稳定。
• Figma 图片粘不过来:已知限制,复制粘贴不支持图片——改用 SVG 或单独重新导入。
• 导出到 Claude Code 失败("Process exited with code 1"):检查 Claude Code 认证与权限;换独立 Claude Code 会话导出;检查环境变量。
• 导出结果与画布不一致:已知问题——截图留档、重新导出、调整设计再试,并向官方报告具体案例。

MCP 与 AI

• MCP 是本地还是远程?本地运行,设计操作无云端依赖。验证:Cursor 在 Settings → Tools & MCP;Codex 运行 /mcp。
• Codex config.toml 被改动:首次使用前备份;官方已在调查。
• AI 无法访问文件夹 / 权限弹窗不出现:接受权限提示、检查系统权限,或换独立会话执行。

保存与版本控制

• 没有自动保存(计划中):勤按 Cmd/Ctrl + S,用 Git 提交做版本历史。
• 撤销/重做有限:大改动前先保存/提交;小步修改;需要时用 Git 回滚。
• 没有实时协作:目前通过 Git 协作——分支并行、pull → 编辑 → commit → push → PR,用 PR 评审设计。

平台相关

• Linux:桌面应用可用;Wayland/Hyprland 可能有 UI 问题,X11 更稳,必要时退回 IDE 扩展。
• Windows:如桌面应用不可用,使用 VS Code / Cursor 扩展,功能一致。

获取更多帮助

问题仍未解决时,按以下顺序排查:

1. 回查相关文档:Installation(安装)、Authentication(认证)、AI Integration(AI 集成)
2. 把所有组件更新到最新版本:pen.dev、Claude Code CLI、IDE
3. 尝试全新重装:卸载扩展 → 清除扩展数据 → 重新安装
4. 联系支持时请附上:你的平台(macOS/Windows/Linux)、pen.dev 版本、IDE 及版本、准确的错误信息、复现步骤

报告 Bug

报告问题时,请提供以下信息:

• 环境信息:操作系统及版本、IDE(VS Code/Cursor/Desktop)及版本、pen.dev 版本、Claude Code CLI 版本
• 问题详情:你想做什么、实际发生了什么、准确的错误信息、复现步骤
• 有帮助的附加材料:截图、控制台日志(如有)、能复现问题的最小 .pen 文件

常见错误信息速查

预防清单

1. 勤保存(尚无自动保存)
2. 保持 Claude Code 认证有效
3. .pen 文件放在项目工作区内
4. 定期提交 Git
5. 定期更新 pen.dev 与 Claude Code
6. 接受权限提示
7. 使用受支持的工作流(不要手动编辑 .pen 文件)

.pen 文件格式

原文:For Developers / The .pen Format

总览

• .pen 文件是一个 JSON 结构,描述一棵对象树(类似 HTML 或 SVG)。
• 每个对象都是无限二维画布上的图形实体。
• 对象必须有文档内唯一的 id,以及 type(如 rectangle、frame、text、script 等)。

布局

• 顶层对象放在无限画布上,由 x、y 描述左上角位置;嵌套对象相对父级左上角定位。
• 父对象可通过 layout、justifyContent、alignItems 等属性以 Flexbox 风格接管子级的尺寸与定位。
• 子对象可选择填满父级(fill_container)或固定宽高;父对象可选择适配子级(fit_content)或固定宽高。

图形外观

• 由 fill(填充)、stroke(描边)、effect(效果)控制。
• 填充可以是纯色、渐变(线性/径向/角度)、图片、网格渐变(mesh gradient),甚至 WebGL 着色器;一个对象可叠多层填充,按文档顺序绘制。
• 描边只有一条,但描边可以有多层填充;效果(模糊、背景模糊、内/外阴影)可叠加,按顺序应用。

组件与实例

.pen 与 HTML/SVG 的关键差异:文档中的对象树片段可以在别处复用——这就是组件系统。

定义组件:reusable: true

{
  "id": "foo",
  "type": "rectangle",
  "reusable": true,   // ← 这个对象现在是可复用组件
  "x": 0, "y": 0, "width": 100, "height": 100,
  "fill": "#FF0000"
}

创建实例:type: "ref"

{
  "id": "bar",
  "type": "ref",
  "ref": "foo",       // ← foo 的一个实例(同样是 100×100 红色方块)
  "x": 120, "y": 0
}

属性覆盖(Overrides)

实例可以覆盖组件定义中的属性——下例 baz 仍是 foo 的实例,但把继承的填充覆盖成了蓝色:

{
  "id": "baz",
  "type": "ref",
  "ref": "foo",
  "x": 240, "y": 0,
  "fill": "#0000FF"   // ← 100×100 的蓝色方块
}

嵌套定制:descendants

实例会复制组件根之下的一切;通过 descendants 映射可以定制内部任意后代节点(键为后代 id,嵌套实例内的后代用 实例id/后代id 路径):

{
  "id": "red-round-button",
  "type": "ref",
  "ref": "round-button",
  "fill": "#FF0000",
  "descendants": {
    "label": {                // ← 定制组件内部 id 为 label 的节点
      "text": "Cancel",
      "fill": "#FFFFFF"
    }
  }
}

规则:descendants 条目里不含 type 表示属性覆盖;含 type 表示整节点替换。也可以保留节点本身、只替换其 children(适合面板、卡片、侧边栏等容器型组件)。组件可以由其他组件的实例组合而成。

插槽(格式层)

当组件内某个 Frame 就是为「被替换 children」而生时,用 slot 属性标记,数组值为建议放入的组件 id 列表:

{
  "id": "content",
  "type": "frame",
  "slot": ["round-button", "icon-button"]   // ← 建议投放的组件
}

变量与主题

常用颜色和数值(内边距、圆角、不透明度等)可提取为文档级变量,引用时加 $ 前缀:

{
  "variables": {
    "color.background": { "type": "color", "value": "#FFFFFF" },
    "text.title":       { "type": "number", "value": 72 }
  },
  "children": [
    { "id": "page", "type": "frame", "fill": "$color.background",
      "children": [
        { "id": "title", "type": "text", "fontSize": "$text.title", "content": "Welcome!" }
      ]
    }
  ]
}

主题系统:变量可以有多个值,每个值绑定一组主题条件;求值时,最后一个主题条件满足的值胜出。主题轴在文档级 themes 中声明(每根轴的默认值是第一个),对象通过 theme 属性切换其子树的主题:

{
  "variables": {
    "color.background": {
      "type": "color",
      "value": [
        { "value": "#FFFFFF", "theme": { "mode": "light" } },
        { "value": "#000000", "theme": { "mode": "dark" } }
      ]
    }
  },
  "themes": { "mode": ["light", "dark"] },
  "children": [
    { "id": "page-dark", "type": "frame",
      "theme": { "mode": "dark" },        // ← 该子树全部使用 dark 主题
      "fill": "$color.background" }       // ← 求值为 #000000
  ]
}

节点类型与文档结构速查

文档级字段:version(当前为 "2.14")、themes、imports(导入其他 .pen 文件,键为别名、值为相对路径)、variables(boolean/color/number/string 四类)、children。完整 TypeScript Schema(所有属性、Fill/Effect/Layout 的全部取值)请见官方原文。

pen.dev CLI

原文:For Developers / pen.dev CLI

pen.dev CLI 是独立的命令行工具,可在终端创建和编辑 .pen 文件。它运行与桌面应用/IDE 扩展相同的编辑器引擎,完全无头(headless)、无需 GUI。可用于:带提示词运行 AI 代理、在交互式 shell 中直接调用 MCP 工具、批量处理多个设计、导出 PNG/JPEG/WEBP/PDF。

安装

npm install -g @pen.dev/cli

# 验证安装(需要 Node.js 18+)
pen version

认证

快速开始

# 登录
pen login

# 从零创建设计
pen --out design.pen --prompt "Create a login page with email and password fields"

# 修改现有设计
pen --in existing.pen --out modified.pen --prompt "Add a blue submit button"

# 导出 PNG
pen --in design.pen --export design.png

# 交互式 shell
pen interactive -o design.pen

# 列出可用模型
pen --list-models

Agent 模式选项

可用模型

交互模式

pen interactive 启动一个可直接对 .pen 文件调用 MCP 工具的 shell——适合脚本化、调试和需要精细控制设计操作的 agentic 工作流。

• App 模式:pen interactive -a desktop -i my-design.pen — 通过 WebSocket 连接正在运行的桌面应用/扩展,改动实时生效。
• Headless 模式:pen interactive -i input.pen -o output.pen — 本地拉起无 GUI 编辑器,用 save() 写盘。

# shell 内可用命令
tool_name({ key: value })   // 带参调用 MCP 工具
tool_name()                 // 无参调用
save()                      // 保存文档到磁盘
exit()                      // 退出

# 示例会话(2026-07-27 起工具集已改为 execute / get_app_state / get_screenshot / export_nodes / get_guidelines 五个,见下方「支持的 MCP 工具」)
pen > get_app_state({ include_schema: true })
pen > get_guidelines()
pen > execute({ operations: 'hero=Insert(document,{type:"frame",name:"Hero",x:0,y:0,width:1440,height:900,fill:"#0A0A0A"})' })
pen > get_screenshot({ nodeId: "hero" })
pen > save()
pen > exit()

批量处理

pen --tasks batch.json 按 JSON 文件顺序执行多个任务,每个任务独立的编辑器实例。任务字段:out(必填)、prompt(必填)、in、model。

{
  "tasks": [
    { "out": "landing-page.pen",
      "prompt": "Create a SaaS landing page with hero, features, and pricing sections" },
    { "in": "existing-app.pen", "out": "existing-app-v2.pen",
      "prompt": "Add a dark mode toggle to the header" },
    { "out": "mobile-menu.pen", "model": "claude-haiku-4-5",
      "prompt": "Create a mobile hamburger menu component" }
  ]
}

支持的 MCP 工具

来源:官方 pen.dev CLI · Supported MCP Tools(核对方式:直接抓取页面原始 HTML 逐条比对,WebFetch 摘要在这个页面上给出过不一致的结果,不作为唯一依据)。官方文档未给出 execute 的完整参数 JSON 示例,示例会话里的操作名是根据文档文字描述转写的,不保证与实际调用签名逐字一致。

CI/CD 与环境变量

export PEN_CLI_KEY=pen_cli_...
export ANTHROPIC_API_KEY=sk-ant-...

pen --out onboarding.pen --prompt "Create a 3-step onboarding flow"

CLI 与桌面应用使用不同的会话文件(~/.pencil/session-cli.json,这个路径官方未随品牌更名调整),便于后端区分客户端类型。