---
title: "刷新插件注册表"
method: POST
path: "/jsplugins/registry/refresh"
tags: ["JS插件管理"]
---

# 刷新插件注册表

`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）不受缓存影响，每次请求都从数据库实时计算。

## Request body

- HandlersRegistryRefreshRequest
  - `all_sources` boolean
  - `force` boolean — Force 为 true 时绕过服务端缓存强制重新拉取。供「刷新」按钮使用； 翻页与搜索不应设置它，否则每翻一页都会重拉整棵注册表树。
  - `github_proxy` string
  - `page` integer
  - `page_size` integer
  - `registry_url` string
  - `search` string
  - `token` string

## Response `200`

插件列表

- HandlersRegistryRefreshResponse
  - `page` integer
  - `page_size` integer
  - `plugins` HandlersRegistryPluginEntry[]
    - `author` string
    - `conflict` boolean — Conflict 为 true 表示本地已装了同 entry_path 但**不同身份**的插件。 此时 installed=false（这不是同一个插件），安装它会覆盖掉本地那个。
    - `conflict_with` string — ConflictWith 描述占用该 entry_path 的本地插件，可直接展示给用户。
    - `description` string
    - `download_url` string
    - `entry_path` string
    - `has_update` boolean
    - `homepage` string
    - `icon` string
    - `identity` string — Identity 是 entry_path 之外的身份维度（规范化 author，或 GitHub 仓库兜底）。 entry_path 撞名时前端据 (entry_path, identity) 做稳定行标识与就地状态更新。 为空表示无法判定身份（此时仅按 entry_path 判定）。
    - `installed` boolean
    - `installed_version` string
    - `name` string
    - `source_name` string — SourceName 该插件所属订阅源名称（仅「全部」聚合模式返回）， 供 UI 区分 entry_path 相同的两个条目。
    - `source_url` string — SourceURL 该插件所属订阅源 URL（仅「全部」聚合模式返回）， 安装时回传给后端以按源解析私有源 token。
    - `version` string
  - `total` integer
  - `warnings` string[]

## Other responses

- `400` — 请求格式错误
- `500` — 拉取注册表失败

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/versions/ee41778dbf8f/schema)