AI Chat uTools 插件

AI Chat 是一个运行在 uTools 里的 AI 助手，支持对话、翻译、总结、解释和 OCR。插件使用 OpenAI 兼容的 /v1/chat/completions 接口，可以接入本地模型、云端模型或其他兼容服务。

开源地址: https://github.com/VonSdite/utools_ai_chat

• 使用 OpenAI 兼容的 /v1/chat/completions 接口，接入模型服务；
• 支持对接多模态模型，进行OCR、翻译、总结、解释、AI对话；
• AI对话支持slash命令，支持搜索历史会话，支持创建不同的助手系统提示词，支持文档处理；
• 支持选中文本朗读；

命令入口

• AI Chat：进入对话。
• AI 对话：进入对话，语义更明确。
• AI 翻译 / 翻译：处理选中文本、最近复制的文本，或多模态模型可读取的图片。
• AI 总结 / 总结：处理选中文本、最近复制的文本，或多模态模型可读取的图片。
• AI 解释 / 解释：处理选中文本、最近复制的文本，或多模态模型可读取的图片。
• AI OCR / OCR：识别最近复制或命令传入的图片文字，可同时带入最近复制的文本作为说明。

使用姿势

必须到设置页面先配置模型提供商，如果有多模态模型，在翻译、总结、解释、对话均可使用多模态识别图片。

超级面板

选中文本、图片，唤出超级面板，即可快速发起翻译、总结、解释、对话。

复制图片、复制文本，唤起超级面板，即可快速发起OCR、翻译、总结、解释、对话。

快捷命令启动

在设置 - 快捷方式 - 设置快捷键绑定 对应命令， 后续通过快捷键快速唤起对应入口。

通过快捷命令唤起时，插件只处理 uTools 命令自身传入的划词文本或图片，不再读取最近剪贴板记录。

自动处理规则

AI 翻译、AI 总结、AI 解释 在这些场景会自动发送给模型：

• 通过 uTools 划词入口进入，并且 uTools 成功传入选中文本。
• 插件处于分离窗口，当前页签标题栏剪贴板开关已开启，并且此时复制了文本。
• 插件处于分离窗口，当前页签标题栏剪贴板开关已开启，并且此时复制了图片，且当前功能绑定的是多模态模型。
• 如果没有选中文本，也没有可用剪贴板内容，只会打开对应页面，不会自动发送。

AI OCR 以图片为执行前提：

• 命令传入的是图片，或插件处于分离窗口、当前页签标题栏剪贴板开关已开启且此时复制的是图片时，会自动带入附件区并发送给 OCR。
• 插件处于分离窗口且当前页签标题栏剪贴板开关已开启时，如果剪贴板同时包含文本和图片，会同时带入文本和图片，文本可作为 OCR 说明或上下文。
• 插件处于分离窗口且当前页签标题栏剪贴板开关已开启时，如果只有文本、没有可用图片，会填入 OCR 输入框但不会自动发送。
• 如果命令传入多张图片，会尽量按附件上限带入。
• OCR 只能选择标记为多模态的模型。
• 如果没有可用图片，只会打开 OCR 页签，不会自动发送。

AI Chat 和 AI 对话 不会自动发送：

• 插件处于分离窗口，当前页签标题栏剪贴板开关已开启时，此时复制的文本会填入输入框。
• 命令传入的图片会带入附件区；插件处于分离窗口，当前页签标题栏剪贴板开关已开启时，此时复制的图片也会带入附件区。
• 用户需要自己点击发送，方便继续编辑或追加问题。
• 最多支持 3 个对话同时生成；后台对话完成后，会在对应会话前显示小蓝点，点击会话后清除。

AI 对话界面

对话页由左侧侧边栏、消息区和底部输入区组成。

• 左侧侧边栏用于管理助手和会话。顶部显示当前助手，点开后可以切换助手、创建新助手或删除助手。
• 助手编辑区可以设置助手名称和 Prompt。Prompt 会作为该助手的固定系统提示词，发送消息时自动带给模型；不同助手可以使用不同 Prompt。
• 话题列表展示当前助手下的会话。点击话题即可切换会话；新建会话会保留在当前助手下。后台会话生成完成后，会在话题前显示未读提示。
• 侧边栏可以折叠，适合只关注当前对话内容时使用。
• 每条模型回复会显示实际使用的 provider / 模型名称；支持展开思考过程、查看 token 和耗时统计。
• 底部输入区支持文本、图片和文档附件。图片需要当前对话模型开启多模态；文档会先提取文本后作为上下文发送。
• 模型选择放在发送按钮左侧。这里切换的是当前对话会话使用的模型，不影响翻译、总结、解释和 OCR 的模型选择。
• 输入框内选中文本、对话消息内选中文本，都可以点击悬浮喇叭朗读。

