企业官网建设流程全解析

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

导读

OpenPencil 内置的 AI 聊天助手（AI Chat）是一个拥有90+ 设计工具的原生智能体（Agent）：你只需用自然语言描述意图，它就能创建图形、调整样式、管理布局、操作组件，甚至分析整个文档。本文以官方文档 packages/docs/es/programmable/ai-chat.md 为核心骨架，结合仓库源码，系统讲解从模型 Profile 配置、多角色分配，到 BYOK（Bring Your Own Key）提供商直连、ACP 代理与远程 MCP 接入、工具目录与隐私成本的完整实战链路。读完本文，你将能够独立完成 AI 助手的模型接入、角色编排与工具权限管理，并理解其"无后端、浏览器直连提供商"的架构原理。

快速上手：按 ⌘J 打开内建 AI 助手

在 OpenPencil 编辑器中，按⌘J（macOS）或CtrlJ（Windows/Linux）即可唤起 AI 聊天面板。输入你想要的任意描述后，助手可以：

• 创建形状（frame、矩形、椭圆、文本、组件、页面）
• 修改样式（填充、描边、效果、透明度、圆角、混合模式）
• 配置布局（自动布局、网格、对齐、间距、尺寸）
• 处理组件（创建组件、实例、组件集，管理覆盖 Override）
• 分析当前文档（读取节点、字体、选区，检测设计问题）

每次调用都作用于当前激活的编辑器，并在适用时进入撤销（Undo）历史——对 AI 改动不满意，直接按编辑器里的"撤销"即可回退，AI 产生的变更与手动编辑一样支持完整撤销。每执行一次工具后，布局都会自动重算。

配置模型：从连接、Profile 到角色分配

四步完成首个模型接入

1. 打开 AI 聊天面板（⌘J）
2. 点击面板上的设置图标
3. 添加一个模型 Profile，配置其连接（提供商与端点）、模型 ID、凭据与能力
4. 保存 Profile，并将其分配给Design agent（设计代理）

源码视角：连接与 Profile 的数据结构

从 src/app/ai/models/types.ts 可以看到，模型体系被拆成两层：

• 连接（AIModelConnection）：一条连接代表一个可复用的提供商端点，包含providerID、customBaseURL（自定义 Base URL）、customAPIType（completions或responses两种 API 契约）以及credentialProfileId（凭据引用）。多个模型 Profile 共享同一条连接时，会复用同一条已安全存储的凭据，无需重复填写密钥。
• 模型 Profile（AIModelProfile）：在连接之上定义的模型实例，包含name、modelID/customModelID（自定义模型标识）、maxOutputTokens（最大输出 token）、可选的reasoningEffort（推理强度），以及capabilities（能力数组）。

能力（capabilities）目前有两类，定义在 types.ts：tools（工具调用能力）与vision（视觉/图像理解能力）。保存 Profile 时的校验逻辑位于 src/app/ai/models/settings/profile-editor/schema.ts：当 Profile 用于设计角色时，必须启用tools能力才能保存成功（designToolsRequired校验），否则会提示缺少设计工具。

多 Profile 与角色分配

OpenPencil 支持保存多个可复用模型，并将它们分别分配给不同用途。角色（Role）定义在 types.ts：

分配逻辑实现在 src/app/ai/models/settings/assignments.ts：每个角色可以指定独立 Profile，也可以设置为__design__（"与设计代理相同"，继承设计模型）或__none__（无模型）。这让你可以灵活组合——例如用强大的旗舰模型做设计，用廉价快速的模型处理日常琐碎任务，用专门的视觉模型解析图片输入。

聊天行为相关设置

在设置 → AI 与代理 → 聊天（Chat）中，还可以调整每条消息的最大步骤数（Maximum steps per message）：取值范围为 1～1000 的整数，默认50（常量定义于 src/app/ai/chat/step-limit.ts）。一步（step）即一次模型迭代，一次迭代可以包含多个工具调用；该预算在每条消息开始时被捕获，停止、剩余步骤警告与"继续（Continue）"共用同一预算，修改后对正在运行的请求不生效、下一条消息才采用新值。步骤上限越高，越适合长链条的工具驱动任务，但延迟与提供商成本也会随之上升。聊天面板还支持多行输入自动增高、将当前画布选区"钉"为显式节点上下文，以及按响应展示可折叠的推理过程与复制按钮。

支持的提供商与 BYOK 直连架构

内置提供商适配器

OpenPencil 支持与 OpenAI、Anthropic 协议兼容的连接，以及 OpenRouter、Google、Z.ai 和本地（自定义端点）提供商。从 src/app/ai/providers/registry.ts 可以看到实际注册的适配器：

