# プラグイン

4.0 から、AB の多くの機能はプラグインが提供します：リネーム方式、ダウンローダー、通知チャネル、トレントのフィルター、整理後の処理などです。プラグインは WebUI に独自の画面を追加することもできます。このページではプラグインの使い方を説明します。プラグインの作り方は [プラグイン開発](/ja/dev/plugins) を参照してください。

## 内蔵プラグイン

次のプラグインは AB に同梱されており、インストールは不要です：

| プラグイン id | 既定 | 機能 |
| --- | --- | --- |
| `rename` | 有効 | リネーム方式 `pn`、`advance`、`template` を提供します。[ファイルリネーム](./rename.md)を参照 |
| `ingest-filters` | 有効 | グローバルな「包含フィルター」：名前がいずれかの式に一致するトレントだけをダウンロードします。空欄ならフィルターしません |
| `media-server-refresh` | 有効 | 整理が終わると Jellyfin、Emby、Plex にライブラリの更新を要求します。アドレスまたは API Key が空なら何もしません |
| `hardlink` | 無効 | 整理済みのファイルをメディアライブラリフォルダにリンクします。[メディアライブラリへのハードリンク](./hardlink.md)を参照 |

qBittorrent・aria2 のダウンローダーと各通知チャネルは AB 自体が提供します。無効にはできず、プラグイン一覧にも表示されません。

## プラグイン設定ページ

**設定 → プラグイン** を開きます。各プラグインはカードで表示されます：

- **名前、id、バージョン**。
- **有効** スイッチ。
- **状態**：「実行中」「無効」「エラー」のいずれか。
- **ソース**：「内蔵」「ローカル」「pip」のいずれか。署名のないプラグインには「未署名」の表示も付きます。
- **エラー理由**：プラグインの読み込みに失敗したとき、または自動的に無効化されたときに表示されます。
- **宣言された権限**：プラグインがマニフェストで宣言した権限（例：`fs.write`、`network`）。これは情報のみで、AB はこれによってプラグインを制限しません。
- **設定**：展開するとプラグインの設定フォームが表示されます。

プラグインカードでの変更は、設定ページ下部の全体保存には含まれません。スイッチと **設定を保存** ボタンはすぐに `config.json` に書き込まれ、すぐに反映されます。再起動は不要です。

### プラグインを設定する

![プラグイン設定フォーム](/image/en/feature/plugin-config.png)

1. プラグインカードの **設定** を展開します。
2. フォームに入力します。リスト形式の項目は **行を追加** と **削除** で編集します。
3. **設定を保存** をクリックします。

AB は保存前に設定を検証します。不正な場合は保存されず、元の設定が残ります。内蔵プラグインと署名済みプラグインは、有効にする前に設定を入力できます。必須項目のあるプラグイン（例：`hardlink`）は、先に設定を入力して保存してから有効にしてください。

フォームで編集できない項目には「このフィールドはまだ画面で編集できません」と表示されます。`config.json` の `plugins.options.<プラグイン id>` を直接編集してください。

### プラグインのエラー

プラグインのコードが 5 回連続でエラーまたはタイムアウトになると、AB はそのプラグインを無効にします。カードの状態は「エラー」になり、理由が表示されます。AB のほかの部分は通常どおり動作します。例えば `rename` プラグインが無効化されると、すべての番組が `none` として扱われます。

原因を直した後（例：設定を変更して保存する）、または AB を再起動すると、プラグインが再び読み込まれます。

## ソースと信頼

プラグインは AB のプロセス内で、AB と同じ権限で動作します。AB はソースによってプラグインを信頼するかどうかを決めます：

| ソース | 場所 | 署名 | 有効にする方法 |
| --- | --- | --- | --- |
| 内蔵 | AB に同梱 | AB と一緒にリリース | 既定で使用可能 |
| 署名済みカタログ | `config/plugins/<id>/<バージョン>/` | AB が ed25519 署名を検証 | インストールすると有効になります |
| ローカル | `config/plugins/local/<id>/` | なし | 「未署名プラグインを許可」をオンにしてから有効にする |
| pip | entry point `autobangumi.plugins` を持つ Python パッケージ | なし | 同上 |

同じ id が複数のソースにある場合は、内蔵 > 署名済みカタログ > ローカル > pip の順で 1 つが選ばれます。

### 未署名プラグイン

ローカルフォルダと pip のプラグインには署名がありません。**設定 → プラグイン** で **未署名プラグインを許可** をオンにするまで、AB はこれらのプラグインのコードを一切実行せず、設定フォームも表示されません。

::: warning
信頼できるプラグインだけを有効にしてください。未署名プラグインは、AB がアクセスできるすべてのファイルとネットワークを使えます。
:::

ローカルプラグインのインストール：

1. プラグインのフォルダを `config/plugins/local/` にコピーします。フォルダ名はプラグイン id と同じにします。
2. AB を再起動します。
3. **設定 → プラグイン** で **未署名プラグインを許可** をオンにしてから、そのプラグインを有効にします。

### 署名済みカタログ

AB は GitHub release `plugins` から署名済みプラグインカタログを読み込みます。インストールの前に、カタログとプラグインパッケージの署名と sha256 を検証し、署名のないパッケージや署名が不正なパッケージを拒否します。カタログからインストールしたプラグインは署名済みとして扱われ、「未署名プラグインを許可」は不要です。

| リクエスト | 説明 |
| --- | --- |
| `GET /api/v1/plugins/catalog` | カタログのプラグインと、インストール済みのバージョンを返します |
| `POST /api/v1/plugins/{id}/install` | プラグインをインストールまたは更新し、有効にします |
| `DELETE /api/v1/plugins/{id}` | カタログからインストールしたプラグインを削除します。ローカルプラグインには影響しません |

**Plugin market**（插件市场）ページで、カタログを閲覧し、プラグインをインストール・更新・削除できます。**設定 → プラグイン** の「Open plugin market」からこのページを開きます。署名と公開の手順は [署名と配布](/ja/dev/plugins/signing) を参照してください。

![プラグインマーケット](/image/en/feature/plugin-market.png)

## プラグインの画面

プラグインは WebUI の次の場所に独自の画面を追加できます。画面が表示されるのは実行中のプラグインだけです。

| 場所 | 表示される内容 |
| --- | --- |
| 設定ページ | セクション一覧の末尾にプラグインのセクションが追加されます。サイドバーと検索で見つけられます。例：`hardlink` の「Hardlink backfill」 |
| 番組の編集モーダル | モーダル上部にタブが表示されます。「規則」は元の編集フォームで、他のタブはプラグインが提供します |
| 番組カード | カードのタイトル下の操作バー |
| 番組一覧ページ | ページ上部のウィジェットのグリッド |
| サイドバー | パズルのアイコンの項目が「設定」の前に追加され、`/plugins/<プラグイン id>` を開きます |

スマートフォンの下部ナビゲーションにはプラグインページの入口がありません。スマートフォンではアドレスを直接開いてください。

プラグインの画面でエラーが起きると、そのプラグインのすべての画面に「プラグインコンポーネントの読み込みに失敗しました」と表示されます。他のプラグインとページには影響しません。ページを開き直すと、プラグインの画面が再び読み込まれます。

## イベントと自動化

プラグインは AB のイベント（例：「整理完了」「ダウンローダー接続エラー」）を購読できます。独自の REST エンドポイント（`/api/v1/plugins/<プラグイン id>/…`）と MCP ツールを提供することもできます。[プラグイン開発](/ja/dev/plugins) を参照してください。