uTools 开发者 API 参考

概述

uTools 是基于 Electron 的跨平台效率工具平台。插件应用通过 plugin.json 定义入口、通过 preload.js 调用 Node.js/Electron 原生能力、通过 utools 全局 API 与平台交互。

插件目录结构

1
2
3
4
5
6
7

/{plugin}
|-- plugin.json    # 核心配置（必须）
|-- preload.js     # 预加载脚本（可选，需要 Node.js 能力时使用）
|-- index.html     # 前端页面入口
|-- index.js
|-- index.css
|-- logo.png       # 插件图标（必须）

⚠️ 打包注意事项
uTools 只识别 html + css + javascript。如果用框架（Vue/React/Vite），先编译到 dist 再打包 dist 文件夹。

plugin.json 核心字段

基础字段

features 功能定义

features 是数组，每个元素定义一个功能及其指令：

• code：功能编码（唯一，进入插件时分发）
• explain：功能描述
• cmds：指令集合（字符串为功能指令，对象为匹配指令）

匹配指令类型

tools 字段（AI Agent 专用）

向 AI Agent 暴露可调用工具：

1
2
3
4
5
6

"tools": {
  "say_hi": {
    "description": "向用户打招呼",
    "inputSchema": { "type": "object", "additionalProperties": false }
  }
}

每个工具需在运行时代码中通过 utools.registerTool 注册。

preload 预加载脚本

preload.js 遵循 CommonJS 规范，可以调用 Node.js API 和 Electron 渲染进程 API。

示例：

1
2
3
4

const fs = require("node:fs");
window.services = {
  readFile: (path) => fs.readFileSync(path, "utf-8")
};

规范要求：代码不能打包/压缩/混淆，引入的第三方模块源码必须清晰可读。

使用 npm 第三方模块：在 preload.js 同级目录创建 package.json（type: “commonjs”），执行 npm install。

事件 API

utools.onPluginEnter(callback)

进入插件时触发，参数包含 code、type、payload、from。

• type："text" / "img" / "file" / "regex" / "over" / "window"
• from："main"（主面板）/ "panel"（超级面板）/ "hotkey"（快捷键）/ "reirect"（重定向）

utools.onPluginOut(callback)

退出插件时触发。isKill 为 true 表示进程结束。

utools.onMainPush(callback, onSelect)

推送内容到搜索框，需在 plugin.json 中设置 feature.mainPush: true。

utools.onPluginDetach(callback)

插件分离为独立窗口时触发。

utools.onDbPull(callback)

其他设备数据同步到本设备时触发。

窗口 API

主窗口控制

• utools.hideMainWindow(isRestorePreWindow)：隐藏主窗口
• utools.showMainWindow()：显示主窗口
• utools.setExpendHeight(height)：设置高度
• utools.outPlugin(isKill)：退出插件

子输入框

• utools.setSubInput(onChange, placeholder, isFocus)：设置子输入框
• utools.removeSubInput()：移除子输入框
• utools.setSubInputValue(text)：设置值
• utools.subInputFocus() / utools.subInputBlur() / utools.subInputSelect()

独立窗口

utools.createBrowserWindow(url, options, callback)：创建独立窗口，返回 BrowserWindow 实例。

主窗口 ↔ 独立窗口通信：

• 主窗口 → 独立窗口：win.webContents.send('channel', data)
• 独立窗口 → 主窗口：utools.sendToParent('channel', data)
• 接收：ipcRenderer.on('channel', callback)

其他

• utools.showOpenDialog(options)：文件选择框
• utools.showSaveDialog(options)：文件保存框
• utools.redirect(label, payload)：跳转到另一个插件
• utools.findInPage(text)：页面内查找
• utools.startDrag(filePath)：拖拽文件
• utools.getWindowType()：返回 "main" / "detach" / "browser"
• utools.isDarkColors()：是否深色主题

复制 API

• utools.copyText(text)：复制文本
• utools.copyFile(filePath)：复制文件（支持路径数组）
• utools.copyImage(image)：复制图像（路径或 base64）
• utools.getCopyedFiles()：获取剪贴板中文件列表

输入 API

• utools.hideMainWindowPasteFile(filePath)：粘贴后隐藏窗口
• utools.hideMainWindowPasteImage(image)：粘贴图像后隐藏窗口
• utools.hideMainWindowPasteText(text)：粘贴文本后隐藏窗口
• utools.hideMainWindowTypeString(text)：模拟键盘输入

系统 API

屏幕 API

用户 API

• utools.getUser()：获取当前用户信息（avatar、nickname、type），未登录返回 null
• utools.fetchUserServerTemporaryToken()：获取服务端临时令牌（token + expired_at）

本地数据库 API

基于 nosql 设计，支持秒级云端同步、端到端加密存储。

基础操作

文档结构：{ _id: string, _rev?: string, ... }

附件操作

dbStorage（键值对存储）

类似 localStorage 的简化 API：setItem(key, value) / getItem(key) / removeItem(key)

dbCryptoStorage（加密键值对存储）

与 dbStorage 接口一致，数据加密存储。

同步状态

utools.db.replicateStateFromCloud()：返回 null（未开同步）/ 0（完成）/ 1（同步中）

AI Agent 工具注册

utools.registerTool(name, handler)

在 preload.js 或与 onPluginEnter 同级作用域注册，不能写在 onPluginEnter 内部。

1
2
3
4
5
6
7
8
9

utools.registerTool('say_hi', async () => 'hi')

// 带进度的长任务
utools.registerTool('video_convert', async ({ inputPath, format }, ctx) => {
  await runFFmpeg(args, (progress) => {
    ctx.sendProgress?.({ progress, total: 100, message: '转换中...' })
  })
  return { outputPath }
})

最佳实践

• 一个工具一个职责，避免”万能工具”
• 参数与 inputSchema 严格一致
• 长任务（≥5s）必须提供进度反馈
• 返回值保持结构化对象
• 错误直接 throw，由 AI Agent 感知处理

动态指令 API

• utools.getFeatures(codes?)：获取动态功能列表
• utools.setFeature(feature)：注册动态功能
• utools.removeFeature(code)：删除动态功能
• utools.redirectHotKeySetting(cmdLabel)：跳转快捷键设置
• utools.redirectAiModelsSetting()：跳转 AI 模型设置