Skip to content

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

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

PUT /jsplugins/{id} ​

更新 JS 插件

上传新的 JS 插件文件以更新现有插件

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

表单参数 ​

参数类型必填说明
filefile是JS插件文件 (.jsplugin.zip)

响应 ​

200 - 更新成功 ​

类型: map[string]any

400 - 请求数据错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: multipart/form-data
  • 响应: application/json

DELETE /jsplugins/{id} ​

删除 JS 插件

根据插件ID删除 JS 插件。可通过 keep_data 参数保留插件数据目录(文件系统存储),持久化存储(数据库)始终保留。

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

查询参数 ​

参数类型必填说明
keep_datastring否是否保留插件数据目录(true/false,默认 false)

响应 ​

200 - 删除成功 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

GET /jsplugins/{id} ​

获取 JS 插件详情

根据插件ID获取 JS 插件的详细信息

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

响应 ​

200 - JS插件信息 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

GET /jsplugins/{id}/check-update ​

检查 JS 插件更新

检查指定 JS 插件的远程更新

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

响应 ​

200 - 更新信息 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

POST /jsplugins/{id}/disable ​

禁用 JS 插件

禁用指定的 JS 插件

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

响应 ​

200 - 禁用成功 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

POST /jsplugins/{id}/enable ​

启用 JS 插件

启用指定的 JS 插件

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

响应 ​

200 - 启用成功 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

POST /jsplugins/{id}/update ​

下载并更新 JS 插件

从远程下载并更新指定的 JS 插件。设置 force=true 可跳过版本检查强制重新下载安装。

需要认证

此接口需要 Bearer Token 认证

路径参数 ​

参数类型必填说明
idinteger是插件ID

响应 ​

200 - 更新成功 ​

类型: map[string]any

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

404 - 插件不存在 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: 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 认证

请求体 ​

安装请求

类型: registryInstallRequest

字段类型必填说明
download_urlstring否
github_proxystring否
overwriteboolean否Overwrite 为 true 时允许覆盖掉本地已装的同 entry_path 但不同作者的插件。
默认 false:这种情况返回 409,由前端二次确认后带该字段重发。
source_urlstring否SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传:
当未显式提供 token 时,后端据此从 plugin_registries 配置解析该源的 token。
tokenstring否

响应 ​

200 - 安装结果(更新已有插件) ​

类型: jsPluginUploadResponse

字段类型必填说明
failedinteger否
messagestring否
resultsjsPluginUploadResult[]否
successinteger否
totalinteger否

201 - 安装结果(新插件) ​

类型: jsPluginUploadResponse

字段类型必填说明
failedinteger否
messagestring否
resultsjsPluginUploadResult[]否
successinteger否
totalinteger否

400 - 请求格式错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

409 - entry_path 已被另一个作者的插件占用,需用户确认后带 overwrite=true 重试 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 下载或安装失败 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: 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 认证

请求体 ​

刷新请求

类型: registryRefreshRequest

字段类型必填说明
all_sourcesboolean否
forceboolean否Force 为 true 时绕过服务端缓存强制重新拉取。供「刷新」按钮使用;
翻页与搜索不应设置它,否则每翻一页都会重拉整棵注册表树。
github_proxystring否
pageinteger否
page_sizeinteger否
registry_urlstring否
searchstring否
tokenstring否

响应 ​

200 - 插件列表 ​

类型: registryRefreshResponse

字段类型必填说明
pageinteger否
page_sizeinteger否
pluginsregistryPluginEntry[]否
totalinteger否
warningsstring[]否

400 - 请求格式错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 拉取注册表失败 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

POST /jsplugins/storage/cleanup ​

清理孤儿持久化存储

删除 plugin_storage 表中不属于任何已安装插件的数据。当插件被卸载后,其持久化存储数据会保留在数据库中;此端点用于清理这些无主数据。

需要认证

此接口需要 Bearer Token 认证

响应 ​

200 - 清理完成 ​

类型: map[string]string

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 响应: application/json

