打包与发布

插件通过后端插件市场上架，用户从客户端插件中心安装。本篇覆盖打包机制、两条发布路径、审核与版本管理。

两条发布路径

维度	开发者中心（第三方开发者）	管理端脚本（平台自研 / 批量）
接口	`/api/v1/developer/plugins`	`/api/v1/admin/plugins`
认证	开发者账号 JWT，写操作需已实名	管理员 JWT（ADMIN / SUPER_ADMIN）
审核	插件与版本进入 `pending`，审核通过后上架	创建即上架
适用	对外发布的第三方插件	官方插件、批量发布、CI

分发模式如何判定

打包与发布方式由 manifest.json 的 main 字段自动决定：

模式	判定条件	存储位置	客户端安装行为
Tarball	`main` 非空	对象存储（MinIO/S3）存 `.tar.gz`	下载 → SHA256 校验 → 解压
ConfigOnly	`main` 为空 + 有 MCP 能力	数据库存 manifest	不下载包，只写 manifest
内联代码	Tarball 上传失败时自动降级	数据库存 manifest（含 `inlineCode` / `inlineUiCode`）	从 manifest 还原成本地文件

内联降级无需人工干预：对象存储不可达时，脚本会把 index.js 写入 manifest.inlineCode、ui.js 写入 manifest.inlineUiCode，改走 create-version 接口。

打包细节

发布脚本使用系统 tar 命令自动打包，排除以下内容：

*.tar.gz        node_modules/        .git/        .DS_Store

包内必须包含 manifest.json，后端上传时会提取校验其 id 与 version。

bash

# 脚本内部等价命令
tar -czf my-tool-1.0.0.tar.gz \
  --exclude="my-tool/node_modules" \
  --exclude="my-tool/.git" \
  --exclude="my-tool/.DS_Store" \
  my-tool/

手工打包时注意：node_modules 一定要排除，否则包体积可能膨胀数十倍。

前置准备

后端地址：生产 https://gateway.aweeclaw.com，本地开发 http://localhost:3000
管理员 Token：需 ADMIN / SUPER_ADMIN 角色

bash

# 登录获取 Token
curl -X POST https://gateway.aweeclaw.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"<admin-email>","password":"<admin-password>"}' | jq -r '.data.accessToken'

export AWEECLAW_BACKEND_URL="https://gateway.aweeclaw.com"
export AWEECLAW_ADMIN_TOKEN="<上一步的 accessToken>"

不要把密码或 Token 硬编码进脚本或提交到仓库。

脚本发布：单个插件

bash

node scripts/publish-plugin.mjs plugins/my-tool \
  --changelog "Initial release"

脚本自动完成：

校验 manifest.json（必需字段、id / version 格式、MCP 能力声明）
拉取后端分类列表，校验 category 合法
打包 .tar.gz（排除 node_modules / .git）
创建或更新插件记录（POST 新建 / PUT 更新）
上传版本包或直接创建版本（按分发模式自动选择，失败时降级为内联代码）
若 icon 为本地相对路径，额外上传图标
清理临时包文件

常用选项

选项	说明
`--backend <url>`	后端地址（也可用 `AWEECLAW_BACKEND_URL`）
`--token <token>`	管理员 JWT（也可用 `AWEECLAW_ADMIN_TOKEN`）
`--version <ver>`	覆盖 manifest 中的版本号
`--changelog <text>`	版本变更日志
`--skip-upload`	仅打包不上传，用于本地预演与手工发布准备

仅打包（预演）

bash

node scripts/publish-plugin.mjs plugins/my-tool --skip-upload

产出的 my-tool-1.0.0.tar.gz 可直接用于开发者中心的手工上传。

脚本发布：批量

bash

# 标准模式：打包 + 上传对象存储
node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN

# direct 模式：无需对象存储，直接创建版本 + 内联代码
node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN --direct

# 仅发布指定插件
node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN --only mcp-brave-search,util-uuid-gen

# 跳过指定插件
node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN --skip ai-macro-recorder

# 模拟运行（不实际上传）
node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN --dry-run

选项	说明
`--backend <url>`	后端地址
`--token <token>`	管理员 JWT
`--only <ids>`	仅发布指定插件（逗号分隔）
`--skip <ids>`	跳过指定插件（逗号分隔）
`--dry-run`	仅模拟，不实际上传
`--direct`	使用直接创建版本接口，适合配置型 + 内联代码插件

批量模式的两个特殊处理：

type 不匹配自动重建：远程记录的 type 与 manifest 不一致时（后端不支持修改 type），脚本删除原记录后重建。
版本已存在跳过：上传返回 already exists 不视为错误。

开发者中心发布

面向第三方开发者，要求账号已完成实名认证。

第 1 步：本地打包

bash

node scripts/publish-plugin.mjs plugins/my-tool --skip-upload

第 2 步：在开发者中心发布插件

在「我的插件」中新建插件，pluginKey 必须与 manifest.id 完全一致（大小写敏感，发布后不可修改）。

第 3 步：上传版本包

上传第 1 步生成的 .tar.gz，填写 version（须与 manifest 一致）与 changelog。

