API 密钥与开放 API

生成 API 密钥，让 Agent 或 CI 上传版本、更新说明并提交审核。

Plugin API v1

Documentation content is currently available in Simplified Chinese.

除了在开发者工作台手动上传，飞块拓展商店还提供开放 API。你可以为 Agent、CI 或脚本生成 API 密钥，让它自动上传 .flyext 安装包、补全公开资料、提交审核并跟踪状态。

#1. 生成与管理 API 密钥

登录拓展商店，进入「账户设置」中的「API 密钥」区域。
输入用途名称（例如 release-bot），点击「生成密钥」。
明文密钥只显示一次，请立即复制并保存到密钥管理服务；服务端仅保存 SHA-256 摘要。
不再使用时随时撤销；撤销后，使用该密钥的请求立即失效。

密钥形如 fdk_ 加 43 位 Base64URL 字符。
每个账户最多保留 20 个有效密钥。
密钥只能访问 /api/v1/open/*，不能替代浏览器或桌面端登录态访问 /account/*、/developer/* 或 /admin/*。
密钥的权限与所属账户一致，只能操作该账户拥有命名空间下的插件。

#2. 认证方式

所有开放接口使用 Bearer 认证：

curl -H "Authorization: Bearer $FLYON_KEY" \
  "$BASE/open/me"

其中 BASE 为 https://<商店域名>/api/v1。与浏览器 Cookie 请求不同，开放接口不要求 Origin 请求头，因为 Bearer 凭据不属于浏览器环境自动携带的授权。请求仍受账户速率限制；密钥无效、已被撤销或账户被停用时返回 401。

#3. 接口一览

方法 / 路径	用途
GET /open/me	当前密钥对应的账户
GET /open/namespaces	可用命名空间与插件数量
GET /open/plugins	本人插件列表及发布状态
GET /open/plugins/:id	插件详情、版本与审计活动
PATCH /open/plugins/:id	保存插件公开资料草稿，字段与开发者页面一致
POST /open/plugins	multipart `file` 上传 `.flyext`，自动创建插件草稿
POST /open/plugins/:id/releases	multipart `file` 追加不可覆盖的新版本
POST /open/images	multipart `file` 上传 16:9 截图，返回资产 UUID
GET /open/releases/:id	版本状态、检查报告、驳回原因与提交快照
PATCH /open/releases/:id	更新版本说明 `{changelog}`（0–5000 字）
POST /open/releases/:id/submit	提交审核；检查中提交会冻结资料快照
POST /open/releases/:id/cancel	撤回审核中的提交
POST /open/releases/:id/retry	重新检查 `check_failed` 的同一不可变包

#4. 发布第一个版本

插件 ID、名称与版本号由安装包根目录的 manifest.json 决定，请求中不需要也无法手工指定。首次上传会自动创建私有插件草稿，并返回版本记录 UUID：

curl -H "Authorization: Bearer $FLYON_KEY" \
  -F file=@demo.flyext \
  -F changelog="首个版本" \
  "$BASE/open/plugins"

资料字段与开发者页面一致：name、summary、description、category、tags、icon、screenshots（POST /open/images 返回的资产 UUID）、repository、website、support、privacyPolicy 与 license。网站、支持与隐私政策链接必须是 HTTPS 或空字符串；介绍为纯文本。也可以提供 i18n 译文，规则与商店资料一致。

curl -X PATCH -H "Authorization: Bearer $FLYON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo","summary":"Summary","description":"Details","category":"productivity","tags":[],"icon":"🧩","screenshots":[],"repository":"","license":"MIT"}' \
  "$BASE/open/plugins/demo.plugin"

首次上传只创建草稿，必须补全必填资料并等待包体检查通过后才能提交审核。提交可以发生在检查完成之前：此时资料快照立即冻结，后台检查成功后自动进入内容审核队列。

#5. 发布新版本与更新说明

版本号必须递增并重新打包。已上传的同版本包体不可覆盖，重复版本返回 409：

curl -H "Authorization: Bearer $FLYON_KEY" \
  -F file=@demo-1.1.0.flyext \
  -F changelog="修复若干问题" \
  "$BASE/open/plugins/demo.plugin/releases"

上传后仍可补充或修改版本说明：

curl -X PATCH -H "Authorization: Bearer $FLYON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changelog":"本次更新修复了若干问题"}' \
  "$BASE/open/releases/<release-id>"

changelog 为可选字段，去空白后最多 5000 字，缺省为空字符串。
仅所有者可编辑检查中、检查失败、待提交或驳回的版本。
提交审核后须先撤回才能修改；已发布及已下架版本不可改写。

#6. 提交与跟踪状态

# 提交审核
curl -X POST -H "Authorization: Bearer $FLYON_KEY" \
  "$BASE/open/releases/<release-id>/submit"

# 轮询状态：checking → pending → published / rejected
curl -H "Authorization: Bearer $FLYON_KEY" \
  "$BASE/open/releases/<release-id>"

checking：后台正在检查归档结构、清单、权限与资源，不执行插件代码。
check_failed：检查失败，可修正后上传新版本，或对同一不可变包调用 retry。
pending：已进入人工审核队列。
rejected：审核驳回，响应中的 reason 给出原因；修改资料或上传修复版本后重新提交。
published：版本已公开，用户可在商店与桌面端安装。

GET /open/releases/:id 还会返回检查报告、权限差异、提交快照与审核说明，便于 Agent 根据稳定字段决定下一步操作。提交期间可调用 cancel 撤回整次提交，再继续修改资料或版本说明。

#7. 错误与限流

错误响应为 JSON，包含 statusCode、message、requestId 与稳定的 code；请根据 code 而非错误句子做分支。响应头 X-Request-ID 便于排查单次请求。

认证写请求限制为每分钟 30 次，一般写请求 120 次，读取 1200 次。超限返回 429 和 Retry-After 秒数。客户端应对 429 与临时 503 做指数退避，不要并发重试同一个提交。

发布流程中的命名空间申请、资料完整性与人工审核规则，与手动发布完全一致。