mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-10-31 12:45:41 +08:00
b129c4437a
- 部署文档、升级指南与 README 改为正式版说法：latest = 4.0，3.3 固定为 3.3.7 - docs/changelog/4.0.md 新增 4.0.0 汇总（升级前必读、破坏性变更、新功能、主要修复），链接改为绝对地址 - 文档站与插件市场改为从 main 发布，插件上架 PR 的目标分支改为 main - 文档站页脚版本 v4.0.0；en/ja README 的 star history 地址
104 lines
7.4 KiB
Markdown
104 lines
7.4 KiB
Markdown
# プラグインを掲載する
|
||
|
||
プラグインのソースは、作者自身の公開 GitHub リポジトリに置いたままにします。プラグインを掲載または更新するには、作者が `EstrellaXD/Auto_Bangumi`（ベースブランチ `main`）に PR を作ります。PR では 1 つのファイル `plugins/registry/<id>.toml` を追加または編集します。
|
||
|
||
CI はこのファイルが指すコードを検査します。メンテナーがコードを読んでマージします。マージ後、CI がプラグインをパックして署名し、署名付きカタログに公開します。
|
||
|
||
::: tip バージョン要件
|
||
AutoBangumi 4.0.0-beta.2 以降はプラグイン用の鍵を信頼します。4.0.0-beta.1 は新しいカタログからプラグインをインストールできません。
|
||
:::
|
||
|
||
## 登録ファイル
|
||
|
||
ファイル `plugins/registry/<id>.toml` のフィールドは 4 つです。
|
||
|
||
```toml
|
||
repo = "owner/name" # 公開 GitHub リポジトリ
|
||
commit = "<40 文字の完全な SHA>" # タグは動かせるが、SHA は動かせない
|
||
path = "." # 任意。プラグインのサブディレクトリ。既定はリポジトリのルート
|
||
sha256 = "<64 桁>" # PR チェックで作られる zip の sha256。最初は省略し、CI が示す値を書きます
|
||
```
|
||
|
||
- ファイル名は `plugin.toml` の `id` と一致させます。
|
||
- `commit` は 40 文字の完全な SHA にします。短い SHA やタグは拒否されます。
|
||
- 名前、バージョン、`sdk` の範囲、作者、権限は、その commit の `plugin.toml` から読み取ります。登録ファイルに重複して書かないでください。
|
||
- `sha256` は署名をレビュー済みのバイトに結び付けます。マージ後に作り直した zip がこれと完全に一致するときだけ、CI は署名します。最初の push では省略できます。CI がサマリーに値を示すので、追記して再度 push します。
|
||
|
||
1 つの PR で複数のエントリを変更できます。1 PR に 1 プラグインを推奨します。
|
||
|
||
## 手順
|
||
|
||
1. リポジトリを準備します。リポジトリは公開にします。`plugin.toml`、プラグインのコード、`tests/` をコミットします。フロントエンドがある場合は、ソースを `web-src/` に置き、`package.json` と `pnpm-lock.yaml` もコミットします。
|
||
2. ローカルで確認します。
|
||
|
||
```bash
|
||
ab-plugin validate .
|
||
uv run pytest
|
||
pnpm install --frozen-lockfile && pnpm build # フロントエンドがある場合のみ
|
||
```
|
||
|
||
`tests/` には少なくとも 1 つのテストが必要で、すべて合格しなければなりません。`ab-plugin new` が生成する契約テストはこの条件を満たします。
|
||
3. コードを公開リポジトリに push します。
|
||
4. 完全な SHA を取得します。
|
||
|
||
```bash
|
||
git rev-parse HEAD
|
||
```
|
||
|
||
5. `EstrellaXD/Auto_Bangumi` を fork し、`plugins/registry/<id>.toml` を追加して、`main` に PR を作ります。変更するのは `plugins/registry/` 以下のファイルだけです。PR の説明ではプラグイン用テンプレート（`?template=plugin.md`）を使い、各項目にチェックを入れます。
|
||
|
||
## CI のルール
|
||
|
||
ワークフロー `plugin-registry.yml` のジョブ `check` が PR 上で実行されます。権限は読み取り専用で、secret はありません。変更された各エントリについて、まず固定された commit を取得します。次に下のルールを検査します。1 つでも満たさないと、CI はそのエントリを拒否します。
|
||
|
||
- `commit` が 40 文字の完全な SHA ではない。
|
||
- ファイル名がマニフェストの `id` と異なる。
|
||
- `id` が組み込みプラグインと衝突する、または予約 id である。
|
||
- `ab-plugin validate` が失敗する。
|
||
- 更新で、バージョンがカタログにあるバージョンより高くない。
|
||
- 更新で、`repo` が変更されている。プラグインを移管するには、下の「プラグインを移管する」を参照してください。
|
||
- `tests/` にテストがない、またはテストが失敗する。
|
||
- プラグインにフロントエンドがあるのに、`web-src/` がない。フロントエンドは、ソースを `web-src/` にコミットし、`package.json` と `pnpm-lock.yaml` を付けます。CI は pnpm 9 / Node 20 で `pnpm install --frozen-lockfile --ignore-scripts && pnpm build` を実行します。`@autobangumi/plugin-ui` はこのリポジトリのパッケージに解決します。コミット済みの `web/` は破棄します。
|
||
|
||
検査に通ると、CI は `ab-plugin pack` でパックし、次の内容を Job Summary に書き込みます。
|
||
|
||
- バージョンの変化。
|
||
- 比較リンク（更新）またはツリーリンク（新規）。
|
||
- validate とテストの結果。
|
||
- 拡張ポイント。
|
||
- 宣言された権限。
|
||
- フロントエンドの有無。
|
||
- zip の sha256。
|
||
|
||
## マージ後
|
||
|
||
メンテナー（CODEOWNERS：@EstrellaXD）が比較リンクでコードを読み、マージします。
|
||
|
||
マージ後、CI はカタログを増分で再構築します。`commit` が変わっていないエントリは、既存の zip を再利用します。次に、専用のプラグイン署名鍵で `catalog.json` とすべての zip に署名します。この鍵は更新用の鍵ではありません。最後に、CI がファイルを GitHub release `plugins` にアップロードします。
|
||
|
||
ユーザーは `GET /api/v1/plugins/catalog` で新しいプラグインやバージョンを確認できます。カタログの形式と署名は [署名と配布](/ja/dev/plugins/signing) を参照してください。
|
||
|
||
## プラグインを更新する
|
||
|
||
1. 自分のリポジトリでコードを変更し、`plugin.toml` の `version` を上げます。
|
||
2. push して、`git rev-parse HEAD` で新しい完全な SHA を取得します。
|
||
3. `main` に PR を作ります。`plugins/registry/<id>.toml` の `commit` を新しい SHA に変更し、CI サマリーの値で `sha256` を更新します。
|
||
|
||
バージョンはカタログにあるバージョンより高くする必要があります。そうでない場合、CI は PR を拒否します。
|
||
|
||
## プラグインを移管する
|
||
|
||
更新では `repo` を変更できません。プラグインを別のリポジトリに移すには、2 つの PR を使います。
|
||
|
||
1. 1 つ目の PR で `plugins/registry/<id>.toml` を削除します。
|
||
2. マージ後、2 つ目の PR で新しい `repo` を指定して、このファイルを再び追加します。このとき CI は新規プラグインとして検査するため、古いバージョンの制限は受けません。
|
||
|
||
## プラグインを削除する
|
||
|
||
`plugins/registry/<id>.toml` を削除する PR を作ります。マージ後、そのプラグインはカタログから外れます。ユーザーが既にインストールしたコピーは削除されません。
|
||
|
||
## 依存関係と再配布
|
||
|
||
- プラグインが依存できるのは、標準ライブラリと AutoBangumi に既にあるパッケージだけです。サードパーティの純 Python ライブラリは `vendor/` に入れてください。
|
||
- ライセンスは必須ではありません。ただし、PR を作ることで、作者は AutoBangumi がパック済みのプラグインを release で再配布することに同意したものとみなされます。
|