插件开发总览
lingtools 的插件就是一个网页加一份 plugin.json。用你熟悉的前端技术写界面,通过 window.ling 调用系统能力。
插件能做什么
- 在搜索框里出现:用户输入关键字(如「二维码」)、粘贴一段文字、拖入几个文件,或者在某个应用前唤起 lingtools 时,你的插件出现在结果里。
- 打开一个界面:插件页面显示在搜索框下方,也可以分离成独立窗口。
- 调用系统能力:读写剪贴板、读写文件、截图、调用 AI、处理图片和音视频、开局域网服务、运行本地程序等,全部通过
window.ling。 - 直接在搜索结果上方给答案:用「搜索卡片」,不用打开插件就能显示结果(比如输入算式直接出得数)。
- 跑 Node.js 代码:需要 npm 包或原生模块时,写一个 Node 后端(preload)。
- 给 AI 提供工具:把插件的功能注册成工具,供 Claude、Cursor 等 AI 客户端调用。
核心概念
先认识这几个词,后面的文档都会用到。
| 概念 | 是什么 | 在哪里定义 |
|---|---|---|
| 插件 | 一个目录:plugin.json + 页面文件 + 图标。用 name 唯一标识 | plugin.json |
| 入口(feature) | 插件的一个功能,在搜索结果里占一行。一个插件可以有多个入口 | plugin.json 的 features |
| 入口标识(code) | 入口的 ID。用户从哪个入口进来,插件通过 onPluginEnter 拿到这个 code | features[].code |
| 指令(cmd) | 触发入口的方式。功能指令是关键字(字符串);匹配指令按输入内容匹配(正则、任意文字、图片、文件、当前窗口) | features[].cmds |
| 插件页面 | 插件的界面,一个普通网页,window.ling 已经注入好 | plugin.json 的 main |
| 子输入框 | 插件打开后,搜索框变成插件自己的输入框,插件可以监听里面的文字 | ling.setSubInput() |
| Node 后端 | 和插件页面配套的 Node.js 脚本,在独立进程里运行 | plugin.json 的 preload |
| 搜索卡片 | 显示在搜索结果上方的小卡片,不用打开插件 | plugin.json 的 extends.searchCards |
| 权限 | 插件要用到敏感能力(读文件、剪贴板等)时必须先声明,用户可以随时关闭 | plugin.json 的 permissions |
它们之间的关系:
text
plugin.json
├─ features(入口)──┬─ cmds(指令)── 用户在搜索框命中 ──┐
│ └─ code ─────────────────────────────┤
├─ main(插件页面)◀─────── onPluginEnter({ code, type, payload })
├─ preload(Node 后端)◀── 页面直接 await 调用它挂出的函数
├─ extends.searchCards(搜索卡片)── 搜索时在结果上方显示
└─ permissions(权限)── 决定页面、后端、卡片能调用哪些 API开发方式
插件页面可以用任何能产出静态网页的技术写:Vue、React、Svelte 或纯 HTML 都行。官方推荐 Vite + Vue 3 + Element Plus,并提供 @lingtools/ui 让界面和 lingtools 本身保持一致。
开发时,插件页面从你本机的开发服务(如 Vite 的 http://127.0.0.1:5173/)加载,改代码即时生效;完成后打成一个 .lpxs 文件,可以发给别人本地安装,也可以发布到插件市场。
开始之前
你需要:
- 一台 macOS 13 及以上或 Windows 10 及以上的电脑,已安装 lingtools;
- Node.js 24 及以上、pnpm(也可以用 npm,本文档统一写 pnpm);
- 在 lingtools 的插件市场里安装「开发者工具」插件:用它把你的插件目录装进 lingtools、打包、发布。
推荐阅读顺序
- 第一个插件:十分钟做出一个能在搜索框里打开的插件。
- 插件运行模型:插件什么时候创建、什么时候销毁、在哪个窗口里。
- plugin.json 和 插件 API:需要时查阅。
- 按需求读指南:子输入框、数据存储、Node 后端、搜索卡片、给 AI 提供工具。
- 权限 和 打包与发布:上架前必读。
从 uTools 迁移过来?先看 从 uTools 迁移。