第 4 步：上传图标（可选）

需要本地图标时，manifest.icon 写成相对路径（如 icon/icon.png），或直接在开发者中心上传。

第 5 步：等待审核

管理员在管理后台「审核中心」处理，分三个页签：场景包 / 插件 / 插件版本。

未通过审核前：

插件不出现在插件市场
待审核的新版本不抢占当前版本，市场仍下发上一个已通过审核的版本

审核结果与理由会写入 reviewStatus / reviewNote，可在开发者中心用 reviewStatus 过滤查看；驳回时务必阅读 reviewNote 了解具体原因，再修改重新提交。

插件与版本是两级审核。 首次发布时插件本体与首个版本都是 pending：管理员通过插件时会自动放行首个版本，保证上架即可安装；后续更新则只需审核新版本（插件本体保持 approved，老版本继续可用）。

权限要求

操作	要求
查看我的插件 / 插件详情	开发者账号即可
发布 / 更新 / 设置价格 / 上传图标 / 上传版本 / 下架	已实名认证（`status = verified`）

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

手动发布（分步 API）

需要更细粒度控制时直接调接口：

bash

# ① 创建插件记录
curl -X POST $AWEECLAW_BACKEND_URL/api/v1/admin/plugins \
  -H "Authorization: Bearer $AWEECLAW_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pluginKey": "my-tool",
    "name": "My Tool",
    "nameZh": "我的工具",
    "description": "Do something useful",
    "descriptionZh": "做一些有用的事",
    "type": "tool",
    "icon": "Sparkles",
    "category": "utility",
    "tags": ["demo"],
    "source": "official",
    "isFree": true,
    "platforms": ["darwin", "win32", "linux"]
  }'
# 返回 { "id": "abc123..." }

# ② 上传版本包
curl -X POST $AWEECLAW_BACKEND_URL/api/v1/admin/plugins/abc123/upload \
  -H "Authorization: Bearer $AWEECLAW_ADMIN_TOKEN" \
  -F "file=@my-tool-1.0.0.tar.gz" \
  -F "version=1.0.0" \
  -F "changelog=Initial release"

# 或：直接创建版本（ConfigOnly / 内联代码）
curl -X POST $AWEECLAW_BACKEND_URL/api/v1/admin/plugins/abc123/create-version \
  -H "Authorization: Bearer $AWEECLAW_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.0.0", "manifest": { } }'

后端上传时自动：提取校验包内 manifest.json（id 与 version 必须匹配）→ 计算 SHA256 → 上传对象存储 → 创建版本记录。

版本管理

递增 manifest.json 的 version（semver）
重新执行发布命令，脚本检测到插件已存在则只创建新版本

bash

node scripts/publish-plugin.mjs plugins/my-tool \
  --changelog "Added new tool: create_item"

规则与限制：

项	规则
版本号	必须 semver，且不能与已存在版本重复
`pluginKey`	发布后不可修改
`type`	创建后不可改，需删除重建
`price` / `validityDays`	走独立价格接口，便于单独校验与留痕
下架	软下架，保留历史版本与用户购买记录

发布 Checklist

开发阶段

[ ] manifest.id 匹配 ^[a-z][a-z0-9-]*$，且与目录名一致
[ ] manifest.version 为合法 semver
[ ] manifest.category 在后端分类表内
[ ] ConfigOnly 插件 main 为空字符串（不能省略）
[ ] in-process 插件导出工厂函数，返回 { server, clientTransport }，且不 import 外部 SDK
[ ] stdio 插件 package.json 声明了 @modelcontextprotocol/sdk 依赖
[ ] package.json 声明 "type": "module"
[ ] 必填配置项标记 required: true，密钥标记 secret: true
[ ] 本地图标放 icon/icon.png（≤ 256KB，建议 128×128）

UI 扩展（如有）

[ ] permissions 包含 ui.render
[ ] contributes.ui.entry 指向 ui.js
[ ] 执行 node scripts/build-ui.mjs <name> 生成 ui.js
[ ] 扩展点 component 键与 ui.js 导出映射一致

发布阶段

[ ] node --check index.js 通过
[ ] --skip-upload 预演打包成功
[ ] 版本号已递增
[ ] 发布后在客户端插件中心搜索并安装成功
[ ] 智能体可正常调用插件工具

下一步

后端 API 参考 — 完整接口清单与错误码
常见问题 — 发布报错排查

打包与发布 ​

两条发布路径 ​

分发模式如何判定 ​

打包细节 ​

前置准备 ​

脚本发布：单个插件 ​

常用选项 ​

仅打包（预演） ​

脚本发布：批量 ​

开发者中心发布 ​

权限要求 ​

手动发布（分步 API） ​

版本管理 ​

发布 Checklist ​

开发阶段 ​

UI 扩展（如有） ​

发布阶段 ​

下一步 ​

打包与发布

两条发布路径

分发模式如何判定

打包细节

前置准备

脚本发布：单个插件

常用选项

仅打包（预演）

脚本发布：批量

开发者中心发布

权限要求

手动发布（分步 API）

版本管理

发布 Checklist

开发阶段

UI 扩展（如有）

发布阶段

下一步