权限系统
Such 插件权限声明与校验机制
权限系统
Such 插件采用声明式权限模型：插件在 permissions 字段中声明需要的权限，宿主在加载时检查并提示用户确认。运行时调用 API 时也会校验权限，权限不足将抛出错误。
权限清单
| 权限值 | 可调用的 API | 说明 |
|---|---|---|
local_program | execProgram, execTerminal | 调用本地可执行程序和终端命令 |
file_system | fileOp, writeMeta | 本地文件读写、复制、删除操作 |
fetch | fetch, downloadFile | 发起 HTTP 网络请求 |
app_info | getSetting | 读取 Such 应用设置 |
playlist | createPlaylist, addToPlaylist, updatePlaylistSettings, listPlaylists | 歌单 CRUD 操作 |
声明方式
在 window.source.permissions 中声明：
window.source = {
id: 'MY_PLUGIN',
name: '我的插件',
version: '1.0.0',
author: 'dev',
permissions: ['local_program', 'file_system', 'fetch']
}ℹ️ 未在
permissions中声明的 API 即使代码中调用了，宿主也会抛出权限错误拦截。
权限校验流程
插件调用 suchmusic.xxx()
→ 宿主检查 manifest.permissions 是否包含所需权限
→ 有权限：继续执行
→ 无权限：抛出错误 "插件未声明权限 xxx，无法调用 yyy()"最小权限原则
只声明插件实际需要的权限，不要声明多余的权限。这样：
- 减少用户对安全风险的担忧
- 加快用户审核通过的速度
- 提升插件的安全性评价
// ✅ 好 — 只声明实际需要的
permissions: ['fetch', 'playlist']
// ❌ 差 — 声明了不需要的权限
permissions: ['local_program', 'file_system', 'fetch', 'app_info', 'playlist']权限不足时的错误
当插件调用未授权 API 时，会抛出类似以下错误：
Error: [Such Plugin] 插件 "我的插件" 未声明权限 "file_system"，无法调用 fileOp()插件中应做好错误处理：
async safeFileOp() {
try {
const content = await suchmusic.fileOp('read', 'config.json')
return content
} catch (err) {
console.error('文件操作失败:', err.message)
window.notify('操作失败：权限不足', 'error')
}
}权限与敏感操作的区分
- 权限：声明式控制 API 是否可调用，属于粗粒度访问控制
- 敏感操作：运行时每次执行前向用户确认，属于细粒度安全确认
| 特性 | 权限 | 敏感操作 |
|---|---|---|
| 检查时机 | API 调用时 | API 执行前 |
| 用户交互 | 加载插件时一次性确认 | 每次执行时弹窗确认 |
| 可跳过 | 否 | 是（勾选"不再询问"） |
| 控制粒度 | API 级别 | 操作实例级别 |
例如 fileOp 需要 file_system 权限（声明式），同时每次调用都是敏感操作（需确认）。详见 安全模型。