后端 API 参考

插件的全生命周期由四组接口支撑。开发者最常用的是「开发者接口」；「管理接口」用于官方插件与紧急运维；「公开接口」「用户接口」由客户端插件中心调用。

接口组	前缀	认证
公开接口	`/api/v1/plugins`	无需认证
用户接口	`/api/v1/plugins`	需登录
开发者接口	`/api/v1/developer/plugins`	开发者 JWT（写操作需实名）
管理接口	`/api/v1/admin/plugins`	ADMIN / SUPER_ADMIN

公开接口

方法	路径	说明
GET	`/api/v1/plugins/browse`	浏览插件市场（支持搜索、分类、排序、分页）
GET	`/api/v1/plugins/featured`	推荐插件
GET	`/api/v1/plugins/popular`	热门插件（按下载量排序）
GET	`/api/v1/plugins/categories`	市场分类列表（含插件数统计）
GET	`/api/v1/plugins/detail/:pluginId`	插件详情
GET	`/api/v1/plugins/versions/:pluginId`	版本历史
GET	`/api/v1/plugins/reviews/:pluginId`	评价列表

已登录用户请求这些接口时会附带购买状态。

用户接口

方法	路径	说明
GET	`/api/v1/plugins/download/:pluginId/:version`	获取下载地址（返回预签名 URL + SHA256；ConfigOnly 模式返回 `configOnly: true` + manifest）
GET	`/api/v1/plugins/installed`	我的已安装列表
POST	`/api/v1/plugins/install/:pluginId`	上报安装（需带 `version`）
POST	`/api/v1/plugins/purchase/:pluginId`	购买插件
POST	`/api/v1/plugins/rate/:pluginId`	评价插件

开发者接口

面向第三方开发者，配合开发者中心使用。字段级说明与完整请求示例见开发者接口。

方法	路径	说明	权限
GET	`/api/v1/developer/plugins`	我的插件列表（`page` / `pageSize` / `reviewStatus`）	开发者
GET	`/api/v1/developer/plugins/:pluginId`	插件详情（含全部版本与最近购买记录）	开发者
POST	`/api/v1/developer/plugins/publish`	发布插件（进入待审核）	已实名
PUT	`/api/v1/developer/plugins/:pluginId`	更新插件基本信息	已实名
PUT	`/api/v1/developer/plugins/:pluginId/price`	设置价格与有效期	已实名
POST	`/api/v1/developer/plugins/:pluginId/icon`	上传图标（≤ 256KB，转 base64 存 `icon` 字段）	已实名
POST	`/api/v1/developer/plugins/:pluginId/upload-version`	上传版本包（.tar.gz，≤ 100MB，进入待审核）	已实名
POST	`/api/v1/developer/plugins/:pluginId/create-version`	直接创建版本（ConfigOnly / 内联代码，无需传包）	已实名
DELETE	`/api/v1/developer/plugins/:pluginId`	下架插件（软下架）	已实名

不可通过开发者接口修改的字段

字段	原因
`pluginKey`	改了会导致历史版本 manifest.id 失配
`featured` / `enabled`	推荐位与上下架由平台控制
审核相关字段	防止开发者绕过审核

审核状态

reviewStatus 取值：pending / approved / rejected / taken_down。

开发者提交的插件与版本一律进入 pending
待审核版本不抢占当前版本，市场继续下发上一个已通过审核的版本

管理接口

供官方插件发布与运维使用，认证为管理员 JWT。

方法	路径	说明
GET	`/api/v1/admin/plugins`	管理端列表（`page` / `limit` / `reviewStatus` / `search`）
GET	`/api/v1/admin/plugins/categories`	全部分类定义（发布脚本以此为分类校验数据源）
GET	`/api/v1/admin/plugins/versions/pending`	待审核版本（跨插件聚合，`page` / `limit` / `reviewStatus` / `search`，`reviewStatus=all` 返回全部）
GET	`/api/v1/admin/plugins/:pluginId/versions`	某插件的全部版本（含 `pending` / `rejected`）
POST	`/api/v1/admin/plugins`	创建插件（创建即上架）
PUT	`/api/v1/admin/plugins/:pluginId`	更新插件（`pluginKey` / `source` / `type` 不可变）
DELETE	`/api/v1/admin/plugins/:pluginId`	删除插件
POST	`/api/v1/admin/plugins/:pluginId/upload`	上传版本包（.tar.gz）
POST	`/api/v1/admin/plugins/:pluginId/create-version`	直接创建版本
POST	`/api/v1/admin/plugins/:pluginId/icon`	上传图标
POST	`/api/v1/admin/plugins/:pluginId/review`	审核插件
POST	`/api/v1/admin/plugins/versions/:versionId/review`	审核插件版本

审核语义

