plugin.json
plugin.json 放在插件目录的根上,描述插件是谁、从哪里进入、需要什么权限。
严格校验
lingtools 加载插件时严格检查 plugin.json:出现不认识的字段、字段值不合法、引用的文件不存在,插件都不会加载。如果插件装上后搜不到,先检查这个文件。类型 PluginManifest(来自 @lingtools/plugin-types)能让编辑器提前发现大部分错误。
完整示例
{
"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 里反斜杠要写两次:
{ "type": "regex", "label": "格式化 JSON", "match": "/^\\s*[\\[{]/" }匹配指令进入插件时,onPluginEnter 收到的 type 和 payload:
| 指令 | type | payload |
|---|---|---|
| 功能指令 | "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 后端
| 字段 | 说明 |
|---|---|
preload | Node 后端脚本,插件目录内的相对路径,扩展名 .cjs、.mjs 或 .js。写了它就必须声明 node 权限。见 Node 后端 |
development:开发选项
只对开发者工具安装的开发版生效,打包发布后忽略。
| 字段 | 说明 |
|---|---|
main | 开发服务地址,插件页面从这里加载、支持热更新。必须是本机地址(127.0.0.1、localhost 或 [::1]),以 / 结尾,如 http://127.0.0.1:5173/ |
extends:扩展点
| 字段 | 说明 |
|---|---|
searchCards | 搜索卡片:在搜索结果上方显示的卡片。见 搜索卡片 |
ai | 提供给 AI 客户端的工具。见 给 AI 提供工具 |