openpencil/README.zh.md

OpenPencil

全球首个 AI 原生开源矢量设计工具。
_{并发 Agent 团队 • 设计即代码 • 内置 MCP 服务器 • 多模型智能}

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

_{点击图片观看演示视频}

为什么选择 OpenPencil

🎨 提示词 → 画布 用自然语言描述任意 UI，实时以流式动画在无限画布上生成。选中已有元素，通过对话即可修改设计。	🤖 并发 Agent 团队 编排器将复杂页面分解为空间子任务。多个 AI 智能体同时处理不同区块 — Hero、功能区、页脚 — 全部并行流式生成。
🧠 多模型智能 自动适配每个模型的能力。Claude 获得完整提示词和思考模式；GPT-4o/Gemini 关闭思考模式；小模型（MiniMax、Qwen、Llama）使用简化提示词以确保输出可靠性。	🔌 MCP 服务器 一键安装到 Claude Code、Codex、Gemini、OpenCode、Kiro 或 Copilot CLI。从终端进行设计 — 通过任意 MCP 兼容的智能体读取、创建和修改 .op 文件。
📦 设计即代码 .op 文件是 JSON — 人类可读、对 Git 友好、可进行 diff 对比。设计变量生成 CSS 自定义属性。代码导出为 React + Tailwind 或 HTML + CSS。	🖥️ 全平台运行 Web 应用 + 通过 Electron 支持 macOS、Windows 和 Linux 原生桌面端。从 GitHub Releases 自动更新。.op 文件关联 — 双击即可打开。

快速开始

# 安装依赖
bun install

# 在 http://localhost:3000 启动开发服务器
bun --bun run dev

或以桌面应用形式运行：

bun run electron:dev

前置条件： Bun >= 1.0 以及 Node.js >= 18

Docker

提供多个镜像变体 — 按需选择：

镜像	大小	包含
openpencil:latest	~226 MB	仅 Web 应用
openpencil-claude:latest	—	+ Claude Code CLI
openpencil-codex:latest	—	+ Codex CLI
openpencil-opencode:latest	—	+ OpenCode CLI
openpencil-copilot:latest	—	+ GitHub Copilot CLI
openpencil-gemini:latest	—	+ Gemini CLI
openpencil-full:latest	~1 GB	全部 CLI 工具

运行（仅 Web）：

docker run -d -p 3000:3000 ghcr.io/zseven-w/openpencil:latest

运行 AI CLI（以 Claude Code 为例）：

AI 聊天依赖 Claude CLI 的 OAuth 登录。使用 Docker volume 持久化登录会话：

# 第一步 — 登录（仅需一次）
docker volume create openpencil-claude-auth
docker run -it --rm \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest claude login

# 第二步 — 启动
docker run -d -p 3000:3000 \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest

本地构建：

# 基础版（仅 Web）
docker build --target base -t openpencil .

# 指定 CLI
docker build --target with-claude -t openpencil-claude .

# 完整版（全部 CLI）
docker build --target full -t openpencil-full .

AI 原生设计

提示词生成 UI

• 文字转设计 — 描述一个页面，实时以流式动画在画布上生成
• 编排器 — 将复杂页面分解为空间子任务，支持并行生成
• 设计修改 — 选中元素后，用自然语言描述更改
• 视觉输入 — 附加截图或线框图作为参考进行设计

多智能体支持

智能体	配置方式
Claude Code	无需配置 — 使用 Claude Agent SDK 本地 OAuth
Codex CLI	在 Agent 设置中连接（Cmd+,）
OpenCode	在 Agent 设置中连接（Cmd+,）
GitHub Copilot	运行 copilot login 后在 Agent 设置中连接（Cmd+,）
Gemini CLI	在 Agent 设置中连接（Cmd+,）

模型能力配置 — 自动根据模型层级适配提示词、思考模式和超时时间。完整层级模型（Claude）获得完整提示词；标准层级模型（GPT-4o、Gemini、DeepSeek）关闭思考模式；基础层级模型（MiniMax、Qwen、Llama、Mistral）使用简化的嵌套 JSON 提示词以确保最大可靠性。

MCP 服务器

• 内置 MCP 服务器 — 一键安装到 Claude Code / Codex / Gemini / OpenCode / Kiro / Copilot CLI
• 自动检测 Node.js — 若未安装则自动回退到 HTTP 传输模式并启动 MCP HTTP 服务器
• 从终端进行设计自动化：通过任意 MCP 兼容的智能体读取、创建和修改 .op 文件
• 分层设计工作流 — design_skeleton → design_content → design_refine，实现更高保真度的多区块设计
• 分段提示词检索 — 按需加载所需的设计知识（schema、layout、roles、icons、planning 等）
• 多页面支持 — 通过 MCP 工具创建、重命名、重新排序和复制页面

代码生成

• React + Tailwind CSS、HTML + CSS、CSS Variables
• Vue、Svelte、Flutter、SwiftUI、Jetpack Compose、React Native

功能特性

画布与绘图

• 无限画布，支持平移、缩放、智能对齐参考线和吸附
• 矩形、椭圆、直线、多边形、钢笔（贝塞尔）、Frame、文本
• 布尔运算 — 联合、减去、交集，配合上下文工具栏
• 图标选择器（Iconify）和图片导入（PNG/JPEG/SVG/WebP/GIF）
• 自动布局 — 垂直/水平方向，支持间距、内边距、主轴对齐、交叉轴对齐
• 多页面文档，支持标签页导航