每个提供商的模型列表与能力各不相同，以各服务商官方为准；API 密钥需要到对应提供商控制台获取。

无中间服务器：浏览器直连

OpenPencil不依赖任何中转服务器：你的密钥（BYOK）直接与提供商对话。这意味着：

• 在**浏览器（Web 构建）**中，请求会直接受到各提供商CORS 策略的约束——若某提供商未正确设置Access-Control-Allow-Origin响应头，浏览器端将无法连接；
• 各提供商对**流式工具调用（streaming tool calls）**的可靠性也因部署而异，同一个模型在不同提供商上可能表现不同；
• 桌面版应用通过 Tauri 原生通道（tauriFetch）发起请求，可绕过浏览器的 CORS 限制。

关于各提供商在浏览器端的 CORS 支持情况与模型工具调用质量的实测记录与复现步骤，参见仓库内的 BYOK 提供商与模型兼容性。该文档是一份持续更新的"活清单"：它记录了截至测试日期（如 2026-07-30/31）各端点 Base URL、浏览器能否直连（如 OpenRouter、OpenAI、Google、DeepSeek、Z.ai、MiniMax、Anthropic、Scaleway、TensorX 等），以及常见的两类失败模式：

• 错误响应路径的 CORS 缺失：部分提供商在 200 成功响应时带Access-Control-Allow-Origin，却在 401/403/500 时省略，导致错误密钥表现为"无法从浏览器访问该端点"的通用网络失败；
• 流式工具调用的缺陷：流式tool_callsdelta 中id缺失、或参数片段被错误路由导致拼接后的 JSON 非法，都会让工具"静默不触发"或直接中断流。

该文档还给出了可复现的 curl 验证脚本（预检 OPTIONS + 成功路径 POST 双重检查）、SSE 流解析验证脚本（按 index 分组、校验首条 delta 的id、拼接参数并JSON.parse），以及"推理模型因输出预算不足而饿死（finish_reason: length却零工具调用）"的排查建议。接入新提供商前，强烈建议先按其中的方法用 curl 验证成功路径的 CORS 头，避免把提供商的问题误判为应用故障。

ACP 代理与远程 MCP 连接

在桌面应用中接入外部智能体

OpenPencil 的桌面应用可以执行ACP（Agent Client Protocol）代理，并将其连接到受信任的、实现了Model Context Protocol（MCP）的远程服务器，从而把外部工具/数据源接入设计工作流。

操作路径：设置（Settings）→ MCP 连接（Connections），添加一条连接，配置：

• 端点：一个Streamable HTTP端点（远程服务器必须使用HTTPS；本地开发时允许 loopback HTTP 端点）；
• 名称：便于识别的连接名；
• Bearer Token（可选）：如服务端要求认证则填写。

保存后，Token 存储在配置的凭据后端（credential backend）中，而非普通设置项，并且只在启动 ACP 会话时才被解析读取。从 src/app/automation/mcp/preferences.ts 可以看到相关设置均以独立键保存在本地存储中（open-pencil:mcp:disabled-tools、open-pencil:mcp:root-directory、open-pencil:mcp:authentication-enabled），包括认证开关、可禁用工具清单与根目录约束等。

启用前请务必审查并信任该服务器：远程 MCP 服务器的工具可能读取外部数据，或以你提供的凭据执行操作。OpenPencil 内置的设计 MCP 服务器会自动附加，无需在此手动添加。此外，远程 MCP 连接、WebMCP 访问与 Pi 代理的 shell/文件系统权限是相互独立的配置域。

工具目录：90+ 设计工具的代理化封装

覆盖的能力类别

按官方文档 packages/docs/es/programmable/ai-chat.md，AI 助手的工具目录覆盖以下类别（实际提供给模型哪些工具，取决于你的工具访问设置）：

• 读取（Query）：查找节点、XPath 选择器、读取属性、列出页面/字体/选区
• 创建（Create）：frame、形状、文本、组件、页面；复杂布局可渲染 JSX
• 修改（Style / Layout）：填充、描边、效果、透明度、圆角、混合模式；自动布局、网格、对齐、间距、尺寸
• 结构（Components）：创建组件、实例、组件集，管理覆盖
• 变量（Variables）：创建/编辑变量、集合、模式，绑定到填充
• 向量（Vector）：布尔运算、路径编辑
• 分析（Analyze）：配色方案、排版审计、间距一致性、簇（cluster）检测
• 描述（Describe）：语义角色识别与设计问题检测
• 代码生成：导出/生成 JSX（含 Tailwind 类）、get_jsx往返视图、diff_jsx结构差异
• 图像（Export / Stock）：PNG/SVG 导出、基于视觉的验证（export_image）、素材图片

