[4.0] — Beta

4.0 is a large release that adds plugins. Download, notification, parsing, search, rename, and file organization all use one set of extension points. Built-in features and third-party plugins use the same interfaces. You can have more than one downloader instance. Built-in plugins supply rename, hard links, torrent filters, and media server refresh. You can upgrade only from 3.3.x. At the first start, AB migrates the configuration and keeps a backup of the original file.

For the upgrade procedure, the rollback procedure, and the checks after the upgrade, refer to Upgrade from 3.3 to 4.0.

4.0.0-beta.3

Breaking changes

• MCP uses Streamable HTTP at /mcp. The old /mcp/sse endpoint is removed. Update the address in your MCP client.
• API calls with a JSON body must send Content-Type: application/json. Other requests get 422.
• Unknown /api/… paths return 404. They do not return the WebUI page.
• Plugin SDK (ab_sdk) 0.6.0: AdapterContext.build_http_client returns an httpx2.AsyncClient. Plugins that only call get / post need no change. Plugins that use httpx-specific APIs must be updated.
• Runtime: Python 3.14.

4.0.0-beta.1

Docker image: ghcr.io/estrellaxd/auto_bangumi:4.0.0-beta.1. dev-latest also points to the most recent beta.

Breaking changes

• Upgrade only from 3.3.x. AB does not start if it finds data from an older version: a version below 3.3 in config/version.info, or a 2.x data/data.json file. The log tells you to upgrade to the latest 3.3.x and start it once.
• New configuration structure, with automatic migration. Downloaders are now instances in plugins.instances. plugins.slots.downloader points to the default instance. The rename method and the revision conflict policy moved to plugins.slots.rename_strategy and plugins.slots.conflict_policy. At the first start, AB migrates the 3.3 fields downloader, bangumi_manage.rename_method, and bangumi_manage.revision_conflict_policy. AB keeps the original file as config.json.v3.bak. If that backup exists, AB writes config.json.v3.bak.1 and so on, and does not overwrite it. If the migration fails, config.json does not change, AB does not start, and the log shows the field that caused the failure. The environment variables AB_DOWNLOADER_*, AB_DOWNLOAD_PATH, AB_METHOD, and AB_REVISION_CONFLICT_POLICY continue to work.
• Old notification fields. Bark no longer reads token (use device_key). WeCom no longer reads chat_id (use webhook_url). The upgrade migrates them.
• Removed old API. The 3.2-compatible GET control endpoints (/api/v1/restart, /start, /stop, /shutdown) and GET /api/v1/auth/refresh_token are removed. Use POST.
• Removed old configuration. The experimental_openai section and the old single-channel notification fields are removed. 3.3 already moved them to llm and notification.providers. The deprecated normal rename method is removed. AB changes it to none, which has the same behavior.
• AB upgrades the database to schema v26. It adds a plugin storage table and downloader_id columns.

Plugin system

• New plugin runtime. Plugins can come from the built-in directory, the signed plugin catalog, a local directory (config/plugins/local/), or a pip package. Local and pip plugins do not have a signature. AB loads them only when you turn on Settings → Plugins → Allow unsigned plugins (plugins.allow_unsigned).
• Plugins can supply downloaders, notification channels, LLM parser providers, search sites, metadata sources, and scheduled tasks. The built-in qBittorrent and aria2 downloaders and the notification channels use the same extension points. The lists of downloader types, notification channels, and subscription parsers show the options that plugins supply.
• In the RSS download flow, plugins can filter torrents, correct parse results, change the save path, category, or tags, and add request headers (for example cookies for private sites).
• The settings page has a new "Plugins" card. Use it to see the status, enable and disable plugins, and edit plugin options in a generated form. Read APIs always mask secret fields.
• Signed plugin catalog: GET /api/v1/plugins/catalog lists the catalog. POST /api/v1/plugins/{id}/install verifies the sha256 and the ed25519 signature, then installs and enables the plugin. DELETE /api/v1/plugins/{id} uninstalls it.
• Plugin hook calls have a timeout. If one plugin fails 5 times in sequence, AB disables it. After you correct the problem, enable it again on the settings page.

More than one downloader

