AI 助手 plugin-view-ai

约 1878 字大约 6 分钟

...

2026-09-28

插件说明

在设计器中挂载可拖拽的 AI 面板（DragBox）+ 悬浮球，通过自然语言与 AI 交互，生成模板 JSON / 打印数据并一键应用到设计器。

核心能力：

流式响应（SSE 打字机效果）与思考过程展示（DeepSeek R1 / Claude thinking 等推理模型，可折叠/展开）
三种连接模式（可同时配置，运行时在设置弹窗切换）：provider 直连 / proxy 轻量代理（服务端持 Key，生产推荐）/ customService 自定义协议
AI 工具调用：AI 通过 ```tool 代码块调用内置/自定义工具（读模板 JSON、打印数据、打开预览等），结果自动回传续跑，支持多轮
一键应用：模板 + 打印数据应用前弹确认框（showModal / showToast），可用 onApply 拦截
自定义提示词系统（{{templateJson}} 等变量，localStorage 持久化）、快捷指令、多轮对话上下文、多会话管理
图片输入：剪贴板粘贴（Ctrl/Cmd + V）/ 上传 / 拖拽，自动压缩后 base64 发送给 Vision 模型
消息操作：复制、重试、编辑重发、删除、自定义 action 按钮
拦截器 beforeSend / afterReceive、上下文注入 contextCollectors、请求适配器 requestAdapter

npm install @sv-print/plugin-view-ai

注意

插件包含 UI 组件，必须引入样式文件：import '@sv-print/plugin-view-ai/dist/style.css';

示例代码

proxy 轻量代理模式（推荐，API Key 留在服务端）：

import '@sv-print/plugin-view-ai/dist/style.css'; // 必须引入样式文件
import pluginViewAi from '@sv-print/plugin-view-ai';

await hiprint.register({
  plugins: [
    pluginViewAi({
      proxy: {
        proxyUrl: '/api/ai/proxy', // 代理地址 // 代理端转发前必须剥离 _contextPrompt/_targetBaseUrl 私有字段
        targetBaseUrl: 'https://api.openai.com/v1',
        model: 'gpt-4o', // 默认模型
        modelsUrl: 'https://my-server.com/api/ai/models', // 动态拉取模型列表(可选)
        injectSystemPrompt: true, // 服务端 prepend system message
      },
      showPromptManager: true,
      enableTools: true, // 启用工具调用 (默认 true)
      maxToolRounds: 3, // 工具自动续跑最大轮数
      onApply: ({ templateJson, printData }) => {
        // 返回 false 可拦截一键应用
      },
      dragBoxStyle: 'right:10px;top:140px;width:340px;height:calc(100% - 200px);',
      defaultShow: false,
    }),
  ],
});

provider 直连模式（个人开发 / 内网）：

pluginViewAi({
  // 需注册到 hiprint.register 的 plugins 中
  provider: {
    provider: 'openai',
    baseUrl: 'https://api.openai.com/v1',
    apiKey: 'sk-xxx', // 前端持 Key 直连，仅建议开发/内网环境，生产用 proxy
    model: 'gpt-4o',
  },
  systemPrompt: '你是 sv-print 模板设计专家，根据用户描述生成模板 JSON...',
});

customService 自定义协议（非 OpenAI 兼容后端，不支持流式）：

pluginViewAi({
  customService: {
    url: 'https://my-server.com/api/ai/generate',
    method: 'POST',
    buildRequest: (ctx) => ({
      prompt: ctx.userInput,
      template: ctx.templateJson,
      images: ctx.images?.map((i) => i.url),
    }),
    parseResponse: (res) => res.result.text,
  },
});

高级用法

三种连接模式对比

	provider	proxy	customService
API Key	前端放入 `Authorization`	服务端注入	服务端
系统提示词	前端构造	前端构造（默认）或服务端注入（`injectSystemPrompt`）	服务端
请求格式	OpenAI 标准	OpenAI 标准（代理透传）	完全自定义
流式支持	支持	支持	不自动支持
模型切换	面板内切换供应商/模型	配置 `models`/`modelsUrl` 后面板内切换（Key 仍在服务端）	不自动支持
首次使用确认	`firstUseConfirm` 弹窗确认	同左（确认状态各模式独立）	同左
适用场景	个人开发 / 内网	生产环境防泄露	非 OpenAI 兼容后端

常用配置参数

参数	类型	默认	说明
`provider` / `proxy` / `customService`	见 README 类型定义	-	三种连接配置，可同时配置后在设置弹窗切换
`defaultConnectionMode`	`'provider' \| 'proxy' \| 'customService'`	按优先级 customService > proxy > provider	初始连接模式
`enableTools`	`boolean`	`true`	启用工具调用，系统提示词注入工具说明
`tools`	`AITool[]`	-	自定义工具（与内置工具合并）
`maxToolRounds`	`number`	`3`	工具自动续跑最大轮数（防死循环）
`enableStream`	`boolean`	`true`	SSE 流式响应（偏好初始值）
`enableImageInput`	`boolean`	`true`	允许粘贴/上传图片（偏好初始值）
`maxHistoryMessages`	`number`	`6`	附带最近 N 条历史消息
`enableSessions` / `maxSessions`	`boolean` / `number`	`true` / `20`	会话切换栏 / 会话数上限
`systemPrompt`	`string`	内置	覆盖内置系统提示词
`customPrompts` / `promptVariables` / `showPromptManager`	-	-	自定义提示词 / 变量 / 提示词管理入口
`quickCommands` / `showQuickCommands`	-	- / `true`	快捷指令（与内置指令合并）
`beforeSend` / `afterReceive`	hook（可数组）	-	请求 / 响应拦截（可修改，`beforeSend` 返回 `false` 取消）
`contextCollectors`	`ContextCollector[]`	-	自动采集上下文（选中元素等）注入请求
`messageActions`	`MessageAction[]`	-	消息自定义操作按钮
`parseAIContent` / `onApply`	hook	-	自定义内容解析 / 拦截一键应用（返回 `false` 拦截）
`requestAdapter`	`(config) => Promise<Response>`	-	覆盖默认 fetch（三模式均生效；流式要求 `body.getReader()` 可用）
`emptyHint` / `dragBoxStyle` / `defaultShow` / `icon`	-	-	面板 UI
`bubble`	`object`	`defaultShow: true`	悬浮球：`imageUrl` / `html` / `size` / `position` / `defaultShow`
`firstUseConfirm`（各连接模式内）	`boolean`	-	发送消息前弹窗确认，确认后按模式独立缓存

运行时 API（designerUtils.ai）

方法	说明
`send(text, images?)`	发送文本 / 文本+图片，返回结果
`apply(result)`	一键应用模板与打印数据（弹确认框）
`focusInput()`	聚焦输入框
`getTools()` / `registerTool(tool)`	获取 / 运行时动态注册工具
`getPrompts()` / `addPrompt()` / `updatePrompt(id, patch)` / `removePrompt(id)`	提示词管理
`getSessions()` / `createSession(title?)` / `switchSession(id)` / `removeSession(id)`	会话管理
`show()` / `hide()` / `toggle()`	面板显隐

工具协议与内置工具

AI 在回复中输出 ```tool {"name":"...", "args":{}} 代码块（非 function calling，任何模型可用），插件解析执行后把结果回传自动续跑（受 maxToolRounds 限制）。

