Skip to content

插件开发总览 ​

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 拿到这个 codefeatures[].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、打包、发布。

推荐阅读顺序 ​

  1. 第一个插件:十分钟做出一个能在搜索框里打开的插件。
  2. 插件运行模型:插件什么时候创建、什么时候销毁、在哪个窗口里。
  3. plugin.json 和 插件 API:需要时查阅。
  4. 按需求读指南:子输入框、数据存储、Node 后端、搜索卡片、给 AI 提供工具。
  5. 权限 和 打包与发布:上架前必读。

从 uTools 迁移过来?先看 从 uTools 迁移。