源码佐证：默认工具集与可配置开关

从 src/app/ai/tools/catalog.ts 可以看到工具集的构成方式：

• 默认工具集（defaultNames）＝CORE_TOOLS（核心工具集合）＋get_components、list_libraries、insert_library_component，即"紧凑的出厂默认集"；
• 所有暴露给 AI 的可用工具通过ALL_TOOLS.filter(isToolExposed(tool, 'ai'))导出，并按是否修改文档（toolChangesDocument）划分为read（只读）与write（写入/副作用）两类，在"工具访问"界面中分组成组展示与开关；
• 更强大的扩展工具（如create_component）默认关闭，可逐个启用。

工具开关控制的是"模型能调用哪些工具"，并不构成沙箱：一个启用的eval或具备脚本能力的工具，依然可以执行其专属设计工具被禁用掉的同类操作。启用过多工具会增大发送给模型的 schema 体积，请注意权衡。

视觉验证：export_image 截图校验

当启用export_image工具后，助手可以在创建或修改设计后主动截图，并与原始请求核对结果，从而捕捉纯文本回复无法发现的问题——例如布局错位、元素缺失、颜色不匹配。从 packages/core/src/tools/vector/export.ts 的实现看，该工具支持：

• 格式：PNG / JPG / WEBP（默认 PNG）；
• scale：导出倍率，取值范围 0.1～4（默认 1）；
• maxEdge：输出最大边（宽或高）像素数，取值范围 64～4096，默认 1280（为约束模型输入尺寸而设），保持宽高比且不放大；
• 返回 Base64 编码的图像数据及实际宽高，供视觉模型直接解读。

同文件中还定义了export_svg（返回 SVG 字符串）与export_pdf（返回 Base64 的矢量 PDF），它们均不修改文档（mutation: 'none'）。

隐私与成本

• 请求直达提供商：你发送的每一条消息（包括画布上下文与附件）都会发送到你在设置中配置的提供商。发送敏感文档前，请先阅读该提供商的服务条款、数据政策与定价。
• OpenPencil 不包含模型积分：项目本身不提供任何内置额度或计费，所有 token 消耗均发生在你的提供商账号上。
• 凭据安全存储：在浏览器构建中，凭据默认以加密的 IndexedDB 持久化保存（设置中也可选择"仅会话存储"——密钥只保留在内存中，关闭标签页即清除）；桌面构建则使用操作系统凭据存储（详见 BYOK 提供商与模型兼容性 的"安全说明"一节）。由于同源下的脚本仍可能使用已保存的凭据，建议在提供商侧尽量使用受限作用域、带消费上限（spend cap）的密钥。

实战提示与示例提示词

使用技巧

• 先选中节点再提问——助手知道当前选区是什么，回答会更精准；
• 明确说出颜色、尺寸与位置，以获得精确结果；
• 一条消息可以同时修改多个节点；
• 不满意就撤销（undo）——AI 改动完整支持撤销；
• 每次工具执行后所有布局自动重算，无需手动刷新。

示例提示词

• "Create a card with a title, description, and a blue button"（创建一个含标题、描述和蓝色按钮的卡片）
• "Make all buttons on this page use the same border radius"（让本页所有按钮使用相同的圆角）
• "What fonts are used in this file?"（这个文件里用了哪些字体？）
• "Change the background of the selected frame to a gradient from blue to purple"（把选中 frame 的背景改为蓝到紫渐变）
• "Export the selected frame as SVG"（把选中 frame 导出为 SVG）
• "Find all text nodes with font size less than 12"（找出所有字号小于 12 的文本节点）
• "Describe the selected component — what role does it look like?"（描述选中的组件——它看起来是什么角色？）
• "Show me the JSX for this frame"（显示这个 frame 的 JSX）

小结

OpenPencil 的 AI 聊天助手以"无后端、密钥直连提供商"为架构核心：模型 Profile + 连接的复用设计让多角色（设计/评审/快速/视觉）编排变得简单，ACP 代理与远程 MCP 为其接入外部智能体与工具生态，而 90+ 工具的代理化封装（含export_image视觉验证）让它真正能"边说边画、画完自检"。接入任何新提供商前，记得对照仓库内的 BYOK 兼容性实测文档 验证 CORS 与流式工具调用质量；隐私方面，始终以"请求直达你配置的提供商、项目不含模型积分"为前提做好成本与数据风险评估。

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