Skip to content

权限 ​

插件要用敏感能力,必须在 plugin.json 的 permissions 里声明。用户能在插件市场里看到插件申请了哪些权限,并逐项关闭。

规则 ​

  1. 没声明就不能用:调用以错误码 forbidden 失败。所有插件都一样,包括官方插件。
  2. 用户可以关闭:在插件市场的插件详情页「权限」标签里,用户可以关掉任意权限(node 除外)。关掉后调用同样以 forbidden 失败,插件会被停止,下次打开生效。
  3. 只申请需要的:权限越多,用户越犹豫,审核也越严。
json
{
  "permissions": ["clipboard.write", "fs.read"]
}

处理被拒绝的情况:

ts
import { isApiError } from '@lingtools/plugin-sdk'

try {
  await window.ling.copyText(text)
} catch (error) {
  if (isApiError(error) && error.code === 'forbidden') {
    ElMessage.warning('没有剪贴板权限,请在插件市场里打开')
  }
}

权限一览 ​

权限允许做什么涉及的 API
clipboard.write写剪贴板copyText、copyImage、copyFile、clipboard.writeHtml、hideMainWindowPaste*
clipboard读写剪贴板(包含 clipboard.write)上面全部,加 clipboard.readText、getCopiedFiles
fs.read读插件目录以外的文件fs.* 的读操作、getFileIcon 传路径、startDrag、shellShowItemInFolder、browser 的 file / drop
fs读写插件目录以外的文件(包含 fs.read)上面全部,加 fs.* 的写操作、shellTrashItem、browser 的 savePath / pdf
screen截图、取色、读光标位置captureScreen、screenColorPick、getCursorScreenPoint
shell用系统默认方式打开文件(可执行文件会被运行)shellOpenPath
input模拟键盘鼠标操作其他应用simulate*、hideMainWindowTypeString
foreground读取其他应用的状态readCurrentFolderPath、readCurrentBrowserUrl
browser可编程浏览器ling.browser、getIdleBrowsers、setBrowserProxy、clearBrowserCache
server在本机开局域网服务,让同一网络的设备访问ling.server
ffmpeg调用 FFmpeg 处理音视频runFFmpeg、ffmpeg.probe
ai调用用户配置的 AI 模型和内置本地模型ai、allAiModels、localAi.*
spawn运行本机程序ling.spawn
node运行 Node 后端(preload)plugin.json 的 preload
network插件页面访问外网fetch、XHR、WebSocket、外部图片 / 脚本 / 样式 / 字体

高风险权限:node、spawn、ffmpeg、shell 实际上能以用户身份做任何事。用户和审核都会特别留意,非必要不要申请。node 用户不能单独关闭。

不需要权限的 ​

db、dbStorage、插件自己的数据目录和临时目录(fs.*)、系统通知、文件对话框、redirect、shellOpenExternal、shellBeep、getPath、getUser、getForegroundApp、显示器信息与坐标换算,以及作用于插件自身的方法(子输入框、outPlugin、setFeature 等)。

文件权限按路径判断 ​

fs.read / fs 只管插件目录以外的文件。下面这些路径不需要声明任何权限就能读写:

  • 插件自己的数据目录(getPluginLocalDataPath())和临时目录(getPluginTempPath());
  • 用户在文件对话框(showOpenDialog / showSaveDialog)里选给插件的文件;
  • 用户粘贴或拖进搜索框、随入口交给插件的文件(files 匹配指令);
  • 用户拖进插件页面的文件(经 ling.getPathForFile(file) 取得路径后)。

这些授权在插件这次运行期间有效。所以「让用户选一个文件再处理」的插件,通常不需要 fs 权限。

路径按跟随符号链接后的真实路径判断。

网络 ​

network 默认开启,不用声明,用户可以在插件市场里关闭:

  • 开启时:插件页面可以访问任何 http / https 地址,并且不受跨域限制(可以直接 fetch 任何网站并读到内容);
  • 关闭时:页面只能加载插件自己的文件和 data: / blob: 资源;
  • 无论开关:不能用 iframe 嵌入外部网页,不能读 file: 地址。

用户关掉网络后插件应该给出提示,而不是静默失败。

用户看到什么 ​

  • 插件市场详情页的「权限」标签列出插件申请的每项权限和说明;node 标为「最高风险 · 可绕过其他权限」,spawn 标为「高风险 · 可运行任意程序」。
  • 安装后可以逐项开关;任何改动都会停止正在运行的插件,重新打开后生效。

用户在插件市场里看到的权限页