对话输入框支持 slash 命令：

• /clear：在当前会话中插入上下文清除标记，后续发送只会携带该标记之后的消息；再次执行可撤销最近一次清除标记。
• /new：在当前助手下新建一个会话，并切换过去。
• /model：打开模型选择列表。可以继续输入关键字过滤 provider 名称、模型名、provider id 或 model id，使用方向键选择，Enter 或 Tab 确认。

划词内容获取说明

uTools 的划词能力来自 plugin.json 里的 type: "over" 命令配置。本插件给 AI 对话、AI 翻译、AI 总结、AI 解释 配置了划词入口。图像超级面板入口使用 type: "img"，用于 AI OCR。

工作流程是：

1. 用户在其他应用里选中文本。
2. 用户唤起 uTools，并选择对应的划词命令。
3. uTools 判断选中文本长度是否符合命令配置。
4. 符合条件时，uTools 会以 over 类型进入插件，并把选中文本作为 payload 传给插件。
5. 插件收到选中文本后优先使用它，不再读取最近剪贴板图片。

普通关键词命令，例如直接输入 AI 翻译 或 AI 总结 进入，不属于 over 划词入口。它不会携带选中文本 payload；插件也不会再为普通关键词命令读取最近剪贴板记录。

长度限制：

• AI 翻译：选中文本最多 8000 字符。
• AI 对话、AI 总结、AI 解释：选中文本最多 12000 字符。

注意：插件不会主动扫描屏幕，也不会自己从其他应用抓取文字。划词文本是否可获取，取决于 uTools 能否从当前应用和系统环境拿到选中内容。

剪贴板说明

插件只关注剪贴板里的文本和图片，不处理文件列表或其他内容。标题栏里的剪贴板开关按页签分别保存，默认关闭；关闭时不会监听复制。

• 只有插件处于分离窗口，并且当前页签剪贴板开关已开启，才会启动剪贴板监听。
• 普通关键词命令进入插件时不会读取最近剪贴板记录。
• “剪贴板轮询间隔”决定剪贴板监听启用后，插件检查剪贴板变化的频率，默认 500 毫秒。
• 文本和图片是分开记录的；选中文本优先级高于剪贴板内容。
• 图片自动带入会尽量使用命令或剪贴板能提供的图片，最终数量受附件上限限制。

模型和 Provider

在设置里可以添加多个 provider。Provider 名称和 URL 必填，API Key 可选。API 地址需要填写完整的 OpenAI 兼容聊天接口，例如：

https://api.example.com/v1/chat/completions

模型可以手动添加，也可以从 provider 拉取。图片处理和 OCR 依赖多模态能力，所以需要在模型列表里把对应模型标记为多模态。

翻译、总结、解释、OCR 和对话会分别记住上一次使用的模型。切换功能时，会回到该功能自己的模型选择。

插件代理在设置中统一配置，支持直连模式、系统代理和自定义代理。直连模式会绕过环境变量、系统代理和 uTools/Electron 代理配置；系统代理读取操作系统代理设置和系统环境变量，不使用 uTools 自己的代理配置；自定义代理支持 HTTP/HTTPS 代理地址。

附件和数据

• 附件总数最多 3 个，图片和文档共用这个限制。
• OCR 只能添加图片附件。
• 图片会按 OpenAI 兼容的 image_url 多模态消息发送。
• 文本、代码、PDF、DOC、DOCX、PPTX、XLSX、ODT、ODP、ODS 会先提取文本，再作为上下文随消息发送。
• 模型提供商、API Key、模型选择、代理和剪贴板设置会保存到数据目录下的 config.json。
• 对话记录和任务缓存会保存到数据目录下的 chat-store.json 和 task-store.json。
• 文档原文件和提取后的文本会缓存到数据目录下的 cache/attachments，会话里保存用于发送的文本快照。
• 数据目录可在设置中修改；Windows 默认是 D:\utools_ai_chat，macOS/Linux 默认是 ~/utools_ai_chat。修改数据目录时会自动迁移 config.json、会话、任务和缓存目录。

发布目录

发布前执行：

npm run release:utools

脚本会生成 dist/utools，只复制插件运行需要的页面、脚本、图标、vendor 资源，并在发布目录安装 preload 运行依赖。uTools 发布时选择 dist/utools 目录即可。