• In Settings → Downloader Setting, you can add more than one downloader instance (qBittorrent, aria2, or a downloader from a plugin) and set the default instance.
• Rules and RSS subscriptions can select a downloader. If you do not select one, AB uses the default instance. A rule that AB makes from a subscription uses the selection of the subscription.
• Each torrent records its downloader. AB renames and deletes the torrent on that downloader. If a rule changes to a different downloader, the existing torrents stay where they are.
• AB renames files on one downloader at a time. AB skips a downloader that it cannot connect to, and sends a notification the first time that the connection fails.
• The downloader page and the torrent list show the downloader of each torrent. GET /api/v1/downloader/torrents returns the torrents of all instances. The pause, resume, delete, and tag endpoints have a new downloader_id parameter. GET /api/v1/downloader/instances is new.

Rename and file organization

• Rename is now a plugin. The built-in plugin rename (enabled by default) supplies pn, advance, and template. AB itself supplies none. The output of pn and advance is the same as in 3.3. Subtitles use the same method as the video files.
• New template rename method: you write a template for the file name. For normal episodes the default template gives the same result as pn. For movies, pn adds no SxxExx, but the default template does. When you save the settings, AB renders the template as a test and does not save a template that is not valid. If the template fails for a file at run time, the file keeps its name and AB sends a "Files kept their names" notification. AB does not use pn as a fallback.
• New built-in plugin hardlink (disabled by default). After AB organizes a torrent, the plugin links the video and subtitle files into the media library directory. The download directory continues to seed. Set a path map (path_map) for each downloader instance. Across file systems, the plugin copies the files by default. It does not overwrite files that it did not make, and replaces its own links after a revision upgrade. If a copy stops before it is complete, no partial file stays in the library. To link files that already exist, use POST /api/v1/plugins/hardlink/backfill.
• New built-in plugin media-server-refresh. After you set the Jellyfin / Emby / Plex address and API key, it collects the torrents that AB organized during a short period and sends one library refresh request. If you do not configure it, it does nothing.
• New built-in plugin ingest-filters (enabled by default). If you set its include option, AB downloads only torrents whose name matches one of the expressions. This applies to all subscriptions. If the option is empty, the plugin does not filter.

Events, API, and MCP

• System events (RSS feed errors, failed torrent additions, downloader not available, new version, file renamed, torrent organized, and others) go to an event bus. Plugins can subscribe to them.
• Plugins can supply REST routes (under /api/v1/plugins/<plugin id>/, login required), MCP tools, and MCP resources. Plugins can change the title and body of a system notification for each event type and channel.
• Plugins can send notifications to the notification center.
• The notification center now receives events immediately when a message is added, read, or deleted. Before, it checked every 3 seconds.

Frontend plugins

• The WebUI has new plugin slots. A plugin can add its own interface (a Web Component) at a specified location. The built-in hardlink plugin uses a slot for its backfill button.
• New example plugin manual-pick, which shows how to use a frontend slot.

Plugin development tools

• The plugin SDK ab_sdk is available as the autobangumi-sdk wheel on each GitHub Release. It is not on PyPI.
• New ab-plugin command line: new makes a plugin skeleton with contract tests. validate checks the manifest and the SDK version range. pack makes an installable zip. dev links the plugin directory into config/plugins/local/ and turns on plugins.dev_mode. With dev_mode on, AB reloads a local plugin when its files change.
• ab_sdk.testing has contract test suites for downloaders, rename methods, notification channels, and search sites.
• 5 new example plugins in examples/plugins/: webhook-on-event, custom-rss-site, template-rename, nfo-writer, and ntfy-notifier. CI runs the tests of each one.
• New agent skill for plugin authors, on each GitHub Release as autobangumi-plugin-skill-<version>.zip.
• The plugin development documentation now has an overview, core concepts, and one page for each extension point, in Chinese, English, and Japanese. Refer to Plugin Development.

Fixes

• A new search site showed in the search site list only after a restart. It now shows immediately.
• After an MCP client closed its SSE connection, the log showed AssertionError: Unexpected message http.response.start. This problem existed since 3.x.
• When a plugin option validator failed, the save endpoint returned 500 instead of 422.
• version.info compared only the minor version, so it did not record an upgrade to a new major version (for example 3.3 to 4.0).
• 4.x writes its version to config/version_v4.info. When it starts on 3.3 data for the first time, it makes a backup of the database at data/data.db.v3.bak. A rollback to 3.3 no longer runs the 3.0 migration that creates the database again.

Cleanup

• Removed the 3.0 → 3.1 and 3.1 → 3.2 migrations, the old JWT and in-memory session code, and approximately 70 functions, methods, and models that nothing called. CI now checks for dead code.