docs(4.0): 更新 API 参考与开发者文档，新增获取 SDK 页

- API 参考按实际路由重写，修正认证方式、请求方法与设置向导端点 - 数据库指南改为异步 Database 与 MIGRATIONS - E2E 指南改为指向 e2e/README.md - 插件快速上手补上安装 SDK 轮子的步骤，ab-plugin dev 加 --config-dir - 发布流程改为手动推送标签触发
2026-11-03 14:16:03 +08:00 · 2026-10-08 17:36:53 +02:00
parent f6bca2be60
commit 776abfa896
32 changed files with 1394 additions and 3015 deletions
--- a/docs/dev/plugins/builtin.md
+++ b/docs/dev/plugins/builtin.md
@@ -49,7 +49,7 @@
 - 本插件之前为同一集创建的链接，在版本升级（新版本替换旧种子，规范文件名不变）后被原子替换为指向新文件的链接。
 - 已链接的文件再次收到事件时不做任何事；插件在自己的键值存储里记录它创建过的目标路径。
 - **删除种子不会删除媒体库中的链接。**
- 启用前已经下载的文件不会自动处理。在插件的设置分区点「补链已有文件」，或调用 `POST /api/v1/plugins/hardlink/backfill`：遍历 `source_root` 下的 `.mp4` / `.mkv` / `.ass` / `.srt`，返回 `{"linked", "exists", "conflict", "failed"}` 计数。
+- 启用前已经下载的文件不会自动处理。在插件的设置分区点「链接已有文件」，或调用 `POST /api/v1/plugins/hardlink/backfill`：遍历 `source_root` 下的 `.mp4` / `.mkv` / `.ass` / `.srt`，返回 `{"linked", "exists", "conflict", "failed"}` 计数。

 ::: tip Docker
 硬链接不能跨文件系统。在 Docker 中，请把下载目录与媒体库放在同一块盘上，并以**同一个挂载点**映射进 AB 容器（例如把 `/mnt/media` 整体挂载为 `/media`，下载目录与媒体库都在其下）。两个独立挂载的目录即使在同一块盘上，也会被视为不同文件系统，链接会退化为 `cross_device` 指定的行为。下载器运行在另一个容器里、看到的路径与 AB 不同时，用 `path_map` 做映射。
--- a/docs/dev/plugins/cli.md
+++ b/docs/dev/plugins/cli.md
@@ -7,7 +7,7 @@ uv tool install ./autobangumi_sdk-0.5.0-py3-none-any.whl
 # 或在项目里：uv add ./autobangumi_sdk-0.5.0-py3-none-any.whl
 ```

-轮子在 4.0 beta / 正式版的 GitHub Release 附件中，不发布到 PyPI。契约测试需要 pytest：`uv add --dev pytest`（或安装 `autobangumi-sdk[test]`）。
+轮子在 4.0 beta / 正式版的 GitHub Release 附件中，不发布到 PyPI，见 [获取 SDK](/dev/plugins/sdk)。契约测试需要 pytest：`new` 生成的 `pyproject.toml` 已在 `dev` 依赖组里带上 pytest；自己建的项目用 `uv add --dev pytest`（或安装 `autobangumi-sdk[test]`）。

 ## new

@@ -28,6 +28,8 @@ ab-plugin new <id> [--kind rename|notifier|search] [--dir .]

 `id` 只能由小写字母、数字和连字符组成。目录已存在时拒绝执行。没有下载器骨架：下载器要连接真实后端，一个能直接通过契约的骨架没有意义。

+生成的 `pyproject.toml` 依赖 `autobangumi-sdk`。这个包不在 PyPI 上，运行 `uv run pytest` 前先在插件目录里执行一次 `uv add <轮子路径>`，uv 会把依赖指向本地轮子。
+
 ## validate

 ```bash
@@ -42,7 +44,7 @@ ab-plugin validate [path]
 ab-plugin pack [path] [-o dist]
 ```

-先校验，再打成 `dist/<id>-<版本>.zip`。zip 内容在 zip 根（与签名目录的包布局一致）。排除 `tests/`、`pyproject.toml`、`uv.lock`、缓存和 `dist/`。文件顺序与时间戳固定：同样的内容得到同样的 sha256。
+先校验，再打成 `dist/<id>-<版本>.zip`。zip 内容在 zip 根（与签名目录的包布局一致）。排除 `tests/`、`pyproject.toml`、`uv.lock`、`dist/`、`.venv`、`.git`、`node_modules`、各类缓存和 `.pyc`。文件顺序与时间戳固定：同样的内容得到同样的 sha256。

 ## dev

@@ -50,7 +52,9 @@ ab-plugin pack [path] [-o dist]
 ab-plugin dev [path] [--config-dir config]
 ```

