[4.0] — Beta

4.0 是插件化重构的大版本：下载、通知、解析、搜索、重命名与整理都通过同一套扩展点实现，内置功能与第三方插件走相同的接口。下载器可以有多个实例，重命名、硬链接、种子过滤与媒体库刷新由内置插件提供。只支持从 3.3.x 升级，第一次启动时自动迁移配置并备份原文件。

升级步骤、回滚方法与升级后的检查项见 从 3.3 升级到 4.0。

4.0.0-beta.1

Docker 镜像：ghcr.io/estrellaxd/auto_bangumi:4.0.0-beta.1（dev-latest 也指向最新测试版）。

破坏性变更

• 只支持从 3.3.x 升级。 检测到更早版本的数据（config/version.info 低于 3.3，或残留 2.x 的 data/data.json）时拒绝启动，并提示先升级到最新的 3.3.x 启动一次。
• 配置结构变化，自动迁移。 下载器改为 plugins.instances 中的实例，plugins.slots.downloader 指向默认实例；重命名方式与版本冲突策略移到 plugins.slots.rename_strategy / plugins.slots.conflict_policy。第一次启动时自动迁移 3.3 的 downloader、bangumi_manage.rename_method、bangumi_manage.revision_conflict_policy，原文件备份为 config.json.v3.bak（已有备份时另存为 config.json.v3.bak.1 等，不覆盖）。迁移失败时 config.json 保持原样、拒绝启动，日志写明出错的字段。AB_DOWNLOADER_*、AB_DOWNLOAD_PATH、AB_METHOD、AB_REVISION_CONFLICT_POLICY 环境变量照常生效。
• 通知渠道旧字段。 Bark 不再读取 token（改用 device_key），WeCom 不再读取 chat_id（改用 webhook_url）。升级时自动迁移。
• 移除旧 API。 3.2 兼容的 GET 控制端点（/api/v1/restart、/start、/stop、/shutdown）和 GET /api/v1/auth/refresh_token 已移除，请改用 POST。
• 移除旧配置。 移除 experimental_openai 配置节与通知的单渠道旧字段（3.3 已迁移到 llm 与 notification.providers）；移除废弃的 normal 重命名方式，已有配置自动改为行为相同的 none。
• 数据库自动升级到 schema v26（新增插件存储表与 downloader_id 列）。

插件系统

• 新增插件运行时：插件可以来自内置目录、签名插件目录、本地目录（config/plugins/local/）或 pip 包。本地与 pip 插件未签名，需开启 设置 → 插件 → 允许未签名插件（plugins.allow_unsigned）才会加载。
• 插件可以提供下载器、通知渠道、LLM 解析提供商、搜索站点、元数据源和定时任务。内置的 qBittorrent / aria2 与各通知渠道走同一套扩展点。下载器类型、通知渠道、订阅解析器的下拉框会列出插件提供的选项。
• 插件可以在 RSS 下载流程中过滤种子、修正解析结果、修改保存路径 / 分类 / 标签，或为私有站点的请求添加 Cookie 等请求头。
• 设置页新增「插件」卡片：查看状态、启停插件，并通过自动生成的表单修改插件配置；秘密字段在读取接口中一律掩码。
• 签名插件目录：GET /api/v1/plugins/catalog 列出目录中的插件，POST /api/v1/plugins/{id}/install 验证 sha256 与 ed25519 签名后安装并启用，DELETE /api/v1/plugins/{id} 卸载。
• 插件的钩子调用有超时。同一插件连续失败 5 次后被自动禁用，修复后在设置页重新启用即可。

多下载器

• 设置 → 下载设置 可以添加多个下载器实例（qBittorrent、aria2 或插件提供的下载器）并指定默认实例。
• 规则与 RSS 订阅可以选择下载器，留空时用默认实例；由订阅新建的规则继承订阅的选择。
• 每个种子记录它所在的下载器，重命名、删除都在该下载器上进行。规则改用另一个下载器后，已有种子留在原处。
• 重命名逐个下载器运行。连不上的下载器被跳过，并在第一次连不上时发送「下载器连接异常」通知。
• 下载器页与种子列表标出种子所在的下载器。GET /api/v1/downloader/torrents 汇总所有实例，暂停 / 恢复 / 删除 / 打标接口新增 downloader_id，新增 GET /api/v1/downloader/instances。

