JS插件管理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /jsplugins | 列出所有 JS 插件 |
PUT | /jsplugins/{id} | 更新 JS 插件 |
DELETE | /jsplugins/{id} | 删除 JS 插件 |
GET | /jsplugins/{id} | 获取 JS 插件详情 |
GET | /jsplugins/{id}/check-update | 检查 JS 插件更新 |
POST | /jsplugins/{id}/disable | 禁用 JS 插件 |
POST | /jsplugins/{id}/enable | 启用 JS 插件 |
POST | /jsplugins/{id}/update | 下载并更新 JS 插件 |
POST | /jsplugins/registry/install | 从注册表安装插件 |
POST | /jsplugins/registry/refresh | 刷新插件注册表 |
POST | /jsplugins/storage/cleanup | 清理孤儿持久化存储 |
POST | /jsplugins/update-all | 批量更新所有 JS 插件 |
POST | /jsplugins/upload | 上传安装 JS 插件 |
GET | /plugins/health | 音源健康度 |
PUT | /settings/github-discovery-token | 保存 GitHub 发现 Token |
GET | /settings/github-discovery-token | 获取 GitHub 发现 Token |
PUT | /settings/plugin-registries | 保存插件订阅源列表 |
GET | /settings/plugin-registries | 获取插件订阅源列表 |
GET /jsplugins
列出所有 JS 插件
获取 JS 插件列表,形如 {"plugins": [jsplugin.JSPlugin, ...]}(响应类型是 map, 单个插件对象的完整字段见 jsplugin.JSPlugin 定义)。 其中 render_engine 是插件在自己 plugin.json 的 renderEngine 字段里声明的页面渲染引擎, 取值 "webview"(系统 WebView)或 "lynx"(Lynx 原生渲染);空串表示跟随宿主默认,客户端需自行映射为 webview。
需要认证
此接口需要 Bearer Token 认证
响应
200 - JS插件列表
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
PUT /jsplugins/{id}
更新 JS 插件
上传新的 JS 插件文件以更新现有插件
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
表单参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | JS插件文件 (.jsplugin.zip) |
响应
200 - 更新成功
类型: map[string]any
400 - 请求数据错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
multipart/form-data - 响应:
application/json
DELETE /jsplugins/{id}
删除 JS 插件
根据插件ID删除 JS 插件。可通过 keep_data 参数保留插件数据目录(文件系统存储),持久化存储(数据库)始终保留。
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keep_data | string | 否 | 是否保留插件数据目录(true/false,默认 false) |
响应
200 - 删除成功
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
GET /jsplugins/{id}
获取 JS 插件详情
根据插件ID获取 JS 插件的详细信息
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
响应
200 - JS插件信息
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
GET /jsplugins/{id}/check-update
检查 JS 插件更新
检查指定 JS 插件的远程更新
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
响应
200 - 更新信息
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/{id}/disable
禁用 JS 插件
禁用指定的 JS 插件
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
响应
200 - 禁用成功
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/{id}/enable
启用 JS 插件
启用指定的 JS 插件
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
响应
200 - 启用成功
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/{id}/update
下载并更新 JS 插件
从远程下载并更新指定的 JS 插件。设置 force=true 可跳过版本检查强制重新下载安装。
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 插件ID |
响应
200 - 更新成功
类型: map[string]any
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 插件不存在
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/registry/install
从注册表安装插件
从注册表中的 download_url 下载 ZIP 并安装插件。如果 entry_path 已存在且属于同一作者,则自动走更新路径。匿名下载支持 GitHub 加速代理;携带 Token 的下载始终绕过加速代理,避免凭据泄漏。可选传入 token 字段用于从需要认证的私有源下载;若未提供 token 但提供了 source_url,后端会自动从 plugin_registries 配置解析该源存储的 token。 若 entry_path 已被本地一个不同作者的插件占用,返回 409 且不做任何写入(不落盘、不动 static 目录、不改数据库)。前端应向用户说明会替换原插件后,带 overwrite=true 重发本请求。
需要认证
此接口需要 Bearer Token 认证
请求体
安装请求
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
download_url | string | 否 | |
github_proxy | string | 否 | |
overwrite | boolean | 否 | Overwrite 为 true 时允许覆盖掉本地已装的同 entry_path 但不同作者的插件。 |
| 默认 false:这种情况返回 409,由前端二次确认后带该字段重发。 | |||
source_url | string | 否 | SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传: |
| 当未显式提供 token 时,后端据此从 plugin_registries 配置解析该源的 token。 | |||
token | string | 否 |
响应
200 - 安装结果(更新已有插件)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
failed | integer | 否 | |
message | string | 否 | |
results | jsPluginUploadResult[] | 否 | |
success | integer | 否 | |
total | integer | 否 |
201 - 安装结果(新插件)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
failed | integer | 否 | |
message | string | 否 | |
results | jsPluginUploadResult[] | 否 | |
success | integer | 否 | |
total | integer | 否 |
400 - 请求格式错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
409 - entry_path 已被另一个作者的插件占用,需用户确认后带 overwrite=true 重试
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 下载或安装失败
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/registry/refresh
刷新插件注册表
拉取订阅源(含递归 includes),去重合并后返回分页的可用插件列表。每个插件标注是否已安装及是否有更新。默认拉取单个 registry_url,可选传入 token 字段访问需要认证的私有源(如 GitHub 私有仓库 PAT)。当 all_sources=true 时忽略 registry_url/token,改为聚合已保存的所有启用订阅源(各源用自身存储的 token)。 去重键为 entry_path + identity(identity = 规范化 author,author 为空时用 updateUrl 的 GitHub owner/repo 兜底):entry_path 相同但作者不同的插件会各自成行,同一插件被多个源收录时仍只显示一条(保留高版本)。 若某条目的 entry_path 已被本地一个不同作者的插件占用,返回 installed=false、conflict=true,并在 conflict_with 中描述占用者;此时安装该插件需要用户确认覆盖。 拉取结果在服务端缓存 5 分钟:分页与搜索都在缓存的完整列表上做切片/过滤,不会重复拉取远端。传 force=true 绕过缓存强制重拉(供「刷新」按钮使用,翻页与搜索不要传)。安装状态(installed/has_update/conflict)不受缓存影响,每次请求都从数据库实时计算。 Flutter/Lynx 商店通常由客户端逐个拉取清单并渐进展示;此接口保留为 Web 跨域或网络失败的兼容回退。携带源 Token 的远端请求绕过 GitHub 加速代理,此接口不会读取共享的 GitHub 发现 Token。
需要认证
此接口需要 Bearer Token 认证
请求体
刷新请求
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
all_sources | boolean | 否 | |
force | boolean | 否 | Force 为 true 时绕过服务端缓存强制重新拉取。供「刷新」按钮使用; |
| 翻页与搜索不应设置它,否则每翻一页都会重拉整棵注册表树。 | |||
github_proxy | string | 否 | |
page | integer | 否 | |
page_size | integer | 否 | |
registry_url | string | 否 | |
search | string | 否 | |
token | string | 否 |
响应
200 - 插件列表
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | integer | 否 | |
page_size | integer | 否 | |
plugins | registryPluginEntry[] | 否 | |
total | integer | 否 | |
warnings | string[] | 否 |
400 - 请求格式错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 拉取注册表失败
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/storage/cleanup
清理孤儿持久化存储
删除 plugin_storage 表中不属于任何已安装插件的数据。当插件被卸载后,其持久化存储数据会保留在数据库中;此端点用于清理这些无主数据。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 清理完成
类型: map[string]string
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应:
application/json
POST /jsplugins/update-all
批量更新所有 JS 插件
检查并更新所有具有远程更新源的 JS 插件。跳过无 update_url 的插件和已是最新版的插件,逐个下载并安装更新,失败不中断其他插件的更新流程。设置 force=true 可跳过版本检查强制重新下载安装所有插件。
需要认证
此接口需要 Bearer Token 认证
请求体
请求参数
类型: object
响应
200 - 批量更新结果
类型: jsPluginBatchUpdateResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
failed | integer | 否 | |
message | string | 否 | |
results | jsPluginBatchUpdateResult[] | 否 | |
skipped | integer | 否 | |
total | integer | 否 | |
updated | integer | 否 |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
POST /jsplugins/upload
上传安装 JS 插件
上传新的 JS 插件文件(.jsplugin.zip 压缩包)
需要认证
此接口需要 Bearer Token 认证
表单参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | JS插件文件 (.jsplugin.zip) |
响应
201 - 上传成功
类型: map[string]any
400 - 请求数据错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
401 - 未授权
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 服务器错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
multipart/form-data - 响应:
application/json
GET /plugins/health
音源健康度
返回各音乐源插件的下载成功率、健康度分类(green/yellow/red)与最近 5 条失败原因。
需要认证
此接口需要 Bearer Token 认证
响应
200 - OK
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
plugins | PluginHealthSnapshot[] | 否 |
内容类型
- 响应:
application/json
PUT /settings/github-discovery-token
保存 GitHub 发现 Token
将 GitHub Token 保存到服务器配置,供各客户端共用。token 必填,空字符串表示清除;去掉首尾空白,内部只接受 ASCII 字母、数字和下划线,最长 512 字节。立即生效,无需预先创建配置;响应禁止缓存。
需要认证
此接口需要 Bearer Token 认证
请求体
GitHub Token,空字符串表示清除
类型: githubDiscoveryTokenSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
token | string | 否 |
响应
200 - 保存后的 Token
类型: githubDiscoveryTokenSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
token | string | 否 |
400 - 请求格式或 Token 格式错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
401 - 未登录
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 保存配置失败
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
GET /settings/github-discovery-token
获取 GitHub 发现 Token
返回服务器保存的完整 GitHub Token,供已登录客户端直接请求 GitHub API。未配置时 token 为空;服务器不代发发现请求。响应禁止缓存。
需要认证
此接口需要 Bearer Token 认证
响应
200 - GitHub Token
类型: githubDiscoveryTokenSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
token | string | 否 |
401 - 未登录
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 读取配置失败
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应:
application/json
PUT /settings/plugin-registries
保存插件订阅源列表
保存用户配置的插件注册表订阅源 URL 列表。每个源包含 URL、名称和是否启用。
需要认证
此接口需要 Bearer Token 认证
请求体
订阅源列表
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
registries | RegistryConfig[] | 否 |
响应
200 - 保存后的订阅源列表
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
registries | RegistryConfig[] | 否 |
400 - 请求格式错误
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
500 - 保存配置失败
类型: ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息(可选) 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求:
application/json - 响应:
application/json
GET /settings/plugin-registries
获取插件订阅源列表
获取用户保存的所有插件注册表订阅源 URL。未配置时返回空列表。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 订阅源列表
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
registries | RegistryConfig[] | 否 |
内容类型
- 响应:
application/json