- 把插件目录软链到 `<config-dir>/plugins/local/<id>`。
+- 先校验，再把插件目录软链到 `<config-dir>/plugins/local/<id>`。
+- `--config-dir` 默认是当前目录下的 `config`。在插件目录里运行时，请指向 AB 的配置目录（源码运行时为 `backend/src/config`）。
+- 软链接指向插件目录的绝对路径，AB 必须能用同一路径访问它（例如源码运行的 AB）。AB 在 Docker 中运行时，请把插件目录复制或挂载到容器的 `config/plugins/local/<id>/`，再在 设置 → 插件 中开启「允许未签名插件」并启用它。
 - 在宿主配置文件（先找 `config_dev.json`，再找 `config.json`）里写入 `plugins.dev_mode`、`plugins.allow_unsigned` 和 `plugins.enabled.<id>`。
 - 配置文件不存在时拒绝执行：请先启动一次 AutoBangumi。
 - 运行中的 AB 不会重读配置文件，需要重启一次。之后，`dev_mode` 每秒检查一次本地插件目录，文件变化后自动重载该插件。上次加载失败的插件也被监听，修好源码后自动恢复。
@@ -61,8 +65,9 @@ ab-plugin dev [path] [--config-dir config]
 ```bash
 ab-plugin new my-notify --kind notifier
 cd my-notify
+uv add ../autobangumi_sdk-0.5.0-py3-none-any.whl   # 只需一次
 uv run pytest            # 契约测试
-ab-plugin dev .          # 链接并开启热重载，重启 AB 一次
+ab-plugin dev . --config-dir /path/to/autobangumi/config   # 链接并开启热重载，重启 AB 一次
 # 改代码 → AB 自动重载 → 在 WebUI 里验证
 ab-plugin pack .
 ```
--- a/docs/dev/plugins/config-forms.md
+++ b/docs/dev/plugins/config-forms.md
@@ -49,4 +49,4 @@ class MyPlugin(Plugin[Options]):

 ## 超出表单的界面

-表单满足不了时（图表、操作按钮、列表），插件可以提供前端组件，见 [前端挂载点](/dev/plugins/frontend-slots)。内置 `hardlink` 的「补链已有文件」按钮就是一个 `settings.section` 组件。
+表单满足不了时（图表、操作按钮、列表），插件可以提供前端组件，见 [前端挂载点](/dev/plugins/frontend-slots)。内置 `hardlink` 的「链接已有文件」按钮就是一个 `settings.section` 组件。
--- a/docs/dev/plugins/examples.md
+++ b/docs/dev/plugins/examples.md
@@ -21,10 +21,12 @@ cp -r examples/plugins/ntfy-notifier config/plugins/local/

 ## 运行示例的测试

+在仓库根目录运行，脚本逐个校验示例的清单并运行它的测试（与 CI 相同）：
+
 ```bash
-cd examples/plugins/ntfy-notifier && uv run pytest
-# 或一次跑完全部示例（在仓库根目录）：
 scripts/test_example_plugins.sh
 ```

+脚本在 `backend/` 的环境里运行，SDK 以可编辑方式装在那里。示例的 `pyproject.toml` 依赖 `autobangumi-sdk`，PyPI 上没有这个包；把示例复制到仓库外单独测试时，先在示例目录里 `uv add <轮子路径>`，再 `uv run pytest`。
+
 刷新 Jellyfin / Emby / Plex 媒体库不需要写插件：内置插件 `media-server-refresh` 已经支持。
--- a/docs/dev/plugins/points/message-template.md
+++ b/docs/dev/plugins/points/message-template.md
@@ -21,5 +21,5 @@ class Alerts(Plugin):

 - 只影响外部推送。通知中心里的文案由前端按 `i18n()` 渲染，不受影响。
 - 钩子对每个启用的渠道各调用一次；`channel` 是渠道类型，如 `telegram`。
- 钩子出错或超时时沿用上一步的文案，并计入熔断；返回值类型不对时整条消息回退到默认文案。
+- 钩子出错、超时或返回的不是 `RenderedMessage` 时，AB 沿用上一步的文案，并计入熔断。后面的钩子照常执行。
 - 「新集数」通知暂不经过该钩子，仍使用通知渠道里配置的单集模板。