设计系统

• 设计变量 — 颜色、数字、字符串令牌，支持 $variable 引用
• 多主题支持 — 多个主题轴，每个轴有多个变体（浅色/深色、紧凑/舒适）
• 组件系统 — 可复用组件，支持实例和覆盖
• CSS 同步 — 自动生成自定义属性，代码输出中使用 var(--name)

Figma 导入

• 导入 .fig 文件，保留布局、填充、描边、效果、文本、图片和矢量图形

桌面应用

• 通过 Electron 支持原生 macOS、Windows 和 Linux
• .op 文件关联 — 双击即可打开，单实例锁定
• 从 GitHub Releases 自动更新
• 原生应用菜单和文件对话框

技术栈

前端	React 19 · TanStack Start · Tailwind CSS v4 · shadcn/ui
画布	CanvasKit/Skia（WASM, GPU 加速）
状态管理	Zustand v5
服务器	Nitro
桌面端	Electron 35
AI	Anthropic SDK · Claude Agent SDK · OpenCode SDK · Copilot SDK
运行时	Bun · Vite 7
文件格式	.op — 基于 JSON，人类可读，对 Git 友好

项目结构

openpencil/
├── apps/
│   ├── web/                 TanStack Start Web 应用
│   │   ├── src/
│   │   │   ├── canvas/      CanvasKit/Skia 引擎 — 绘图、同步、布局
│   │   │   ├── components/  React UI — 编辑器、面板、共享对话框、图标
│   │   │   ├── services/ai/ AI 聊天、编排器、设计生成、流式处理
│   │   │   ├── stores/      Zustand — 画布、文档、页面、历史、AI
│   │   │   ├── mcp/         供外部 CLI 集成使用的 MCP 服务器工具
│   │   │   ├── hooks/       键盘快捷键、文件拖放、Figma 粘贴
│   │   │   └── uikit/       可复用组件套件系统
│   │   └── server/
│   │       ├── api/ai/      Nitro API — 流式聊天、生成、验证
│   │       └── utils/       Claude CLI、OpenCode、Codex、Copilot 客户端封装
│   └── desktop/             Electron 桌面应用
│       ├── main.ts          窗口、Nitro 子进程、原生菜单、自动更新
│       ├── ipc-handlers.ts  原生文件对话框、主题同步、偏好设置 IPC
│       └── preload.ts       IPC 桥接
├── packages/
│   ├── pen-types/           PenDocument 模型类型定义
│   ├── pen-core/            文档树操作、布局引擎、变量
│   ├── pen-codegen/         代码生成器（React、HTML、Vue、Flutter 等）
│   ├── pen-figma/           Figma .fig 文件解析与转换
│   ├── pen-renderer/        独立 CanvasKit/Skia 渲染器
│   └── pen-sdk/             聚合 SDK（重新导出所有包）
└── .githooks/               预提交钩子：从分支名同步版本号

键盘快捷键

按键	操作		按键	操作
V	选择		Cmd+S	保存
R	矩形		Cmd+Z	撤销
O	椭圆		Cmd+Shift+Z	重做
L	直线		Cmd+C/X/V/D	复制/剪切/粘贴/重复
T	文本		Cmd+G	编组
F	Frame		Cmd+Shift+G	取消编组
P	钢笔工具		Cmd+Shift+E	导出
H	手形（平移）		Cmd+Shift+C	代码面板
Del	删除		Cmd+Shift+V	变量面板
[ / ]	调整层级顺序		Cmd+J	AI 聊天
方向键	微移 1px		Cmd+,	智能体设置
Cmd+Alt+U	布尔联合		Cmd+Alt+S	布尔减去
Cmd+Alt+I	布尔交集

脚本命令

bun --bun run dev          # 开发服务器（端口 3000）
bun --bun run build        # 生产构建
bun --bun run test         # 运行测试（Vitest）
npx tsc --noEmit           # 类型检查
bun run bump <version>     # 同步所有 package.json 的版本号
bun run electron:dev       # Electron 开发模式
bun run electron:build     # Electron 打包

参与贡献

欢迎贡献！请查阅 CLAUDE.md 了解架构细节和代码风格。

1. Fork 并克隆仓库
2. 设置版本同步：git config core.hooksPath .githooks
3. 创建分支：git checkout -b feat/my-feature
4. 运行检查：npx tsc --noEmit && bun --bun run test
5. 使用 Conventional Commits 提交：feat(canvas): add rotation snapping
6. 向 main 分支发起 PR

路线图

• 设计变量与令牌，支持 CSS 同步
• 组件系统（实例与覆盖）
• 带编排器的 AI 设计生成
• MCP 服务器集成与分层设计工作流
• 多页面支持
• Figma .fig 导入
• 布尔运算（合并、减去、相交）
• 多模型能力配置
• Monorepo 重构与可复用包
• 协同编辑
• 插件系统

贡献者

社区

加入我们的 Discord — 提问、分享设计、提出功能建议。

Star History

许可证

MIT — Copyright (c) 2026 ZSeven-W