企业官网建设流程全解析

• 前端
• 桌面应用
• AI 应用
• MCP 服务

OpenPencil 把设计文件当作结构化数据处理：编辑器中每一项操作——创建形状、设置填充、配置自动布局、导出资源——都同时暴露给终端、AI Agent 与代码，无需安装插件、无需 API Key、无需排队等待。本文围绕 packages/docs/de/programmable/index.md 梳理这套自动化体系的全貌：编辑器界面与自动化接口共享同一内核引擎，一个操作无论由点击、脚本还是 Agent 触发，行为完全一致；读完本文，你将掌握 AI-Chat、CLI、JSX-Renderer、MCP-Server 以及协作能力的入口、用法与底层实现证据。

核心理念：设计文件即数据，界面与脚本同源

OpenPencil 的自动化设计遵循一条基本原则：编辑器 UI 与自动化接口使用同一个引擎。凡是你能在画布上点击完成的操作，都能用脚本完成。

OpenPencil behandelt Designdateien als strukturierte Daten. Vorgänge aus dem Editor — Formen erstellen, Füllungen ändern, automatische Anordnung konfigurieren oder Ressourcen exportieren — stehen auch über CLI, AI-Agenten und APIs zur Verfügung.（OpenPencil 将设计文件视为结构化数据。编辑器中的操作——创建形状、修改填充、配置自动排列或导出资源——同样可通过 CLI、AI Agent 和 API 使用。）

这一理念决定了项目的工程形态：它不只是“一个设计应用”，更是一套“工具箱”——可以被嵌入其他产品、包裹自定义 UI、构建贴合特定领域的编辑工作流。App、CLI、AI 工具、JSX 渲染器、MCP 服务器与 SDK 全部构建在同一编辑引擎之上。从源码结构看，这一分层在仓库中清晰可见：packages/core 承载可复用的编辑内核，src/app/editor 与 packages/vue 提供界面层，而 packages/cli、packages/mcp 则是同一内核的外部自动化入口。

AI-Chat：内置助手与 90+ 工具

桌面端内置的 AI 助手可以执行90 多个工具，覆盖编辑器的全部能力面。一条自然语言指令就能完成复杂操作，例如：

• 给所有按钮添加 16px 投影；
• 创建一个带暗色变体的卡片组件；
• 将页面上的每个 Frame 按 2× 比例导出。

按⌘J（macOS）或CtrlJ（Windows/Linux）即可打开助手面板，详细使用说明见 AI-Chat 文档。

模型配置步骤

1. 打开 AI-Chat；
2. 选择设置图标；
3. 添加模型，并配置提供商、模型标识符、访问凭据与能力项；
4. 保存模型并分配给Design agent角色。

可以配置多个模型，分别用于设计生成、代码审查、快速任务与图像输入；同一提供商连接下的多个模型共享同一份安全存储的凭据。

支持的提供商

请求直接发往提供商。在浏览器中运行时受其 CORS 规则约束；不同部署在“工具调用是否可靠流式返回”上存在差异，可参考 BYOK 提供商兼容性 的实测数据。

外部 MCP 连接

桌面 ACP Agent 可以接入可信的远程 MCP 服务器：在设置 → MCP 连接中添加一个 Streamable-HTTP 端点，可选保存 Bearer Token 并启用连接。Token 存储在系统凭据存储中，仅在 ACP 会话启动时读取；远程服务器必须使用 HTTPS，本地开发允许通过 HTTP 访问回环地址。

工具面与视觉校验

AI 助手的 90+ 工具覆盖创建、样式、布局、组件、变量、搜索、校验、分析、导出与矢量编辑等类别。改动之后，助手可以调用export_image将结果渲染出来与请求对比，从而暴露出布局错误、缺失元素与颜色偏差。

从源码看，工具目录由核心包统一暴露：@open-pencil/core/tools提供ALL_TOOLS全集与CORE_TOOLS默认集，AI 侧通过isToolExposed(tool, 'ai')过滤出对 AI 暴露的定义，并区分读写效果（toolChangesDocument），见 src/app/ai/tools/catalog.ts。

使用建议（来自 ai-chat.md）：

• 请求前先选中相关对象，助手识别当前选区；
• 尽量精确描述颜色、尺寸与位置；
• 一条消息可以同时修改多个对象；
• AI 产生的修改可撤销；
• 每次工具调用后自动布局会重新计算。

协作：WebRTC 点对点同步与 CRDT 合并

OpenPencil 通过WebRTC 在参与者之间直接同步文档，共享一个房间链接即可，不需要中心服务器，也不需要账号。参与者的光标与会话跟踪（follow mode）让每个人看到他人所在位置；状态通过CRDT（Yjs）同步，即使在弱网环境下，并发编辑也能自动合并。

这一点与“数据本地化”理念一脉相承：文档留在本地与对等网络，不依赖某个托管方。详细说明见 协作文档，相关实现位于 src/app/collab（含 room.ts、yjs-sync.ts 等模块）。

JSX-Renderer：双向转换的声明式界面描述

JSX-Renderer允许以声明式 JSX 描述界面——这正是 LLM 从 React 生态早已熟悉的语法。一次调用即可创建完整组件树：包含 Frame、文本、自动布局、填充与描边；紧凑、声明式、可 diff。

反方向同样成立：把任意选区导出回JSX + Tailwind 类名，可作为交给开发实现、代码审查或再次喂给 LLM 的起点。

