mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-11-19 18:34:32 +08:00
- 新增 rename_strategy Provider 扩展点(ab_sdk.rename:RenameInput / RenameStrategy),内置 pn / advance / none 以 core 登记,输出与 3.3 的 gen_path 逐字一致(参数化对照测试);字幕改用 RenameInput.kind,不再有 subtitle_* 方法名;未知方式 / 策略出错 / 非法结果均保持原路径并记录错误 - 内置插件 rename-template:template 方式,Jinja2 沙箱模板(剧集 + 剧场版), 默认与 pn 相同;结果为空或含路径分隔符时保持原名,语法错误保存时拒绝 - 整理事件 ab_sdk.organize:file.renamed / torrent.organized,经 module.plugin.host.publish 发布到 PluginManager 登记的进程级总线 - 内置插件 media-server-refresh:订阅 file.renamed,合并后请求 Jellyfin / Emby / Plex 刷新媒体库;未配置时为空操作 - 清理:删除仅测试使用的 rename_file / _lookup_offsets(测试改为驱动 rename() 与 _batch_lookup_offsets)、冗余的 release_replacement_lease、 失去调用方的 match_by_save_path / search_by_qb_hash,以及重命名链路中 未使用的 season_offset 参数 - 修复插件配置接口:field_validator 抛出的错误返回 422 而不是 500 - WebUI 重命名方式下拉框加入 template 与插件提供的方式;ab_sdk 0.3.0; 插件开发文档与番剧管理文档(中 / 英 / 日) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EoBUPFw7Ty1epuPESdELs1
256 lines
11 KiB
Markdown
256 lines
11 KiB
Markdown
# 插件开发
|
||
|
||
::: warning 预览版 SDK
|
||
插件 SDK `ab_sdk` 在 4.0 期间为 0.x 版本,接口可能有不兼容调整;4.1 起冻结 1.0,之后遵守语义化版本。清单里的 `sdk` 字段声明你依赖的版本范围,AB 会拒绝加载不兼容的插件。
|
||
:::
|
||
|
||
插件是一个 Python 包,可以给 AutoBangumi 增加:
|
||
|
||
| 扩展点 | 常量 | 返回值 | 用户如何启用 |
|
||
| --- | --- | --- | --- |
|
||
| 下载器 | `points.DOWNLOADER` | `DownloaderFactory` | 设置 → 下载器 → 类型 |
|
||
| 通知渠道 | `points.NOTIFIER` | `NotifierFactory` | 设置 → 通知 → 添加渠道 |
|
||
| LLM 解析提供商 | `points.LLM_PROVIDER` | `LLMProviderAdapter` 子类 | 设置 → LLM → 提供商 |
|
||
| 搜索站点 | `points.SEARCH_SITE` | `SearchSite` | 搜索框的站点列表 |
|
||
| 定时任务 | `points.SCHEDULED_TASK` | `ScheduledTask` | 插件启用即生效 |
|
||
| 重命名方式 | `points.RENAME_STRATEGY` | `RenameStrategy` | 设置 → 番剧管理 → 重命名方式 |
|
||
|
||
此外,插件可以订阅事件(`@subscribe`,如文件重命名后的 `file.renamed`),并使用私有的键值存储和数据目录。RSS 过滤等流水线扩展点会在后续版本陆续开放。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
config/plugins/local/my-plugin/ # 目录名必须与清单中的 id 相同
|
||
├── plugin.toml
|
||
├── my_plugin.py # 也可以是包,插件内部可以用相对导入
|
||
└── vendor/ # 可选:纯 Python 依赖(禁止 .so/.pyd)
|
||
```
|
||
|
||
```toml
|
||
# plugin.toml
|
||
[plugin]
|
||
id = "my-plugin" # 小写字母、数字、连字符
|
||
name = "我的插件"
|
||
version = "0.1.0"
|
||
sdk = ">=0.2,<1" # 依赖的 ab_sdk 版本范围
|
||
entry = "my_plugin:MyPlugin" # 模块:Plugin 子类,相对插件目录
|
||
description = "一句话说明"
|
||
permissions = ["network"] # 仅用于向用户展示,不做强制
|
||
```
|
||
|
||
本地插件未经签名。要让 AB 加载它,需要在 **设置 → 插件** 中先打开「允许未签名插件」,再启用该插件。插件与 AB 在同一进程中运行,拥有完整权限。
|
||
|
||
## 第一个插件:Bark 风格的推送渠道
|
||
|
||
```python
|
||
from pydantic import BaseModel, Field
|
||
|
||
from ab_sdk import Plugin, points, provider, secret_field
|
||
from ab_sdk.notify import NotificationMessage, NotifierSettings
|
||
|
||
|
||
class Options(BaseModel):
|
||
endpoint: str = Field("https://push.example.com", title="推送地址")
|
||
key: str = secret_field(description="推送密钥")
|
||
|
||
|
||
class Pusher:
|
||
def __init__(self, plugin: "MyPlugin", settings: NotifierSettings) -> None:
|
||
self.plugin = plugin
|
||
self.settings = settings
|
||
|
||
async def send(self, message: NotificationMessage) -> bool:
|
||
import httpx
|
||
|
||
async with httpx.AsyncClient(timeout=10) as client:
|
||
resp = await client.post(
|
||
f"{self.plugin.config.endpoint}/{self.plugin.config.key}",
|
||
json={"title": message.title, "body": message.body},
|
||
)
|
||
return resp.is_success
|
||
|
||
async def test(self) -> tuple[bool, str]:
|
||
ok = await self.send(NotificationMessage(kind="event", title="AB", body="测试"))
|
||
return ok, "已发送" if ok else "发送失败"
|
||
|
||
|
||
class MyPlugin(Plugin[Options]):
|
||
config_model = Options
|
||
|
||
@provider(points.NOTIFIER, id="my-push")
|
||
def push(self):
|
||
return lambda settings: Pusher(self, settings)
|
||
```
|
||
|
||
启用插件后:
|
||
|
||
1. 设置 → 插件里会出现由 `Options` 自动生成的表单。`secret_field` 声明的字段以密码框显示,读取配置的接口只返回掩码。
|
||
2. 设置 → 通知 → 添加渠道时,类型下拉框会多出 `my-push`。
|
||
|
||
## 核心概念
|
||
|
||
### Plugin 与配置
|
||
|
||
- 继承 `Plugin[配置模型]` 并设置 `config_model`。AB 会按模型校验用户配置,插件通过 `self.config` 拿到带类型的实例。在 WebUI 保存不合法的值会被直接拒绝(HTTP 422)。
|
||
- `async setup()` 在加载后调用一次,`async teardown()` 在卸载前调用一次。配置变更时,插件会先 teardown,再重新构造并 setup。
|
||
- `self.ctx` 提供:
|
||
- `log`:带 `plugin.<id>` 前缀的 logger
|
||
- `kv`:插件私有的持久化键值存储,值须可 JSON 序列化
|
||
- `data_dir`:`config/plugin-data/<id>/`
|
||
- `bus`:事件总线
|
||
|
||
### 三种扩展声明
|
||
|
||
| 装饰器 | 用途 |
|
||
| --- | --- |
|
||
| `@provider(point, id=...)` | 工厂方法,返回该扩展点约定的实现 |
|
||
| `@hook(point, priority=...)` | 挂到宿主声明的 filter / transform 扩展点(后续版本开放) |
|
||
| `@subscribe(kind)` | 订阅事件,`"*"` 表示全部事件 |
|
||
|
||
扩展点名写错时,插件会加载失败并在插件列表里显示原因,不会被悄悄忽略。
|
||
|
||
### 隔离与熔断
|
||
|
||
- 钩子、事件处理和定时任务都有超时。
|
||
- 同一插件连续失败 5 次会被自动禁用,并在插件列表中显示原因。修改该插件的配置后会重新尝试加载。
|
||
- 插件发布的事件,`kind` 必须以 `<插件 id>.` 开头。
|
||
|
||
## 各扩展点
|
||
|
||
### 下载器
|
||
|
||
```python
|
||
from ab_sdk.downloader import AddResult, DownloaderCapabilities, DownloaderConnection
|
||
|
||
|
||
class MyClient:
|
||
capabilities = DownloaderCapabilities(
|
||
can_query=False, can_rename=False, can_manage=False, can_rss_rules=False
|
||
)
|
||
|
||
def __init__(self, conn: DownloaderConnection) -> None:
|
||
self.conn = conn # 来自设置页「下载器」的 host / username / password / ssl
|
||
|
||
async def auth(self, retry: int = 3) -> bool: ...
|
||
async def logout(self) -> None: ...
|
||
async def add_torrents(self, torrent_urls, torrent_files, save_path, category, tags=None) -> AddResult: ...
|
||
|
||
|
||
class MyPlugin(Plugin):
|
||
@provider(points.DOWNLOADER, id="my-client")
|
||
def client(self):
|
||
return MyClient
|
||
```
|
||
|
||
至少实现 `CoreDownloaderClient`(认证与添加种子)。需要重命名、整理等功能时,实现完整的 `DownloaderClient` 并在 `capabilities` 中声明,AB 会跳过未声明的操作。
|
||
|
||
### LLM 提供商
|
||
|
||
返回 `ab_sdk.llm.LLMProviderAdapter` 的子类,`@provider` 的 id 必须等于其 `info.id`。内置提供商的 id 不能被覆盖。
|
||
|
||
### 搜索站点
|
||
|
||
```python
|
||
from ab_sdk.search import SearchSite
|
||
|
||
@provider(points.SEARCH_SITE, id="my-site")
|
||
def site(self):
|
||
return SearchSite(url="https://example.com/rss?q=%s", parser="tmdb")
|
||
```
|
||
|
||
用户在搜索设置里配置的同名站点优先。
|
||
|
||
### 定时任务
|
||
|
||
```python
|
||
from ab_sdk.tasks import ScheduledTask
|
||
|
||
@provider(points.SCHEDULED_TASK, id="sync")
|
||
def sync(self):
|
||
async def run():
|
||
...
|
||
return ScheduledTask(run, interval=lambda: self.config.interval, initial_delay=60)
|
||
```
|
||
|
||
任务与 RSS 刷新等内置任务一同启停,失败计入熔断。
|
||
|
||
### 重命名方式
|
||
|
||
需要 `sdk = ">=0.3,<1"`。
|
||
|
||
```python
|
||
from ab_sdk import Plugin, points, provider
|
||
from ab_sdk.rename import RenameInput
|
||
|
||
|
||
class Kebab:
|
||
def target_name(self, f: RenameInput) -> str:
|
||
if f.episode_type == "movie":
|
||
return f"{f.bangumi_name}{f.full_suffix}"
|
||
return f"{f.bangumi_name}-s{f.season:02d}e{f.episode:02}{f.full_suffix}"
|
||
|
||
|
||
class MyPlugin(Plugin):
|
||
@provider(points.RENAME_STRATEGY, id="kebab")
|
||
def kebab(self):
|
||
return Kebab()
|
||
```
|
||
|
||
用户把 **设置 → 番剧管理 → 重命名方式** 设为 `kebab` 后,AB 对种子里的每个媒体文件和字幕文件各调用一次 `target_name`:
|
||
|
||
- `RenameInput` 字段:`title`(从文件名解析的标题)、`bangumi_name`(番剧文件夹名)、`season`、`episode`、`suffix`(含点的扩展名)、`kind`(`media` / `subtitle`)、`language`(字幕语言)、`episode_type`(`episode` / `movie` / `special`)、`original_path`(种子内当前路径)、`group`。
|
||
- 剧集偏移已经应用到 `episode`,季度取自番剧文件夹(同样已含季度偏移),策略只负责拼名字。半集(如 `12.5`)保留小数。
|
||
- 返回种子内的新相对路径,**包括扩展名**。字幕可以直接拼 `f.full_suffix`,它会生成 `.zh.ass` 这样的后缀。返回 `f.original_path` 表示不改名。
|
||
- 抛出异常、返回空字符串、绝对路径或含 `..` 的路径时,AB 记录错误并保持原文件名,不会中断整理流程。
|
||
- 内置的 `pn`、`advance`、`none` 以 `core` 身份登记,不能被覆盖。内置插件「模板重命名」提供 `template`,可以作为参考实现。
|
||
|
||
### 整理事件
|
||
|
||
AB 在重命名完成后向事件总线发布两个事件,定义在 `ab_sdk.organize`:
|
||
|
||
| 事件 | `kind` | 发布时机 |
|
||
| --- | --- | --- |
|
||
| `FileRenamed` | `file.renamed` | 下载器中的一个文件(媒体或字幕)被实际改名后;文件名已符合目标、无需改名时不发布 |
|
||
| `TorrentOrganized` | `torrent.organized` | 一个种子的媒体文件全部就位、字幕也处理完、打上 `ab:renamed` 标签时;重命名方式为 `none` 时不发布 |
|
||
|
||
```python
|
||
from ab_sdk import Plugin, subscribe
|
||
from ab_sdk.organize import FileRenamed
|
||
|
||
|
||
class MyPlugin(Plugin):
|
||
@subscribe(FileRenamed.kind)
|
||
async def on_renamed(self, event: FileRenamed) -> None:
|
||
self.ctx.log.info("%s → %s", event.old_path, event.new_path)
|
||
```
|
||
|
||
- `FileRenamed` 字段:`torrent_hash`、`bangumi_id`(未关联到番剧时为 `None`)、`official_title`、`season`、`episode`(已含偏移)、`old_path`、`new_path`、`save_path`、`file_kind`(`media` / `subtitle`)。
|
||
- `TorrentOrganized` 字段:`torrent_hash`、`torrent_name`、`bangumi_id`、`official_title`、`save_path`、`collection`(多文件合集)。
|
||
- 路径都是**下载器视角**:`save_path` 是种子保存目录,`old_path` / `new_path` 是种子内的相对路径。AB 与下载器不在同一台机器,或两者的挂载路径不同时,插件要自己做路径映射。
|
||
- 事件处理在独立队列里异步执行,有超时,失败计入熔断,不会拖慢或中断重命名。耗时操作(如调用媒体服务器)最好自己合并、延迟执行。内置插件「媒体库刷新」(`media-server-refresh`)就是这样做的:收到第一个 `file.renamed` 后等待一段时间,再请求 Jellyfin / Emby / Plex 刷新一次。
|
||
|
||
## 测试
|
||
|
||
`ab_sdk.testing` 可以在不启动 AB 的情况下构造并驱动插件:
|
||
|
||
```python
|
||
from ab_sdk.testing import create_plugin
|
||
|
||
async def test_push(tmp_path):
|
||
plugin, ctx = create_plugin(MyPlugin, {"key": "k"}, data_dir=tmp_path)
|
||
await plugin.setup()
|
||
factory = plugin.push()
|
||
...
|
||
```
|
||
|
||
## 以 pip 包发布
|
||
|
||
在包的 `pyproject.toml` 中声明 entry point,并在**顶层包内**附带 `plugin.toml`:
|
||
|
||
```toml
|
||
[project.entry-points."autobangumi.plugins"]
|
||
my-plugin = "my_plugin:MyPlugin"
|
||
```
|
||
|
||
pip 安装的插件同样未签名,需要开启「允许未签名插件」。Docker 镜像无法 pip 安装,此时请使用本地目录,并把依赖放进 `vendor/`。
|