POST /jsplugins/update-all ​

批量更新所有 JS 插件

检查并更新所有具有远程更新源的 JS 插件。跳过无 update_url 的插件和已是最新版的插件,逐个下载并安装更新,失败不中断其他插件的更新流程。设置 force=true 可跳过版本检查强制重新下载安装所有插件。

需要认证

此接口需要 Bearer Token 认证

请求体 ​

请求参数

类型: object

响应 ​

200 - 批量更新结果 ​

类型: jsPluginBatchUpdateResponse

字段类型必填说明
failedinteger否
messagestring否
resultsjsPluginBatchUpdateResult[]否
skippedinteger否
totalinteger否
updatedinteger否

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

POST /jsplugins/upload ​

上传安装 JS 插件

上传新的 JS 插件文件(.jsplugin.zip 压缩包)

需要认证

此接口需要 Bearer Token 认证

表单参数 ​

参数类型必填说明
filefile是JS插件文件 (.jsplugin.zip)

响应 ​

201 - 上传成功 ​

类型: map[string]any

400 - 请求数据错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

401 - 未授权 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 服务器错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: multipart/form-data
  • 响应: application/json

GET /plugins/health ​

音源健康度

返回各音乐源插件的下载成功率、健康度分类(green/yellow/red)与最近 5 条失败原因。

需要认证

此接口需要 Bearer Token 认证

响应 ​

200 - OK ​

类型: pluginHealthResponse

字段类型必填说明
pluginsPluginHealthSnapshot[]否

内容类型 ​

  • 响应: application/json

PUT /settings/github-discovery-token ​

保存 GitHub 发现 Token

将 GitHub Token 保存到服务器配置,供各客户端共用。token 必填,空字符串表示清除;去掉首尾空白,内部只接受 ASCII 字母、数字和下划线,最长 512 字节。立即生效,无需预先创建配置;响应禁止缓存。

需要认证

此接口需要 Bearer Token 认证

请求体 ​

GitHub Token,空字符串表示清除

类型: githubDiscoveryTokenSetting

字段类型必填说明
tokenstring否

响应 ​

200 - 保存后的 Token ​

类型: githubDiscoveryTokenSetting

字段类型必填说明
tokenstring否

400 - 请求格式或 Token 格式错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

401 - 未登录 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 保存配置失败 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

GET /settings/github-discovery-token ​

获取 GitHub 发现 Token

返回服务器保存的完整 GitHub Token,供已登录客户端直接请求 GitHub API。未配置时 token 为空;服务器不代发发现请求。响应禁止缓存。

需要认证

此接口需要 Bearer Token 认证

响应 ​

200 - GitHub Token ​

类型: githubDiscoveryTokenSetting

字段类型必填说明
tokenstring否

401 - 未登录 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 读取配置失败 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 响应: application/json

PUT /settings/plugin-registries ​

保存插件订阅源列表

保存用户配置的插件注册表订阅源 URL 列表。每个源包含 URL、名称和是否启用。

需要认证

此接口需要 Bearer Token 认证

请求体 ​

订阅源列表

类型: pluginRegistriesSetting

字段类型必填说明
registriesRegistryConfig[]否

响应 ​

200 - 保存后的订阅源列表 ​

类型: pluginRegistriesSetting

字段类型必填说明
registriesRegistryConfig[]否

400 - 请求格式错误 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

500 - 保存配置失败 ​

类型: ErrorResponse

字段类型必填说明
detailstring否详细错误信息(可选) 示例: "详细错误信息"
errorstring否错误信息 示例: "操作失败"

内容类型 ​

  • 请求: application/json
  • 响应: application/json

GET /settings/plugin-registries ​

获取插件订阅源列表

获取用户保存的所有插件注册表订阅源 URL。未配置时返回空列表。

需要认证

此接口需要 Bearer Token 认证

响应 ​

200 - 订阅源列表 ​

类型: pluginRegistriesSetting

字段类型必填说明
registriesRegistryConfig[]否

内容类型 ​

  • 响应: application/json