权限
插件要用敏感能力,必须在 plugin.json 的 permissions 里声明。用户能在插件市场里看到插件申请了哪些权限,并逐项关闭。
规则
- 没声明就不能用:调用以错误码
forbidden失败。所有插件都一样,包括官方插件。 - 用户可以关闭:在插件市场的插件详情页「权限」标签里,用户可以关掉任意权限(
node除外)。关掉后调用同样以forbidden失败,插件会被停止,下次打开生效。 - 只申请需要的:权限越多,用户越犹豫,审核也越严。
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标为「高风险 · 可运行任意程序」。 - 安装后可以逐项开关;任何改动都会停止正在运行的插件,重新打开后生效。
