mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-11-01 13:15:59 +08:00
3258fcca4b
- docs/dev/plugins.md 改为总览与导航，旧内容拆入 docs/dev/plugins/ - 新增核心概念、配置表单、事件、前端挂载点、命令行、签名与分发、内置插件、示例页 - 每个扩展点一页，侧边栏由页面表生成 - 改正旧文档中下载器配置、hardlink path_map 与补链按钮的过时描述
67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# 重命名方式（rename_strategy）
|
||
|
||
下载完成后，AB 为种子里的每个正片与字幕调用「重命名方式」（`plugins.slots.rename_strategy`）对应的 Provider。宿主只自带 `none`（保留原名）；`pn`、`advance`、`template` 由内置插件 `rename` 提供。插件登记的 `id` 出现在 设置 → 番剧管理设置 → 重命名方式 的下拉框里。
|
||
|
||
```python
|
||
from ab_sdk import Plugin, points, provider
|
||
from ab_sdk.rename import RenameInput, RenameSkipped, pad
|
||
|
||
|
||
class JellyfinStyle:
|
||
def target_name(self, f: RenameInput) -> str:
|
||
language = f".{f.language}" if f.kind == "subtitle" else ""
|
||
if f.episode_type == "movie":
|
||
return f"{f.bangumi_name}{language}{f.suffix}"
|
||
if not f.bangumi_name:
|
||
raise RenameSkipped("缺少番剧文件夹名")
|
||
return f"{f.bangumi_name} - S{pad(f.season)}E{pad(f.episode)}{language}{f.suffix}"
|
||
|
||
|
||
class MyRename(Plugin):
|
||
@provider(points.RENAME_STRATEGY, id="jellyfin-style")
|
||
def jellyfin(self):
|
||
return JellyfinStyle()
|
||
```
|
||
|
||
## RenameInput
|
||
|
||
冻结快照。
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `kind` | `media` 或 `subtitle`（字幕没有单独的方式，按 `kind` 区分） |
|
||
| `media_path` | 种子内的原相对路径 |
|
||
| `title` | 解析自文件名的标题 |
|
||
| `bangumi_name` | 保存目录的番剧文件夹名（电影为 `Title (Year)`） |
|
||
| `season`、`episode` | 季与集；`episode` 已应用集数偏移 |
|
||
| `suffix` | 含点的扩展名，如 `.mkv` |
|
||
| `episode_type` | `episode`、`movie` 或 `special` |
|
||
| `language` | 字幕语言，如 `zh`、`zh-tw` |
|
||
| `group` | 字幕组，可能为 `None` |
|
||
|
||
`title` 和 `bangumi_name` 来自磁盘上已有的文件名或文件夹名，是单个路径分量，AB 不做保留字符清洗。
|
||
|
||
## 返回值与错误
|
||
|
||
- 返回种子内的新相对路径，通常只是文件名。扩展名和字幕语言由策略自己拼上。返回 `f.media_path` 表示不改名。
|
||
- `pad(n, width=2)` 补零并保留半集的小数：`pad(9.5) == "09.5"`。总集篇等半集必须保留小数，否则会覆盖同季的整数集。
|
||
- 抛出 `RenameSkipped(原因)`：该文件保留原名，种子不打「已重命名」标签，每个种子按原因发一条 `rename_skipped` 通知。修正后下一轮自动重试。它表示输入或配置有问题，不计入熔断。**不要在失败时退回别的命名方式。**
|
||
- 抛出其它异常、返回空串或非字符串：同样保留原名并通知，同时计入熔断。
|
||
- `target_name` 是同步调用，没有超时，不要在里面做网络或磁盘 IO。
|
||
- 设置里选择的 `id` 没有登记（插件被停用或熔断）时，AB 记录一次日志并按 `none` 处理。
|
||
|
||
## 测试
|
||
|
||
```python
|
||
from ab_sdk.testing import RenameStrategyContract, create_plugin
|
||
|
||
class TestStrategy(RenameStrategyContract):
|
||
def create(self):
|
||
plugin, _ = create_plugin(MyRename)
|
||
return plugin.jellyfin()
|
||
```
|
||
|
||
套件检查：返回非空的相对路径、不含 `..`、保留扩展名、结果确定。适用于特定输入时，覆盖 `samples()`。
|
||
|
||
示例：`examples/plugins/template-rename`（自带过滤器的模板）。
|