Skip to content

plugin.json ​

plugin.json 放在插件目录的根上,描述插件是谁、从哪里进入、需要什么权限。

严格校验

lingtools 加载插件时严格检查 plugin.json:出现不认识的字段、字段值不合法、引用的文件不存在,插件都不会加载。如果插件装上后搜不到,先检查这个文件。类型 PluginManifest(来自 @lingtools/plugin-types)能让编辑器提前发现大部分错误。

完整示例 ​

json
{
  "name": "my-notes",
  "title": "便签",
  "version": "1.2.0",
  "description": "随手记几条便签",
  "author": "张三",
  "main": "dist/index.html",
  "logo": "logo.png",
  "minAppVersion": "0.9.0",
  "features": [
    {
      "code": "list",
      "explain": "便签",
      "cmds": ["便签", "notes"]
    },
    {
      "code": "create",
      "explain": "新建便签",
      "icon": "icons/add.png",
      "cmds": [
        "新建便签",
        { "type": "over", "label": "存为便签", "minLength": 1, "maxLength": 2000 }
      ]
    }
  ],
  "view": { "appStyle": true },
  "pluginSetting": { "runInBackground": false },
  "permissions": ["clipboard.write"],
  "development": { "main": "http://127.0.0.1:5173/" }
}

基本信息 ​

字段必填说明
name是插件标识。小写字母、数字、-,1–59 个字符,首尾不能是 -,不能有连续的 --。发布到市场后不能再改
title是显示名称,出现在搜索结果和插件顶栏
version是版本号,semver 格式,如 1.2.0、2.0.0-beta.1
description否一句话简介,最多 200 个字符。安装确认页显示它
author否作者,最多 64 个字符
main是插件页面入口,插件目录内的相对路径(不以 / 开头,不含 ..),文件必须存在
logo否图标,插件目录内的相对路径。也是插件市场里显示的图标
minAppVersion否需要的最低 lingtools 版本,如 0.9.0。版本更低的 lingtools 不加载这个插件

features:入口 ​

入口是插件在搜索结果里出现的那一行。至少一个;整个插件至少要有一条功能指令(字符串)。

字段必填说明
code是入口标识,插件内唯一。用户从这个入口进来时,onPluginEnter 收到它
explain是显示名称,也参与搜索匹配
cmds是指令,至少一条,见下文
platform否可用的平台:"darwin"(macOS)、"win32"(Windows)、"linux",或它们的数组。省略为全部平台
icon否这一行的图标,插件目录内的相对路径;省略时用插件的 logo
mainHide否为 true 时,进入插件的同时隐藏搜索框、把焦点还给之前的应用。适合「选中后直接粘贴」这类不需要界面的入口

功能指令 ​

字符串就是功能指令:用户在搜索框里按关键字匹配,支持原文、全拼和拼音首字母(「便签」可以用 bianqian、bq 搜到)。1–80 个字符,不能只有空白,不能含 \ / : * ? " < > | 和控制字符。

匹配指令 ​

对象是匹配指令:按用户输入的内容匹配,命中时出现在搜索结果的「匹配指令」分组里。label 是这条指令在结果里显示的名字。

type什么时候命中其他字段
regex搜索框里的文字匹配正则match(正则,必填)、minLength、maxLength
over搜索框里的任意文字exclude(匹配它时不命中)、minLength、maxLength
img往搜索框粘贴了图片无
files往搜索框粘贴或拖入了文件 / 文件夹fileType("file" / "directory")、extensions(如 ["png","jpg"])或 match(按文件名的正则),二选一;minLength、maxLength(文件个数)
window唤起搜索框前,最前面的窗口符合规则(仅 macOS、Windows;只在搜索框为空时参与)match.app(应用名数组,如 ["Safari.app", "chrome.exe"])、match.title(窗口标题正则)、match.className(窗口类名,仅 Windows)

文字长度的单位是字符;maxLength 省略时为 10000。

正则的写法:字符串 "/正则/标志",标志只能用 i、m、s、u(不能用 g、y)。注意 JSON 里反斜杠要写两次:

json
{ "type": "regex", "label": "格式化 JSON", "match": "/^\\s*[\\[{]/" }

匹配指令进入插件时,onPluginEnter 收到的 type 和 payload:

指令typepayload
功能指令"text"命中的那条指令文字
regex / over"regex" / "over"搜索框里的原样文字
img"img"图片的 PNG Data URL(data:image/png;base64,…)
files"files"文件数组:{ path, name, isFile, isDirectory }[]
window"window"窗口信息:{ app, title, appPath, pid, x, y, width, height, id }

除了写在 plugin.json 里,插件也可以在运行时用 setFeature 添加动态入口(比如每个书签一个入口)。

view:显示选项 ​

字段说明
appStyle为 true 时页面背景透明,透出 lingtools 的卡片底色与毛玻璃,看起来和 lingtools 融为一体;默认 false,插件自己画不透明背景。用 @lingtools/ui 的主题时建议打开

pluginSetting:运行方式 ​

字段说明
runInBackground退出插件时是否退到后台、保留页面(默认 false:退出即销毁)。这只是默认值,用户可以在插件菜单里改。见 插件运行模型
multipleInstance是否允许同时运行多个实例(默认 false)。为 true 时,主窗口里仍只有一个,其余实例各在自己的分离窗口中。声明它时请同时写 minAppVersion

permissions:权限 ​

插件要用的敏感能力,必须在这里声明,否则调用以 forbidden 失败。可选值:

node、fs.read、fs、clipboard、clipboard.write、screen、shell、input、foreground、browser、server、ffmpeg、spawn、network、ai

每个权限管哪些 API、用户会看到什么,见 权限。出现不认识的权限名时插件不加载(通常是插件需要更高版本的 lingtools)。

preload:Node 后端 ​

字段说明
preloadNode 后端脚本,插件目录内的相对路径,扩展名 .cjs、.mjs 或 .js。写了它就必须声明 node 权限。见 Node 后端

development:开发选项 ​

只对开发者工具安装的开发版生效,打包发布后忽略。

字段说明
main开发服务地址,插件页面从这里加载、支持热更新。必须是本机地址(127.0.0.1、localhost 或 [::1]),以 / 结尾,如 http://127.0.0.1:5173/

extends:扩展点 ​

字段说明
searchCards搜索卡片:在搜索结果上方显示的卡片。见 搜索卡片
ai提供给 AI 客户端的工具。见 给 AI 提供工具