工具名	功能
`get_template_json`	获取当前模板 JSON，大模板按 panel 分批返回（参数 `{ startIndex? }`）
`get_print_data`	获取当前测试打印数据（JSON）
`list_designer_apis`	列出 designerUtils 可用方法（参数 `{ path? }` 可深入子对象）
`list_hiprint_apis`	列出 hiprint 全局对象可用 API（参数 `{ path? }`）
`open_preview` / `close_preview`	打开 / 关闭当前模板打印预览弹窗
`browser_print`	浏览器直接打印当前模板
`client_print`	sv-print 客户端直连静默打印当前模板
`open_settings`	打开设计器设置弹窗
`get_property_reference`	查询元素属性取值/函数签名参考文档（参数 `{ query?, ids? }`）

自定义工具：

pluginViewAi({
  tools: [
    {
      name: 'query_order',
      description: '根据订单号查询订单信息, 参数 { orderId: string }',
      handler: async (args) => {
        const res = await fetch(`/api/order/${args.orderId}`);
        return res.json(); // 返回值(或 Promise)作为工具结果回传给 AI
      },
    },
  ],
});

提示词变量

变量	说明
`{{userInput}}`	用户输入
`{{templateJson}}`	当前模板 JSON 字符串
`{{printData}}`	当前打印数据 JSON 字符串

proxy 服务端要点

前端请求体携带插件私有字段 _contextPrompt（动态上下文）与 _targetBaseUrl（转发目标），代理端转发前必须剥离
injectSystemPrompt: true 时为分层提示词：核心提示词（角色人设 + JSON 结构规范等）配置在服务端、绝不下发前端；前端 _contextPrompt（环境信息 / 用户自定义提示词 / 工具说明）拼接后 prepend 为 system message
SSE 流式响应不 buffer，逐块透传；可在此层加用户鉴权 / 限流 / 审计

快捷键

快捷键	功能
`Ctrl/Cmd + Enter`	发送消息
`Ctrl/Cmd + V`	粘贴图片
`Ctrl/Cmd + I`	唤出 AI 面板

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)