--- a/docs/dev/plugins/sdk.md
+++ b/docs/dev/plugins/sdk.md
@@ -0,0 +1,80 @@
+# 获取 SDK
+
+插件 SDK 不发布到 PyPI。每个 4.0 beta 与正式版的 [GitHub Release](https://github.com/EstrellaXD/Auto_Bangumi/releases) 都附带两个给插件作者的文件：
+
+| 文件 | 内容 |
+| --- | --- |
+| `autobangumi_sdk-<SDK 版本>-py3-none-any.whl` | `ab_sdk` 包与 `ab-plugin` 命令行 |
+| `autobangumi-plugin-skill-<AB 版本>.zip` | 给 AI 编码助手使用的插件开发 skill |
+
+轮子文件名里是 SDK 版本（`ab_sdk.SDK_VERSION`，如 `0.5.0`），不是 AB 的版本号。请从目标 AB 版本的 Release 下载轮子，两者的 SDK 版本一致。插件清单里的 `sdk` 范围（如 `">=0.5,<1"`）必须包含这个版本。
+
+## 安装轮子
+
+轮子要求 Python 3.13 或更高，依赖 `pydantic`、`httpx` 与 `packaging`，不需要安装 AutoBangumi。
+
+只用命令行时，装成全局工具：
+
+```bash
+uv tool install ./autobangumi_sdk-0.5.0-py3-none-any.whl
+ab-plugin --help
+```
+
+写插件和跑测试时，把轮子加为插件项目的依赖：
+
+```bash
+cd my-plugin
+uv add ../autobangumi_sdk-0.5.0-py3-none-any.whl
+uv run pytest
+```
+
+`uv add` 在 `pyproject.toml` 的 `[tool.uv.sources]` 里记下轮子的本地路径。`ab-plugin pack` 不打包 `pyproject.toml` 与 `uv.lock`，这个路径不会进入插件包。`ab-plugin new` 生成的 `pyproject.toml` 已经依赖 `autobangumi-sdk`，但没有指定来源，所以在新骨架里也要先执行一次 `uv add`。
+
+契约测试需要 pytest。骨架的 `dev` 依赖组已带上 pytest；也可以安装可选依赖 `autobangumi-sdk[test]`。
+
+升级 SDK 时，下载新 Release 的轮子，再执行一次 `uv tool install --force <新轮子>` 或 `uv add <新轮子>`。
+
+## 在 AB 仓库里开发
+
+SDK 的源码在 `backend/src/ab_sdk`，打包配置在 `backend/sdk/pyproject.toml`。`backend` 的 `dev` 依赖组以可编辑方式安装它，所以在仓库里不需要轮子：
+
+```bash
+cd backend
+uv sync --group dev
+uv run ab-plugin validate ../examples/plugins/ntfy-notifier
+```
+
+自己构建轮子（与 CI 相同的命令）：
+
+```bash
+uv build --wheel backend/sdk --out-dir sdk-dist
+```
+
+## 插件开发 skill
+
+skill 是一组 Markdown 说明，AI 编码助手读取它们来写、测试和打包 AB 插件。zip 内是 `autobangumi-plugin/` 目录：
+
+```
+autobangumi-plugin/
+├── SKILL.md                    # 工作流程、扩展点一览、常见错误
+└── references/
+    ├── extension-points.md     # 每个扩展点的签名与字段
+    ├── frontend.md             # 前端挂载点
+    └── testing.md              # 契约测试与 create_plugin
+```
+
+把它解压到助手的 skills 目录。以 Claude Code 为例，个人 skills 目录是 `~/.claude/skills/`：
+
+```bash
+unzip autobangumi-plugin-skill-<AB 版本>.zip -d ~/.claude/skills/
+```
+
+其它助手请按它们各自的 skills 目录放置。skill 的源码在仓库的 `skills/autobangumi-plugin/`。
+
+## CI 如何构建
+
+`.github/workflows/build.yml` 的 `release` 任务只在维护者推送版本标签时运行：
+
+1. `uv build --wheel backend/sdk --out-dir sdk-dist` 构建轮子，版本取自 `ab_sdk.SDK_VERSION`。
+2. 把 `skills/autobangumi-plugin` 压缩为 `autobangumi-plugin-skill-<AB 版本>.zip`。
+3. 把两者与 WebUI、在线更新包等文件一起附到该版本的 GitHub Release。beta（预发布）与正式版都带这两个文件。
--- a/docs/dev/plugins/signing.md
+++ b/docs/dev/plugins/signing.md
@@ -1,6 +1,6 @@
 # 签名与分发

-插件有三种来源，信任级别不同：
+插件有四种来源，信任级别不同：

 | 来源 | 位置 | 签名 | 如何启用 |
 | --- | --- | --- | --- |
@@ -49,11 +49,7 @@ AB 从 GitHub release `plugins` 下载 `catalog.json`。目录包含：

 签名目录的插件只能依赖标准库和 AB 已有的包，不做 pip 安装。需要第三方纯 Python 库时放进 `vendor/`。

-::: warning WebUI 尚无目录界面
-4.0 预览期间，目录的浏览和安装只有 API，设置 → 插件 页还没有对应的按钮。
-:::
-
-API：
+在 WebUI 中，**设置 → 插件** 的「插件目录」区域可以浏览目录，并安装、更新与卸载插件。API：

 | 请求 | 说明 |
 | --- | --- |
@@ -86,4 +82,4 @@ API：

 ## 发布 SDK

-SDK 以轮子发布在 4.0 beta / 正式版的 GitHub Release 附件里，由 CI 用 `uv build --wheel backend/sdk` 构建。同一个 Release 还附带 `autobangumi-plugin-skill-<版本>.zip`：给 AI 编码助手使用的插件开发 skill，解压到助手的 skills 目录即可。
+SDK 轮子与插件开发 skill 由 CI 构建，附在每个 4.0 beta / 正式版的 GitHub Release 上，维护者不需要手动发布。下载和安装见 [获取 SDK](/dev/plugins/sdk)。