[4.0]

4.0.0 — 插件化重构

4.0 是插件化重构的大版本：下载、通知、解析、搜索、重命名与整理都通过同一套扩展点实现，内置功能与第三方插件走相同的接口。下载器可以有多个实例；重命名、硬链接、种子过滤与媒体库刷新由内置插件提供；新增插件市场。

Docker 镜像：ghcr.io/estrellaxd/auto_bangumi:4.0.0（Docker Hub：estrellaxd/auto_bangumi:4.0.0）。latest 现在指向 4.0。

升级前必读

• 只支持从 3.3.x 升级。 检测到更早版本的数据时拒绝启动，并提示先升级到最新的 3.3.x 启动一次。
• 使用 latest 标签的 3.3 用户，下一次拉取镜像就会升级到 4.0。 拉取前请备份 config 与 data 目录。暂时不升级，就把标签固定为 3.3.7。
• 第一次启动自动迁移。 原配置备份为 config.json.v3.bak；数据库升级到 schema v28，3.3 的数据库备份为 data/data.db.v3.bak。
• 应用内更新不能从 3.3 升级到 4.0，请更换镜像标签。3.3.7 起，3.3 的应用内更新只提供 3.x 版本。
• 升级步骤、迁移细节与回滚方法见 从 3.3 升级到 4.0。

破坏性变更

• 配置结构。 下载器改为 plugins.instances 中的实例，plugins.slots.downloader 指向默认实例；重命名方式与版本冲突策略移到 plugins.slots.rename_strategy / plugins.slots.conflict_policy。第一次启动时自动迁移。AB_DOWNLOADER_*、AB_DOWNLOAD_PATH、AB_METHOD、AB_REVISION_CONFLICT_POLICY 环境变量照常生效。
• 通知渠道旧字段。 Bark 改用 device_key（不再读取 token），WeCom 改用 webhook_url（不再读取 chat_id）。自动迁移。
• 移除的 API 与配置。 3.2 兼容的 GET 控制端点（/api/v1/restart、/start、/stop、/shutdown）与 GET /api/v1/auth/refresh_token 已移除，请改用 POST。移除 experimental_openai 配置节、通知的单渠道旧字段与 normal 重命名方式（自动改为行为相同的 none）。
• MCP 只提供 Streamable HTTP，端点为 /mcp；旧的 /mcp/sse 已删除，请更新 MCP 客户端的地址。
• API。 带 JSON 请求体的调用必须发送 Content-Type: application/json，否则返回 422；未知的 /api/… 路径返回 404。
• 运行环境与插件 SDK。 Docker 镜像使用 Python 3.14，HTTP 客户端换成 httpx2。插件 SDK ab_sdk 0.6.0 的 build_http_client 返回 httpx2.AsyncClient。

新功能

• 插件系统。 插件可以提供下载器、通知渠道、LLM 解析、搜索站点、元数据源、定时任务、REST 路由、MCP 工具与 WebUI 界面，也可以在 RSS 下载流程中过滤种子、修正解析结果、修改保存路径与请求头。钩子有超时，连续失败 5 次的插件被自动停用。
• 插件市场。 新增「插件市场」页面：按分类与状态筛选，安装前确认来源、权限与前端。安装时校验 sha256 与 ed25519 签名。首批上架：Webhook、ntfy、Slack、Synology Chat 与 Apprise 通知，运行外部命令，STRM 文件，NFO 文件，模板重命名，自定义 RSS 站点，手动选种。第三方插件经 PR 上架。
• 多下载器。 可以添加多个 qBittorrent、aria2 或插件提供的下载器实例。规则与订阅可以选择下载器；每个种子记录它所在的实例，重命名与删除都在该实例上进行。
• 重命名与整理。 pn / advance 由内置插件提供，输出与 3.3 逐字一致；新增 template 模板重命名。新增内置插件「硬链接到媒体库」（默认停用）、「媒体库刷新」（Jellyfin / Emby / Plex）与「种子过滤」。
• 事件与通知。 系统事件发布到事件总线，插件可以订阅；通知中心改为即时推送。Bark 可以设置铃声、分组、中断级别、图标与点击后打开的地址。
• 插件开发。 autobangumi-sdk 轮子与 ab-plugin 命令行（new / validate / pack / dev）、契约测试套件、13 个示例插件与插件作者 agent skill，随每个 GitHub Release 发布。文档提供中 / 英 / 日三种语言，见 插件开发。
• 界面。 图标换成 Lucide，弹窗与输入框使用统一组件。逐页检查桌面、平板、手机与深色模式，修复 150 余处对齐、溢出与布局问题。
• 性能。 下载器页改为虚拟滚动表格：2 万个种子时打开时间从约 15 秒降到 0.2 秒以内，内存从约 3 GB 降到几十 MB。RSS 刷新时每个订阅每轮只拉取一次；事件流流量约减少 80 %；静态文件与 API 启用 gzip；启动更快，内存约少 30 MB。

相比 3.3 的主要修复

• 回滚到 3.3 时不再误跑 3.0 迁移、重建数据库：4.x 把运行版本写入 config/version_v4.info。回滚后再升级会重新备份数据库。
• 从搜索结果建立的订阅不再带入集号，可以收到整季的更新（#1138）。
• 文件名不需要改变时，下载完成也会发送通知（#1082）。
• 偏移检测：复扫没有发现偏移时清除旧标记，同一偏移只通知一次（#1072）。
• 登录成功后页面不跳转、需要手动刷新的问题（#1145）。
• 一个下载器出错不再中止其它下载器的重命名；任务在两次请求之间被删除时，只跳过这一个任务。

每个测试版的完整变更见下文与 CHANGELOG.md。

4.0.0-beta.3

破坏性变更

• MCP 改用 Streamable HTTP，端点为 /mcp，旧的 /mcp/sse 已删除，请更新 MCP 客户端的地址。
• 带 JSON 请求体的 API 调用必须发送 Content-Type: application/json，否则返回 422。
• 未知的 /api/… 路径返回 404，不再返回 WebUI 页面。
• 插件 SDK（ab_sdk）0.6.0：AdapterContext.build_http_client 返回 httpx2.AsyncClient，只调用 get / post 的插件不需要改动，直接使用 httpx 专有 API 的插件必须更新。
• 运行环境：Python 3.14。

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 新增死代码检查。