插件审核（/admin/plugins/:pluginId/review）请求体 { approved, reviewNote?, approvePendingVersion? }：

通过时会把插件置为 approved + enabled: true（管理端是唯一的上下架控制方）
通过时若该插件没有任何已通过版本，会自动放行最新的一个待审版本，同步 isLatest 与 latestVersion —— 否则插件虽已上架，客户端却拿不到可下载的包
传 approvePendingVersion: false 可关闭上述联动，改为逐个版本单独审核

版本审核（/admin/plugins/versions/:versionId/review）请求体 { approved, reviewNote? }：

通过：在事务内把旧版本 isLatest 置 false、本版本置 true，并回写 plugin.latestVersion
驳回：写入 reviewNote 并清除 isLatest，避免被驳回的版本继续占据最新位
通过时若插件处于 taken_down（开发者主动下架），不会自动重新上架

无论走哪条路径，插件与版本最终都会收敛到「插件 approved + 至少一个 approved 版本」的可下载状态。

未通过审核的版本不会下发：GET /plugins/download/:pluginId/:version 与 POST /plugins/install/:pluginId 都会拒绝 reviewStatus !== 'approved' 的版本。

列表分页与审核留痕

两个列表接口（/admin/plugins、/admin/plugins/versions/pending）都返回统一的分页结构，过滤与检索全部在服务端完成：

json

{
  "items": [],
  "total": 128,
  "page": 1,
  "limit": 20,
  "counts": { "all": 128, "pending": 6, "approved": 118, "rejected": 4, "taken_down": 0 }
}

search：按 pluginKey / 名称模糊匹配；插件版本还会匹配版本号与所属插件
counts：与 search 同条件、不受 reviewStatus 影响的状态计数，供审核中心的状态页签角标使用
单页 limit 上限 100（超出自动收敛），避免一次拉爆

/admin/plugins/versions/pending 的 reviewStatus 缺省值是 pending，要看全部必须显式传 reviewStatus=all（/admin/plugins 省略即不过滤）。

每次审核都会留下两类痕迹（供多人协管时追溯）：

业务表上的 reviewedBy：执行审核的管理员 User.id；列表接口附带回填的 reviewerLabel（用户名优先，回退邮箱/ID）
audit_logs 流水：action 为 REVIEW_APPROVE / REVIEW_REJECT， detail 记录资源类型、资源 ID、结论、触发来源与备注；触发来源区分 admin（管理员直接操作）、linkage（审核 A 连带改动 B，如插件过审顺带放行版本）、auto-validation（系统校验失败自动驳回）

安装流程（客户端视角）

mermaid

sequenceDiagram
    participant U as 用户
    participant C as 客户端
    participant B as 后端

    U->>C: 插件中心点击「安装」
    C->>B: GET /plugins/download/:pluginId/:version
    B-->>C: 预签名 URL + SHA256（或 configOnly + manifest）
    C->>C: 下载 .tar.gz → SHA256 校验
    C->>C: 解压到 userData/plugins/<pluginKey>/<version>/
    C->>C: 读取 manifest.json
    C-->>U: 有必填配置 → 弹出配置表单
    C->>C: 注册 MCP 服务（注入配置到 env / args）
    C->>B: POST /plugins/install/:pluginId（上报安装）
    C->>C: autoConnect → 建立连接

安装后目录结构与记录文件见本地调试。

错误码

错误码	说明
`PLUGIN_NOT_FOUND`	插件不存在
`PLUGIN_KEY_EXISTS`	插件标识（pluginKey）已存在
`PLUGIN_INVALID_CATEGORY`	插件分类不合法
`PLUGIN_VERSION_EXISTS`	插件版本已存在
`PLUGIN_NOT_OWNED`	只能操作自己名下的插件
`DEVELOPER_NOT_VERIFIED`	开发者未实名认证
`RATE_LIMIT_EXCEEDED`	请求频率超限

场景类接口的错误码见错误码。

常见调用错误

报错	原因与处理
`manifest.id does not match plugin.pluginKey`	包内 manifest 的 `id` 与插件 `pluginKey` 不一致（大小写敏感）
`manifest.version does not match requested version`	manifest 的 `version` 与上传参数不一致
`Invalid category "xxx"`	`category` 不在后端分类表内，见分类
`Plugin package file is required`	未携带 `file` 字段，检查 `-F "file=@..."`
403	开发者未实名，或 Token 权限不足

下一步

打包与发布 — 发布流程与审核
常见问题 — 排查清单

后端 API 参考 ​

公开接口 ​

用户接口 ​

开发者接口 ​

不可通过开发者接口修改的字段 ​

审核状态 ​

管理接口 ​

审核语义 ​

列表分页与审核留痕 ​

安装流程（客户端视角） ​

错误码 ​

常见调用错误 ​

下一步 ​