重命名与整理

• 重命名改为插件：pn / advance / template 由默认启用的内置插件「重命名」（rename）提供，none 由 AB 本身提供。pn / advance 的输出与 3.3 逐字一致。字幕与正片使用同一种方式。
• 新增 template 重命名方式：用模板自定义文件名，默认模板对普通剧集与 pn 相同（剧场版 pn 不加 SxxExx，默认模板会加）。保存时试渲染，不合法的模板直接拒绝；运行时渲染失败的文件保留原名并发送「文件未重命名」通知，不会退回 pn。
• 新增内置插件「硬链接到媒体库」（hardlink，默认停用）：种子整理完成后把正片与字幕链接到媒体库目录，下载目录继续做种。按下载器实例配置路径映射（path_map）；跨文件系统时默认复制。不覆盖不是它创建的文件，版本升级后替换自己创建的链接；复制中断不会在媒体库留下半个文件。已有文件可通过 POST /api/v1/plugins/hardlink/backfill 补链。
• 新增内置插件「媒体库刷新」（media-server-refresh）：填写 Jellyfin / Emby / Plex 地址与 API Key 后，合并一段时间内整理完成的种子，请求刷新媒体库。未配置时不做任何事。
• 新增内置插件「种子过滤」（ingest-filters，默认启用）：填写「包含过滤」后，只下载名称匹配任一表达式的种子（对所有订阅生效）；留空时不过滤。

事件、API 与 MCP

• 系统事件（RSS 订阅异常、种子添加失败、下载器不可用、新版本、文件重命名、种子整理完成等）发布到事件总线，插件可以订阅。
• 插件可以提供 REST 路由（挂载于 /api/v1/plugins/<插件 id>/，需要登录）、MCP 工具与 MCP 资源，并可以按事件类型和渠道改写系统通知的标题与正文。
• 插件可以发出通知，通知进入通知中心。
• 通知中心改为事件推送：有新消息、已读或删除时立即更新（原先每 3 秒检查一次）。

前端插件

• WebUI 新增插件挂载点，插件可以在指定位置加入自己的界面（Web Component）。内置的硬链接插件用它提供补链按钮。
• 新增示例插件 manual-pick（手动选种），演示前端挂载点。

插件开发工具

• 插件 SDK ab_sdk 单独打包为 autobangumi-sdk 轮子，随 GitHub Release 发布（不发布到 PyPI）。
• 新增 ab-plugin 命令行：new 生成插件骨架与契约测试，validate 校验清单与 SDK 版本范围，pack 打包为可安装的 zip，dev 把插件目录链接到 config/plugins/local/ 并开启 plugins.dev_mode。开启 dev_mode 后，修改本地插件的文件会自动重新加载该插件。
• ab_sdk.testing 提供下载器、重命名方式、通知渠道、搜索站点的契约测试套件。
• 新增 5 个示例插件（examples/plugins/，CI 逐个运行它们的测试）：webhook-on-event、custom-rss-site、template-rename、nfo-writer、ntfy-notifier。
• 新增插件作者 agent skill，随 GitHub Release 以 autobangumi-plugin-skill-<版本>.zip 发布。
• 插件开发文档拆为总览、核心概念与每个扩展点一页（中 / 英 / 日），见 插件开发。

修复

• 新保存的搜索站点要重启后才出现在搜索站点列表中；现在立即出现。
• MCP 客户端断开 SSE 连接后，日志出现 AssertionError: Unexpected message http.response.start（3.x 起存在）。
• 插件配置的校验器报错时，保存接口返回 500 而不是 422。
• version.info 只比较次版本号，跨主版本升级（如 3.3 → 4.0）不会被记录。
• 4.x 把运行版本写入 config/version_v4.info，并在首次启动 3.3 的数据时把数据库备份为 data/data.db.v3.bak。回滚到 3.3 时不再误跑 3.0 迁移、重建数据库。

清理

• 删除 3.0 → 3.1、3.1 → 3.2 跨版本迁移、旧 JWT 与内存会话实现，以及约 70 处无调用方的代码；CI 新增死代码检查。