// 示意：一次调用创建带自动布局的完整组件树 <frame name="Card" width={320} autoLayout="vertical" padding={16}> <text name="Title" fontSize={20} fontWeight={700}>标题</text> <text name="Body" fill="#6b7280">正文内容</text> </frame>

渲染器实现在 packages/dom-css/src/jsx（含 core.ts、runtime.ts），文档见 JSX-Renderer。

CLI：不开编辑器也能检查、导出、分析设计文档

CLI 让你在不打开编辑器的情况下检查、导出并分析.fig/.pen文档：列出页面与对象、搜索内容、提取设计令牌、渲染 PNG，并输出机器可读的 JSON 供后续处理。此外，CLI 还能通过RPC 控制正在运行的桌面编辑器。

命令总览

主程序位于 packages/cli/src/index.ts，入口为openpencil，注册了 17 个子命令：

四类典型用法分别见 检查文件、导出、分析设计 与 脚本化 四篇文档。CLI 的 JSON 输出与无头（headless）能力使它可以嵌入 CI 流水线，例如对设计文件做静态检查后失败构建。

MCP-Server：让 Claude Code、Cursor、Windsurf 直接改设计

MCP 服务器 把内置 AI-Chat 使用的同一批90 个工具暴露给任何 MCP 兼容客户端——Claude Code、Cursor、Windsurf 等都可以直接读取、创建、修改设计。服务器支持stdio 与 HTTP 两种传输，HTTP 模式下带会话支持。

从源码看，工具注册体系位于 packages/mcp/src/tool：index.ts 导出元数据与禁用策略序列化，registration.ts、policy.ts 等模块负责工具清单与权限策略；HTTP 传输与认证实现见 packages/mcp/src/transport 与 auth.ts。这意味着团队可以把自己的 LLM 工作流（代码审查、设计走查、批量改稿）直接接到设计数据上，而不必通过截图或手工导出来回搬运。

URL Scheme：从任意页面直达图层

桌面应用注册了openpencil://协议，发布出去的页面——Storybook story、设计评审页、README——可以一键链接到指定图层：

openpencil://open?file=web/design/hikyo.pen&node=Button/Large/Default

• file是以.pen或.fig结尾的仓库相对路径；绝对路径以及含.、..段的内容会被拒绝；node可选。
• 两个参数都需 URL 编码：路径分隔符可保留字面值，但字面+必须写成%2B；重复的键取最后一个值。
• 应用将file与已打开标签页路径按整体尾段序列匹配，命中后聚焦该标签而不重新读文档，因此文件移动或不可读后仍能选中图层；第一个路径尾段匹配的标签页优先（两个检出同时打开同一文件时很关键）。
• 段比较遵循平台文件系统规则：macOS/Windows 上 ASCII 大小写不敏感，Linux 上严格区分——Web/Design/hikyo.pen与web/design/hikyo.pen在 Mac 上是同一文件、在 Linux 上是两个文件。
• 若无匹配标签页，会弹出一次文件选择器，所选文件必须以同一相对路径结尾，否则链接被取消；不拼接根路径、不授予选择器返回值之外的任何文件系统访问权。
• 带node时，应用在当前页面选中所有同名图层并把视口缩放到整个选区；名字不存在时提示并保持文档打开。

Web 端从地址栏接收同样的链接：

https://app.openpencil.dev/?file=https://raw.githubusercontent.com/.../pencil_button.pen&node=Button/Large/Default

• 这里file必须是以.pen/.fig结尾的绝对https:URL（Web 端没有文件系统，相对路径、http:或其它扩展名都会被拒绝并给出控制台警告）；扩展名取自 URL 路径，因此链接文件上的查询串不改变结果。
• fragment 在 fetch 前被丢弃，…hikyo.pen#a与…hikyo.pen#b打开同一个标签页。
• 浏览器跨源取文件，因此宿主必须放行 CORS：raw.githubusercontent.com返回Access-Control-Allow-Origin: *，可用；请求不带凭据、且不跟随重定向——https://github.com/<owner>/<repo>/raw/...会跳转到 raw 主机，因此被拒绝，请直接链接 raw 主机。
• 链接文档上限64 MiB：按流式收到的 body 计数而非信任Content-Length，超限即中止并报告；部署若启用 CSP，需在connect-src中放行链接主机。
• macOS 上 scheme 归属已安装的 App bundle；Windows/Linux 经由 deep-link 插件送达，即使应用未启动也会在启动时排队、编辑器就绪后处理（Linux 通过桌面入口的%U传递）。实现见 desktop/src/deep_link.rs 与 desktop/src/credentials.rs。

为什么“开放”是关键

Figma 是封闭平台：其 MCP 服务器只读、CDP 浏览器访问在版本 126 被移除、设计文件以专有格式存放在他人服务器上、插件开发依赖受限的自定义运行时。OpenPencil 是相反的路线：

• 开源 + MIT 许可证；
• 每个操作都可脚本化；
• 数据存储在本地。

你的设计文件属于你：可以检查、转换、接入 CI、交给 LLM 作为上下文，无需任何许可，也不绑定某个托管服务商。仓库采用 MIT 协议（见 LICENSE），文档默认本地保存，.fig文件可完全脱离图形界面被程序化处理。

实践入口速览

无论是把 OpenPencil 嵌入自有产品、用脚本批量处理设计资产，还是让 Agent 直接驱动画布，这套“同一引擎、多面出口”的架构都能让设计与工程、AI 工作流无缝衔接——而这一切都不需要离开本地数据与开源代码。

• 前端
• 桌面应用
• AI 应用
• MCP 服务