Auto_Bangumi/docs/en/dev/plugins.md

Plugin Development

::: warning Preview SDK The plugin SDK ab_sdk has a 0.x version during 4.0. Incompatible changes can occur. From 4.1 the SDK is frozen at 1.0 and follows semantic versioning. The sdk field in the manifest gives the version range your plugin needs. AB refuses to load an incompatible plugin. :::

A plugin is a Python package, with optional frontend components. It runs inside the AutoBangumi process. A plugin can add downloaders, notification channels, search sites and rename methods. It can also add hooks to the pipeline, subscribe to events, and provide REST routes, MCP tools and settings-page UI.

Five-minute start

1. Install the SDK and the command line. The wheel is an attachment of each 4.0 beta and stable release on GitHub Releases. The file name is autobangumi_sdk-<SDK version>-py3-none-any.whl. The wheel is not on PyPI. Refer to Get the SDK.

   uv tool install ./autobangumi_sdk-0.6.0-py3-none-any.whl
   

2. Create a skeleton and run its tests. The pyproject.toml of the skeleton needs autobangumi-sdk. This package is not on PyPI. Thus, first use uv add to point the dependency to the wheel that you downloaded:

   ab-plugin new my-rename --kind rename   # or notifier, search
   cd my-rename
   uv add ../autobangumi_sdk-0.6.0-py3-none-any.whl   # use the real path of the wheel
   uv run pytest                                      # the skeleton includes a contract test
   

3. Link the plugin to your local AutoBangumi and enable hot reload. Start AB one time first, so that a config file exists in its config directory. Set --config-dir to this directory (backend/src/config when you run AB from source):

   ab-plugin dev . --config-dir /path/to/autobangumi/config
   

   Restart AB one time. After that, AB reloads the plugin when you change its files.

4. Pack the plugin: ab-plugin pack . creates dist/my-rename-0.1.0.zip.

Documentation map

Basics

• Get the SDK: the wheel and the plugin-author skill on the GitHub release

• Concepts: Plugin, ctx, the three extension declarations, the manifest, isolation and the circuit breaker

• Config forms: how config_model becomes a WebUI form

• Events: system events, organize events and custom events

• Frontend slots: Web Components and AbHost

• The ab-plugin command: new, validate, pack, dev

• Signing and distribution: local plugins, the signed catalog, the release flow

• Built-in plugins: rename, hardlink, ingest-filters, media-server-refresh

• Example plugins

Extension points

Extension point	Type	Purpose
Downloader downloader	Provider	A new downloader backend
Notifier notifier	Provider	A new notification channel
LLM provider llm_provider	Provider	A new LLM parsing provider
Search site search_site	Provider	A site in the search box
Scheduled task scheduled_task	Provider	A periodic task
Metadata provider metadata_provider	Provider	The "parser" of an RSS subscription
Rename strategy rename_strategy	Provider	The rule that makes file names
Media files media_files	Provider	Classify torrent files as media, subtitle or ignore
Conflict policy conflict_policy	Provider	A new torrent version and an old torrent want the same file name
REST routes api_router	Provider	HTTP endpoints of the plugin
MCP tools and resources mcp_tool mcp_resource	Provider	Items for MCP clients
Torrent filter torrent.filter	filter hook	Decide if a torrent is downloaded
Parsed title title.parsed	transform hook	Correct the title parse result
Adding request torrent.adding	transform hook	Change save path, category and tags
HTTP request http.request	transform hook	Add a Cookie to the GET requests of AB
Message template message_template	transform hook	Rewrite push messages

A plugin can also subscribe to events (@subscribe) and use a private key-value store and a data directory.