OpenPencil AI 聊天助手实战指南：模型配置、BYOK 直连与 ACP/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：

角色	用途	可选模型的约束
design	设计代理（主工作模型）	必须支持 tools 能力
review	设计评审	非 Agent 类 Profile；可选"与设计相同"
fast	快速任务	非 Agent 类 Profile；可选"与设计相同"
vision	图像输入/视觉参考	必须支持 vision 能力；可选"与设计相同"（仅当设计模型也支持 vision 时）

分配逻辑实现在 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 可以看到实际注册的适配器：

提供商	说明	源码中的默认端点
OpenRouter	聚合 Claude、GPT、Gemini、DeepSeek、Qwen 等众多模型	openrouter.ai/api/v1（SDK 注入）
Anthropic	Claude 系列（如 Claude Sonnet、Opus）	原生 Anthropic API
OpenAI	GPT 系列、o 系列推理模型	原生 OpenAI API
Google AI	Gemini 系列	generativelanguage.googleapis.com
DeepSeek	DeepSeek 系列模型	原生 DeepSeek API
Z.ai	GLM 系列（GLM-5、GLM-4.5 家族等）	https://api.z.ai/api/anthropic（走 Anthropic 兼容通道）
MiniMax	MiniMax M 系列	https://api.minimax.io/v1（OpenAI 兼容、chat 模式）
OpenAI 兼容	任意符合 OpenAI API 格式的端点（含本地/自托管部署）	自定义 Base URL；支持 Completions 与 Responses API 切换
Anthropic 兼容	任意符合 Anthropic API 格式的端点（含本地/自托管部署）	自定义 Base URL

每个提供商的模型列表与能力各不相同，以各服务商官方为准；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_calls delta 中 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 与流式工具调用质量；隐私方面，始终以"请求直达你配置的提供商、项目不含模型积分"为前提做好成本与数据风险评估。