プラグインを掲載する

プラグインのソースは、作者自身の公開 GitHub リポジトリに置いたままにします。プラグインを掲載または更新するには、作者が EstrellaXD/Auto_Bangumi（ベースブランチ 4.0-dev）に PR を作ります。PR では 1 つのファイル plugins/registry/<id>.toml を追加または編集します。

CI はこのファイルが指すコードを検査します。メンテナーがコードを読んでマージします。マージ後、CI がプラグインをパックして署名し、署名付きカタログに公開します。

バージョン要件

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 プラグインを推奨します。

手順

リポジトリを準備します。リポジトリは公開にします。plugin.toml、プラグインのコード、tests/ をコミットします。フロントエンドがある場合は、ソースを web-src/ に置き、package.json と pnpm-lock.yaml もコミットします。
ローカルで確認します。
bash
```
ab-plugin validate .
uv run pytest
pnpm install --frozen-lockfile && pnpm build   # フロントエンドがある場合のみ
```
tests/ には少なくとも 1 つのテストが必要で、すべて合格しなければなりません。ab-plugin new が生成する契約テストはこの条件を満たします。
コードを公開リポジトリに push します。
完全な SHA を取得します。
bash
```
git rev-parse HEAD
```
EstrellaXD/Auto_Bangumi を fork し、plugins/registry/<id>.toml を追加して、4.0-dev に 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 で新しいプラグインやバージョンを確認できます。カタログの形式と署名は署名と配布を参照してください。

プラグインを更新する

自分のリポジトリでコードを変更し、plugin.toml の version を上げます。
push して、git rev-parse HEAD で新しい完全な SHA を取得します。
4.0-dev に PR を作ります。plugins/registry/<id>.toml の commit を新しい SHA に変更し、CI サマリーの値で sha256 を更新します。

バージョンはカタログにあるバージョンより高くする必要があります。そうでない場合、CI は PR を拒否します。

プラグインを移管する

更新では repo を変更できません。プラグインを別のリポジトリに移すには、2 つの PR を使います。

1 つ目の PR で plugins/registry/<id>.toml を削除します。
マージ後、2 つ目の PR で新しい repo を指定して、このファイルを再び追加します。このとき CI は新規プラグインとして検査するため、古いバージョンの制限は受けません。

プラグインを削除する

plugins/registry/<id>.toml を削除する PR を作ります。マージ後、そのプラグインはカタログから外れます。ユーザーが既にインストールしたコピーは削除されません。

依存関係と再配布

プラグインが依存できるのは、標準ライブラリと AutoBangumi に既にあるパッケージだけです。サードパーティの純 Python ライブラリは vendor/ に入れてください。
ライセンスは必須ではありません。ただし、PR を作ることで、作者は AutoBangumi がパック済みのプラグインを release で再配布することに同意したものとみなされます。

プラグインを掲載する ​

登録ファイル ​

手順 ​

CI のルール ​

マージ後 ​

プラグインを更新する ​

プラグインを移管する ​

プラグインを削除する ​

依存関係と再配布 ​