Astra Gate插件市场与发布
官方插件市场的结构、注册表接口，以及如何把插件发布到市场或自建市场
Astra 的插件市场由官网（astra-gate.si）提供。控制台和 astra plugin market 默认读取它的注册表；官网上的 插件市场页面 是同一份数据的网页版。
市场里有什么
注册表由两部分合成，同名时官网发布的条目覆盖社区条目：
- 社区清单：magpie-community 的
registry.json，官网定时拉取，并用 npm 补全每个包的最新版本、描述和许可证； - 官网发布的条目：用下面的接口发布。可以只是一条指向 npm 包（或
github:用户/仓库）的条目，也可以连同 tarball 一起上传，由官网托管。
托管的包由客户端从官网下载，安装前必须与注册表里的 SHA-256（和 SHA-512，若有）一致；解压时只接受普通文件，路径限制在包目录内，与 npm 包的安装规则相同。同样以 --ignore-scripts 安装，安装脚本不会运行。
接口
都在 https://astra-gate.si/api/plugin-market/ 下。
| 方法与路径 | 说明 |
|---|---|
GET registry.json | 注册表。支持 ETag / If-None-Match；Astra 客户端默认读取它 |
GET search?q= | 搜索：先是市场自己的条目（source: "astra"），再是 npm 与 GitHub magpie-plugin 主题的结果。q 不超过 100 个字符 |
GET packages/<目录名>/<版本>.tgz | 下载托管的 tarball。目录名是包名把 / 写成 __（@scope/name → @scope__name）；地址以注册表里的 tarballs[].url 为准 |
POST packages | 发布一个 tarball（需要 token） |
POST entries | 发布或更新一条元数据条目，不带 tarball（需要 token） |
DELETE entries?package=<包名>[&version=<版本>] | 下架条目，或只下架某个托管版本（需要 token） |
注册表里每个插件的字段：
| 字段 | 说明 |
|---|---|
package | npm 包名，必填 |
name、icon、summary | 显示名、图标（图标名或 https 地址）、按语言的简介（en / zh） |
kind | provider、middleware、agent 或 pi |
providers、replaces | 提供商插件登录的服务商 ID；它替代的 Astra 内置订阅 |
spec | 安装时用的 spec，缺省为包名；可以是 github:用户/仓库 |
latest、description、license | 最新版本、描述、许可证 |
author、homepage、repository、tags | 作者、主页、仓库、标签 |
minAstraVersion | 能运行它的最低 Astra 版本；客户端版本不够时安装会失败并说明 |
origin | astra（官网发布）或 upstream（社区清单） |
tarballs | 官网托管的版本，最新在前：version、url、sha256、sha512、size、publishedAt |
发布插件
发布需要官网配置了 PLUGIN_UPLOAD_TOKEN（与桌面客户端发布用的 CLIENT_UPLOAD_TOKEN 分开）；没有配置时，发布接口一律返回 503。
先用 npm pack 打出 tarball，再上传：
npm pack # → name-1.0.0.tgz
curl -X POST https://astra-gate.si/api/plugin-market/packages \
-H "Authorization: Bearer $PLUGIN_UPLOAD_TOKEN" \
-H "x-astra-meta-b64: $(echo '{"summary":{"zh":"一句话简介","en":"One line"},"minAstraVersion":"0.8.0"}' | base64)" \
--data-binary @name-1.0.0.tgz- 包名和版本取自 tarball 里的
package.json；x-astra-package头可选，给了就必须与包内名字一致。 x-astra-meta-b64可选，内容是 base64 的 JSON，可以带name、icon、kind、providers、replaces、summary、author、homepage、repository、tags、minAstraVersion。没给的字段从package.json（描述、许可证、作者、仓库、关键字）和已有条目里取。- 版本不可变：同一个版本已经存在时返回 409。要修改，发布新版本。
- tarball 不超过 50 MB。
只登记一条指向 npm 的条目（不托管包）：
curl -X POST https://astra-gate.si/api/plugin-market/entries \
-H "Authorization: Bearer $PLUGIN_UPLOAD_TOKEN" -H "content-type: application/json" \
-d '{"package":"opencode-foo-auth","kind":"provider","providers":["foo"],"summary":{"zh":"Foo 订阅"}}'下架：
# 整个条目（含托管的所有版本）
curl -X DELETE "https://astra-gate.si/api/plugin-market/entries?package=@scope/name" -H "Authorization: Bearer $PLUGIN_UPLOAD_TOKEN"
# 只下架一个版本
curl -X DELETE "https://astra-gate.si/api/plugin-market/entries?package=@scope/name&version=1.0.0" -H "Authorization: Bearer $PLUGIN_UPLOAD_TOKEN"社区清单里的条目不能在这里下架；要隐藏它，用同名条目覆盖。
自己部署市场
官网镜像（docs/Dockerfile）就是市场服务端。需要持久化的数据都在 DATA_DIR（镜像里是 /app/data）下的 plugin-market/ 目录，请挂载卷。相关环境变量：
| 变量 | 说明 |
|---|---|
PLUGIN_UPLOAD_TOKEN | 发布与下架用的 Bearer token；不设则发布接口关闭 |
PLUGIN_MARKET_UPSTREAM | 社区清单的地址，默认 magpie-community 的 registry.json；设为 off 则只用站内条目和镜像内置的快照 |
GITHUB_TOKEN | 可选，提高搜索访问 GitHub 的限额 |
让 Astra 使用自建的市场：在 设置 → 插件市场 里填 https://你的域名/api/plugin-market/registry.json，或设置环境变量 ASTRA_PLUGIN_MARKET。搜索地址取注册表地址旁边的 search，所以注册表地址需要以 /registry.json 结尾；否则搜索不可用，其余功能不受影响。