OpenPencil AI 聊天助手实战指南：模型配置、BYOK 直连与 ACP/MCP 扩展

前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载导读OpenPencil 内置的 AI 聊天助手AI Chat是一个拥有90 设计工具的原生智能体Agent你只需用自然语言描述意图它就能创建图形、调整样式、管理布局、操作组件甚至分析整个文档。本文以官方文档 packages/docs/es/programmable/ai-chat.md 为核心骨架结合仓库源码系统讲解从模型 Profile 配置、多角色分配到 BYOKBring Your Own Key提供商直连、ACP 代理与远程 MCP 接入、工具目录与隐私成本的完整实战链路。读完本文你将能够独立完成 AI 助手的模型接入、角色编排与工具权限管理并理解其无后端、浏览器直连提供商的架构原理。快速上手按 ⌘J 打开内建 AI 助手在 OpenPencil 编辑器中按⌘JmacOS或CtrlJWindows/Linux即可唤起 AI 聊天面板。输入你想要的任意描述后助手可以创建形状frame、矩形、椭圆、文本、组件、页面修改样式填充、描边、效果、透明度、圆角、混合模式配置布局自动布局、网格、对齐、间距、尺寸处理组件创建组件、实例、组件集管理覆盖 Override分析当前文档读取节点、字体、选区检测设计问题每次调用都作用于当前激活的编辑器并在适用时进入撤销Undo历史——对 AI 改动不满意直接按编辑器里的撤销即可回退AI 产生的变更与手动编辑一样支持完整撤销。每执行一次工具后布局都会自动重算。配置模型从连接、Profile 到角色分配四步完成首个模型接入打开 AI 聊天面板⌘J点击面板上的设置图标添加一个模型 Profile配置其连接提供商与端点、模型 ID、凭据与能力保存 Profile并将其分配给Design agent设计代理源码视角连接与 Profile 的数据结构从 src/app/ai/models/types.ts 可以看到模型体系被拆成两层连接AIModelConnection一条连接代表一个可复用的提供商端点包含providerID、customBaseURL自定义 Base URL、customAPITypecompletions或responses两种 API 契约以及credentialProfileId凭据引用。多个模型 Profile 共享同一条连接时会复用同一条已安全存储的凭据无需重复填写密钥。模型 ProfileAIModelProfile在连接之上定义的模型实例包含name、modelID/customModelID自定义模型标识、maxOutputTokens最大输出 token、可选的reasoningEffort推理强度以及capabilities能力数组。能力capabilities目前有两类定义在 types.tstools工具调用能力与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取值范围为 11000 的整数默认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/v1SDK 注入AnthropicClaude 系列如 Claude Sonnet、Opus原生 Anthropic APIOpenAIGPT 系列、o 系列推理模型原生 OpenAI APIGoogle AIGemini 系列generativelanguage.googleapis.comDeepSeekDeepSeek 系列模型原生 DeepSeek APIZ.aiGLM 系列GLM-5、GLM-4.5 家族等https://api.z.ai/api/anthropic走 Anthropic 兼容通道MiniMaxMiniMax M 系列https://api.minimax.io/v1OpenAI 兼容、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_callsdelta 中id缺失、或参数片段被错误路由导致拼接后的 JSON 非法都会让工具静默不触发或直接中断流。该文档还给出了可复现的 curl 验证脚本预检 OPTIONS 成功路径 POST 双重检查、SSE 流解析验证脚本按 index 分组、校验首条 delta 的id、拼接参数并JSON.parse以及推理模型因输出预算不足而饿死finish_reason: length却零工具调用的排查建议。接入新提供商前强烈建议先按其中的方法用 curl 验证成功路径的 CORS 头避免把提供商的问题误判为应用故障。ACP 代理与远程 MCP 连接在桌面应用中接入外部智能体OpenPencil 的桌面应用可以执行ACPAgent Client Protocol代理并将其连接到受信任的、实现了Model Context ProtocolMCP的远程服务器从而把外部工具/数据源接入设计工作流。操作路径设置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.mdAI 助手的工具目录覆盖以下类别实际提供给模型哪些工具取决于你的工具访问设置读取Query查找节点、XPath 选择器、读取属性、列出页面/字体/选区创建Createframe、形状、文本、组件、页面复杂布局可渲染 JSX修改Style / Layout填充、描边、效果、透明度、圆角、混合模式自动布局、网格、对齐、间距、尺寸结构Components创建组件、实例、组件集管理覆盖变量Variables创建/编辑变量、集合、模式绑定到填充向量Vector布尔运算、路径编辑分析Analyze配色方案、排版审计、间距一致性、簇cluster检测描述Describe语义角色识别与设计问题检测代码生成导出/生成 JSX含 Tailwind 类、get_jsx往返视图、diff_jsx结构差异图像Export / StockPNG/SVG 导出、基于视觉的验证export_image、素材图片源码佐证默认工具集与可配置开关从 src/app/ai/tools/catalog.ts 可以看到工具集的构成方式默认工具集defaultNamesCORE_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默认 PNGscale导出倍率取值范围 0.14默认 1maxEdge输出最大边宽或高像素数取值范围 644096默认 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 导出为 SVGFind 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 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil AI Chat 实战解析用 BYOK 模型驱动 90 设计工具的设计智能体OpenPencil AI Chat 实战解析用 BYOK 模型驱动 90 设计工具的设计智能体 OpenPencil 内置的 AI Chat 是一个“自带前端桌面应用AI 应用MCP 服务Mihon安卓漫画阅读器完整安装指南免费开源漫画应用终极教程Mihon安卓漫画阅读器完整安装指南免费开源漫画应用终极教程 Mihon是一款功能强大的免费开源安卓漫画阅读器专为漫画爱好者设计支持本地内容阅读、多种阅读移动开发Ghost Downloader 3 上手指南快速跑通下载器Ghost Downloader 3 上手指南快速跑通下载器 Ghost Downloader 3 是一个多协议下载工具直链、磁力、FTP、M3U8 到 B桌面应用网络上一篇免费解锁 WeMod 高级功能开源增强工具 Wand-Enhancer 怎么用零基础实战指南下一篇QQ机器人搭建教程零基础用QQBot框架给群聊配置自动回复与定时提醒创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考