开发者接口

供开发者使用的场景与插件发布、管理接口。

发布场景

POST /api/v1/marketplace/developer/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "code-reviewer",
  "version": "1.0.0",
  "name": "Code Reviewer",
  "nameZh": "代码审查",
  "type": "programmatic",
  "category": "development",
  "permissions": ["filesystem:read"],
  "changelog": "首次发布"
}

上传场景包

POST /api/v1/marketplace/developer/:id/upload-package
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: code-reviewer-1.0.0.tar.gz

我的场景

GET /api/v1/marketplace/developer/scenarios?page=1&pageSize=20
Authorization: Bearer <token>

更新场景

PUT /api/v1/marketplace/developer/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "nameZh": "代码审查助手",
  "descriptionZh": "更新后的描述"
}

下架场景

DELETE /api/v1/marketplace/developer/:id
Authorization: Bearer <token>

错误码

错误码	说明
SCENARIO_NOT_FOUND	场景不存在
SCENARIO_VERSION_EXISTS	版本已存在
SCENARIO_PACKAGE_TOO_LARGE	包大小超限
SCENARIO_VALIDATION_FAILED	校验失败
DEVELOPER_NOT_VERIFIED	开发者未实名认证
RATE_LIMIT_EXCEEDED	请求频率超限
PLUGIN_NOT_FOUND	插件不存在
PLUGIN_KEY_EXISTS	插件标识（pluginKey）已存在
PLUGIN_INVALID_CATEGORY	插件分类不合法
PLUGIN_VERSION_EXISTS	插件版本已存在
PLUGIN_NOT_OWNED	只能操作自己名下的插件

插件管理

插件发布走独立接口组 /api/v1/developer/plugins，与场景接口并列。

审核机制：开发者提交的插件与其版本一律进入 pending 状态，管理员审核通过后才会出现在插件市场。 这与管理端 /api/v1/admin/plugins 的「创建即上架」行为不同。

权限要求

接口	权限
我的插件列表 / 插件详情	开发者账号即可
发布 / 更新 / 价格 / 图标 / 上传版本 / 下架	已实名认证（status = verified）

未实名时调用写接口会返回 403。实名状态可通过 GET /api/v1/developer/identity/status 查询。

发布插件

发布后插件处于待审核状态，此时还没有任何版本 —— 需要再调「上传插件版本」写入首个版本。

POST /api/v1/developer/plugins/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "pluginKey": "my-plugin",
  "name": "My Plugin",
  "nameZh": "我的插件",
  "description": "What this plugin does",
  "descriptionZh": "插件说明",
  "type": "mcp",
  "category": "development",
  "isFree": true,
  "price": 0,
  "validityDays": 0,
  "tags": ["mcp", "automation"],
  "license": "MIT"
}

字段说明：

字段	必填	说明
pluginKey	是	插件唯一标识，须与插件包内 manifest.json 的 id 完全一致，发布后不可修改。小写字母/数字/连字符，字母开头，3-64 字符
name / nameZh	是	英文名 / 中文名
description / descriptionZh	是	英文描述 / 中文描述
type	是	mcp / tool / channel / scenario / hook / composite / skill
category	否	见下方分类表，默认 productivity
isFree	否	默认 true
price	否	付费插件价格（元）。isFree = false 时须大于 0
validityDays	否	0 或不传 = 永久买断；> 0 = 按天计费，到期需续费
tags / license / homepage / repository	否	标签、许可证、主页、仓库地址

可用分类：productivity、development、automation、database、design、frontend、office、ai、utility、channel。

上传插件版本

必须先有插件再传包 —— 版本接口以 pluginId 作为路径参数。 包内 manifest.json 的 id / version 必须分别与插件 pluginKey 和请求参数 version 一致，否则会被拒绝。

POST /api/v1/developer/plugins/:pluginId/upload-version
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: my-plugin-1.0.0.tar.gz
version: 1.0.0
changelog: 首次发布

待审核版本不抢占当前版本：新版本通过审核前，市场中仍下发上一个已通过审核的版本， 不会出现「最新版本待审核、用户下不到包」的情况。

我的插件

GET /api/v1/developer/plugins?page=1&pageSize=20&reviewStatus=pending
Authorization: Bearer <token>

reviewStatus 可选：pending、approved、rejected、taken_down。

插件详情

返回插件全部字段及版本历史（含每个版本的审核状态与是否为当前版本）。

GET /api/v1/developer/plugins/:pluginId
Authorization: Bearer <token>

更新插件

pluginKey、featured、enabled 及审核相关字段不可通过此接口修改。

PUT /api/v1/developer/plugins/:pluginId
Authorization: Bearer <token>
Content-Type: application/json

{
  "nameZh": "我的插件（新名称）",
  "descriptionZh": "更新后的描述"
}

设置价格

validityDays 传 0 或不传表示永久买断（服务端统一归一化为 null 落库）。

PUT /api/v1/developer/plugins/:pluginId/price
Authorization: Bearer <token>
Content-Type: application/json

{
  "price": 29.9,
  "validityDays": 365
}

上传插件图标

限制 256KB，支持 png / jpeg / svg / webp，服务端转 base64 data URL 存入 icon 字段（不依赖对象存储）。

POST /api/v1/developer/plugins/:pluginId/icon
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: icon.png

下架插件

软下架：保留历史版本与用户已购记录，仅停止市场下发。

DELETE /api/v1/developer/plugins/:pluginId
Authorization: Bearer <token>