mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-10-30 12:14:27 +08:00
ca7fcdf058
- 依赖 httpx[socks] 换为 httpx2[socks]>=2.15，移除 httpx-socks / python-socks 及其 mypy 覆盖 - backend/src、ab_sdk、e2e 与单元测试统一使用 httpx2（异常类与 httpx 不通用） - request_url 与 LLM 客户端工厂合并为 proxy_url()，SOCKS5 走 httpx2 原生代理（主机名由代理解析） - 保留 #1104 过期连接池替换：httpcore2 2.15.1 的 start_tls 失败路径仍会泄漏隧道 - 日志同时压低 httpx2 与 httpx（google-genai、mcp 仍依赖旧 httpx） - openai 3.35.1 / anthropic 1.15.0 / google-genai 2.31.0；结构化解析改用 chat.completions.parse - ab_sdk 升到 0.6.0，客户端类型改为 httpx2.AsyncClient，同步插件文档
72 lines
4.9 KiB
Markdown
72 lines
4.9 KiB
Markdown
# 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](https://github.com/EstrellaXD/Auto_Bangumi/releases). The file name is `autobangumi_sdk-<SDK version>-py3-none-any.whl`. The wheel is not on PyPI. Refer to [Get the SDK](/en/dev/plugins/sdk).
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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](/en/dev/plugins/sdk): the wheel and the plugin-author skill on the GitHub release
|
|
|
|
- [Concepts](/en/dev/plugins/concepts): `Plugin`, `ctx`, the three extension declarations, the manifest, isolation and the circuit breaker
|
|
- [Config forms](/en/dev/plugins/config-forms): how `config_model` becomes a WebUI form
|
|
- [Events](/en/dev/plugins/events): system events, organize events and custom events
|
|
- [Frontend slots](/en/dev/plugins/frontend-slots): Web Components and `AbHost`
|
|
- [The ab-plugin command](/en/dev/plugins/cli): `new`, `validate`, `pack`, `dev`
|
|
- [Signing and distribution](/en/dev/plugins/signing): local plugins, the signed catalog, the release flow
|
|
- [Built-in plugins](/en/dev/plugins/builtin): `rename`, `hardlink`, `ingest-filters`, `media-server-refresh`
|
|
- [Example plugins](/en/dev/plugins/examples)
|
|
|
|
**Extension points**
|
|
|
|
| Extension point | Type | Purpose |
|
|
| --- | --- | --- |
|
|
| [Downloader](/en/dev/plugins/points/downloader) `downloader` | Provider | A new downloader backend |
|
|
| [Notifier](/en/dev/plugins/points/notifier) `notifier` | Provider | A new notification channel |
|
|
| [LLM provider](/en/dev/plugins/points/llm-provider) `llm_provider` | Provider | A new LLM parsing provider |
|
|
| [Search site](/en/dev/plugins/points/search-site) `search_site` | Provider | A site in the search box |
|
|
| [Scheduled task](/en/dev/plugins/points/scheduled-task) `scheduled_task` | Provider | A periodic task |
|
|
| [Metadata provider](/en/dev/plugins/points/metadata-provider) `metadata_provider` | Provider | The "parser" of an RSS subscription |
|
|
| [Rename strategy](/en/dev/plugins/points/rename-strategy) `rename_strategy` | Provider | The rule that makes file names |
|
|
| [Media files](/en/dev/plugins/points/media-files) `media_files` | Provider | Classify torrent files as media, subtitle or ignore |
|
|
| [Conflict policy](/en/dev/plugins/points/conflict-policy) `conflict_policy` | Provider | A new torrent version and an old torrent want the same file name |
|
|
| [REST routes](/en/dev/plugins/points/api-router) `api_router` | Provider | HTTP endpoints of the plugin |
|
|
| [MCP tools and resources](/en/dev/plugins/points/mcp) `mcp_tool` `mcp_resource` | Provider | Items for MCP clients |
|
|
| [Torrent filter](/en/dev/plugins/points/torrent-filter) `torrent.filter` | filter hook | Decide if a torrent is downloaded |
|
|
| [Parsed title](/en/dev/plugins/points/title-parsed) `title.parsed` | transform hook | Correct the title parse result |
|
|
| [Adding request](/en/dev/plugins/points/torrent-adding) `torrent.adding` | transform hook | Change save path, category and tags |
|
|
| [HTTP request](/en/dev/plugins/points/http-request) `http.request` | transform hook | Add a Cookie to the GET requests of AB |
|
|
| [Message template](/en/dev/plugins/points/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.
|