上传插件到官方插件源

AstroBox V2 官方插件源位于一个 GitHub 仓库：AstralSightStudios/AstroBox-NG-Plugin-Repo。它的根目录只有一份 index.txt，每一行是一个作者仓库的 raw 基地址。仓库里的 GitHub Action 每 4 小时会自动抓取所有作者仓库的 manifest.json，汇总生成 index.json——这就是 AstroBox 客户端插件市场读取的数据源。

所以把插件送上货架，本质是三步：

1. 本地构建 —— 产出 manifest.json + <entry>.wasm + icon.png + additional_files 到一个约定的文件夹（比如 dist/）。
2. 发到你自己的 GitHub 仓库 —— 仓库根目录必须多一份 index.txt，里面写上你放构建产物的文件夹名。
3. 向 Plugin-Repo 提 PR —— 把你仓库的 raw 基地址追加一行到 index.txt。

下面按顺序走一遍。

Step 1 · 本地构建

情形 A：基于官方 Rust 模板的插件

模板：AstroBox-NG-Plugin-Template-Rust，模板里预置了 scripts/build_dist.py，构建产物固定输出到 dist/ 文件夹。

先确认环境齐了（详见 Rust 上手教程）：Rust、Python 3、rustup target add wasm32-wasip2。

然后：

# Debug 构建到 dist 文件夹
python scripts/build_dist.py

# Release 构建到 dist 文件夹（正式上架用这个）
python scripts/build_dist.py --release

# 顺便打一个 .abp 包，方便别人本地导入
python scripts/build_dist.py --release --package

构建完成后，dist/ 里应该长这样：

dist/
├── manifest.json          # 从项目根 manifest.json 拷贝而来
├── <你的插件>.wasm         # entry 字段指向的 wasm 产物
├── icon.png               # icon 字段指向的图标
├── ...                    # additional_files 里列出的所有附加文件
└── <插件名>.abp            # 仅在 --package 时生成，非必需

情形 B：不基于模板的插件（自建 / 其它语言 / JS）

如果你没使用官方模板（比如自己写 CMake、走 JS 手搓、fork 老项目），那么 dist/ 目录里的这四类文件全部要你自己保证放齐：

放这些文件的目录不一定叫 dist/——现存插件里有用 dist/、release/、rel/ 的，任你选。这个目录名会在 Step 2 的 index.txt 里被你自己记录。

Step 2 · 创建并上传你的插件仓库

在自己的 GitHub 账号下新建一个仓库（名字随意，建议是插件相关的英文名），把整个项目推上去。目标形态是这样：

your-plugin-repo/
├── index.txt              # ← 关键！根目录必须有
├── dist/                  # 或 release/ / rel/ / 你自己起的名字
│   ├── manifest.json
│   ├── xxx.wasm
│   ├── icon.png
│   └── ...
├── src/ ...               # 源码可放可不放，官方仓库不读
└── README.md              # 建议有

index.txt 怎么写

根目录 index.txt 每一行是一个「装着 manifest.json 的文件夹的相对路径」。绝大多数插件只需要一行：

dist

如果你把构建产物放在 release/，那就写：

release

把仓库推上 GitHub

git init
git add .
git commit -m "chore: initial plugin release"
git branch -M main            # 或 master，都可以
git remote add origin https://github.com/<你的用户名>/<你的仓库>.git
git push -u origin main

推完确认在 GitHub 网页上能打开 dist/manifest.json 的 raw 视图，说明文件都到位了。

Step 3 · 向 Plugin-Repo 提交 Pull Request

3.1 拿到你要追加到 index.txt 的那一行

Plugin-Repo 里 index.txt 每一行都是这个格式：

https://raw.githubusercontent.com/<owner>/<repo>/refs/heads/<branch>/

推荐用 refs/heads/<branch>/ 这种带引用前缀的写法——聚合脚本对它零加工原样使用，行为最稳定。

怎么快速拿到这条链接？打开你仓库中构建产物所在文件夹里的 manifest.json，点右上角的 Raw 按钮，浏览器地址栏里会出现：

https://raw.githubusercontent.com/<owner>/<repo>/refs/heads/<branch>/dist/manifest.json

把 dist/manifest.json 这一段去掉，只保留到 refs/heads/<branch>/ 结尾的斜杠，就是你要追加的那一行。示例：

❌ 原始 raw URL:
   https://raw.githubusercontent.com/octocat/my-plugin/refs/heads/main/dist/manifest.json

✅ 要写进 index.txt 的：
   https://raw.githubusercontent.com/octocat/my-plugin/refs/heads/main/

3.2 提交 PR

1. 打开 AstralSightStudios/AstroBox-NG-Plugin-Repo，点右上角 Fork，把仓库 fork 到你自己账号下。
2. 在你 fork 的仓库里编辑 index.txt，在最末尾追加一行——你在 3.1 拿到的那个 https://raw.githubusercontent.com/…/refs/heads/…/ 链接。注意保留末尾的斜杠。
3. Commit 一下，然后点 Contribute → Open pull request，把改动向上游 AstralSightStudios/AstroBox-NG-Plugin-Repo 的 main 分支提。
4. PR 标题写清楚是提交哪个插件（例如 Add MyPlugin），描述里附上：
   • 插件名和一句话简介
   • 支持的 API Level 与 WASI Version
   • 用到的权限清单（和 manifest.json 一致）
   • 已知问题或测试情况（可选）

3.3 等待审核合入

审核通过、PR 被合入之后：

• Plugin-Repo 的 Generate Plugin Market Index Action 会在下一次 push 或 4 小时定时中触发。
• Action 会读你 index.txt 每行的 <raw>/index.txt → 找到 dist 文件夹 → 拉 manifest.json → 追加到 index.json。
• AstroBox 客户端读取 index.json，你的插件就会出现在插件市场里。

如果 4 小时以上仍未生效，去 Actions 页面 看最近一次 generate-index 的日志，搜自己仓库的 URL，一般能定位到问题（大多数是 index.txt 路径写错、manifest.json 字段类型不对、或者分支名和 URL 里的对不上）。

常见坑位速查

有其它疑问，欢迎到 创作者社群 里问一声，或直接在 PR 下留言。