构建与发布

AutumnBox

# 构建与发布

# 构建插件

在插件项目根目录执行：

pnpm run build

构建完成后，你会在项目根目录看到一个 .atmb 文件，这就是你的插件包。

my-plugin/
├── src/...
├── package.json
└── myplugins-hello-world.atmb    ← 构建产物

.atmb 文件是插件的唯一交付物。它包含了插件运行所需的一切——代码、资源、语言文件、元数据。

# 本地测试

将 .atmb 文件复制到秋之盒的 builtin-plugins/ 目录，然后刷新页面：

cp *.atmb /path/to/AutumnBoxRevive/packages/app/builtin-plugins/

如果使用 AutumnBoxReviveWorkingSpace，可以直接用 Makefile：

make plugins    # 构建所有插件并自动复制到 builtin-plugins/
make dev        # 启动开发服务器

# 发布插件

# 通过 CLI 发布到插件商店

autumnbox-sdk 内置 publish 命令，可将 .atmb 直接上传到插件商店：

npx autumnbox-sdk publish --file my-plugin.atmb --token <your-publish-token>

# 认证方式（优先级从高到低）

方式	示例
`--token` 参数	`--token abcd1234`
`--token-file` 参数	`--token-file ~/.atmb-token`
`ATMB_TOKEN` 环境变量	`export ATMB_TOKEN=abcd1234`

发布 Token 在开发者中心生成。

# 完整选项

autumnbox-sdk publish [options]

必选:
  --file, -f <path>        要上传的 .atmb 文件路径
  --token, -t <token>      发布 Token（或通过 --token-file / ATMB_TOKEN 提供）

可选:
  --token-file <path>      从文件读取 Token
  --endpoint <url>         覆盖 API 端点
                            （默认: https://api.atmb.top/api/v1/plugins/publish
                             或环境变量 $ATMB_PUBLISH_ENDPOINT）
  --changelog <text>       本次版本的更新说明
  --dry-run                仅打印信息，不上传
  --help, -h               显示帮助

# 退出码

退出码	含义
0	发布成功（新建或更新）
1	通用错误
2	插件 ID 已被其他开发者占用
3	该版本号已存在
4	认证失败（Token 无效或过期）

# 工作流程

构建 .atmb → autumnbox-sdk publish → 自动创建/更新插件记录

端点原子处理"创建"和"更新"：新 pluginPackageName 创建插件记录，已有且属于你的 pluginPackageName 创建新版本，属于他人的 pluginPackageName 被拒绝。

# 示例

# 基本发布
npx autumnbox-sdk publish -f my-plugin.atmb -t mytoken123

# 带 changelog
npx autumnbox-sdk publish -f my-plugin.atmb -t mytoken123 --changelog "修复了文件管理器的排序问题"

# 从环境变量读取 Token
export ATMB_TOKEN=mytoken123
npx autumnbox-sdk publish -f my-plugin.atmb

# 从文件读取 Token
echo "mytoken123" > ~/.atmb-token
npx autumnbox-sdk publish -f my-plugin.atmb --token-file ~/.atmb-token

# 预览（不上传）
npx autumnbox-sdk publish -f my-plugin.atmb --dry-run

# 手动分发

.atmb 文件可以通过任何方式分发——网盘、GitHub Releases、聊天工具等。用户收到 .atmb 文件后，在秋之盒中通过插件管理器导入即可。

# 检查 .atmb 内容

.atmb 本质上是一个 ZIP 压缩包，可以用任何解压工具查看内容：

unzip -l my-plugin.atmb

  Length      Date    Time    Name
---------  ---------- -----   ----
     2048  2026-04-04 10:00   package.json
   524288  2026-04-04 10:00   index.js
      128  2026-04-04 10:00   resources/lang/zh-CN.json
      102  2026-04-04 10:00   resources/lang/en-US.json

# 版本管理

插件版本由 package.json 的 version 字段决定：

{
  "name": "@myplugins/hello-world",
  "version": "1.2.0"
}

发布新版本时，更新 version，重新 pnpm run build，上传新的 .atmb 即可。

# 常见问题

Q: 插件加载后白屏或报错

打开浏览器控制台（F12），查看错误信息。常见原因：

导出名称不符合约定（*App、*Card、*Service）
组件运行时错误

Q: 如何更新已安装的插件？

重新导入新版本的 .atmb 文件，会自动覆盖旧版本。

Q: 插件在开发时正常，构建后不工作

检查是否有 import 路径问题。构建时 @autumnbox/sdk/* 会被重写为宿主模块，确保没有直接 import @autumnbox/core 等内部包。