Merge refactor/4.0-final into docs/4.0-site

docs/dev/plugins/builtin.md

@@ -23,7 +23,7 @@
 
 ## media-server-refresh
 
-订阅 `torrent.organized`。收到第一个事件后等待 `delay` 秒，期间整理完成的种子合并成一次刷新请求。
+订阅 `torrent.organized` 与 `hardlink` 发布的 `hardlink.linked`（文件新放入媒体库）。收到第一个事件后等待 `delay` 秒，期间的事件合并成一次刷新请求；刷新请求发出后到达的事件再排一次。
 
 | 选项 | 说明 |
 | --- | --- |
@@ -47,7 +47,7 @@
 - 链接或副本先写到目标旁的临时文件，再原子地改名，复制中断不会留下半个文件。
 - 媒体库中已有同名文件、但不是本插件创建的：跳过，不覆盖，并发一条 `hardlink.failed` 通知。
 - 本插件之前为同一集创建的链接，在版本升级（新版本替换旧种子，规范文件名不变）后被原子替换为指向新文件的链接。
-- 已链接的文件再次收到事件时不做任何事；插件在自己的键值存储里记录它创建过的目标路径。
+- 已链接的文件再次收到事件时不做任何事；插件在自己的键值存储里记录它创建过的目标路径。插件放置后被用户删除的文件，再次收到事件时也不重建，只有补链会重建。
 - **删除种子不会删除媒体库中的链接。**
 - 启用前已经下载的文件不会自动处理。在插件的设置分区点「链接已有文件」，或调用 `POST /api/v1/plugins/hardlink/backfill`：遍历 `source_root` 下的 `.mp4` / `.mkv` / `.ass` / `.srt`，返回 `{"linked", "exists", "conflict", "failed"}` 计数。
 

docs/dev/plugins/events.md

@@ -42,11 +42,11 @@ AB 发出的、会进入通知中心的事件都是 `ab_sdk.events.SystemEvent`
 | kind | 事件类 | 字段 | 何时发布 |
 | --- | --- | --- | --- |
 | `file.renamed` | `FileRenamed` | `bangumi_id`、`old_path`、`new_path`、`file_kind`、`downloader_id` | 一个文件被实际重命名（含版本替换后的改名） |
-| `torrent.organized` | `TorrentOrganized` | `torrent_hash`、`bangumi_id`、`files`（`OrganizedFile(path, kind)` 元组）、`downloader_id` | 一个种子整理完成；重命名方式为 `none` 时同样发布，`files` 为原路径 |
+| `torrent.organized` | `TorrentOrganized` | `torrent_hash`、`bangumi_id`、`files`（`OrganizedFile(path, kind)` 元组）、`downloader_id` | 一个种子整理完成；重命名方式为 `none` 时同样发布，`files` 为原路径。选中的重命名方式未登记（插件停用或被熔断）时不发布 |
 
 - 路径是**下载器视角**的绝对路径，以 `/` 拼接（Windows 下载器的 `\` 也统一为 `/`）。AB 与下载器看到的目录不同（如分别运行在不同容器）时，订阅者要自己做路径映射。
 - `bangumi_id` 来自种子的 `ab:<id>` 标签，旧种子可能为 `None`。`downloader_id` 是种子所在下载器实例的 id；多个实例的路径视角可能不同。
-- `torrent.organized` 的投递是**至少一次**：未打「已重命名」标签的种子（如重命名方式为 `none`）在每次 AB 重启后会再发布一次。订阅者必须幂等。
+- `torrent.organized` 的投递是**至少一次**：下载器中已整理的种子（包括已打「已重命名」标签的）在每次 AB 重启后会再发布一次。订阅者必须幂等。
 - 这两个事件只发布到事件总线，不进入通知中心。
 
 ## 自定义事件

docs/dev/plugins/points/downloader.md

@@ -13,7 +13,7 @@ class MyClient:
     )
 
     def __init__(self, conn: DownloaderConnection) -> None:
-        self.conn = conn  # host / username / password / ssl
+        self.conn = conn  # host / username / password / ssl / instance_id
 
     async def auth(self, retry: int = 3) -> bool: ...
     async def logout(self) -> None: ...

docs/dev/plugins/signing.md

@@ -26,7 +26,7 @@ AB 从 GitHub release `plugins` 下载 `catalog.json`。目录包含：
       "kind": "plugin",
       "extension_points": ["notifier"],
       "sdk": ">=0.5,<1",
-      "min_ab_version": "4.0.0",
+      "min_ab_version": "4.0.0-beta.1",
       "description": "…",
       "asset": "ntfy-notifier-0.1.0.zip",
       "sha256": "…"
@@ -49,7 +49,11 @@ AB 从 GitHub release `plugins` 下载 `catalog.json`。目录包含：
 
 签名目录的插件只能依赖标准库和 AB 已有的包，不做 pip 安装。需要第三方纯 Python 库时放进 `vendor/`。
 
-在 WebUI 中，**设置 → 插件** 的「插件目录」区域可以浏览目录，并安装、更新与卸载插件。API：
+::: tip 在 WebUI 中安装
+在 设置 → 插件 的「插件目录」区点击「浏览目录」，可以安装、更新目录中的插件。经目录安装的插件卡片上有「卸载」按钮；内置、本地和 pip 插件没有。
+:::
+
+API：
 
 | 请求 | 说明 |
 | --- | --- |
@@ -71,11 +75,11 @@ AB 从 GitHub release `plugins` 下载 `catalog.json`。目录包含：
 
    ```bash
    uv run --no-project --with cryptography python scripts/build_plugin_catalog.py \
-       --key ~/.autobangumi/update-signing-key.pem --min-ab 4.0.0 \
+       --key ~/.autobangumi/update-signing-key.pem --min-ab 4.0.0-beta.1 \
        --out release-assets dist/*.zip
    ```
 
-   脚本输出 `catalog.json`、各 zip 及其 `.sig`。
+   脚本输出 `catalog.json`、各 zip 及其 `.sig`。`--min-ab` 不要写成 `4.0.0`：按 semver，`4.0.0-beta.N` 低于 `4.0.0`，4.0 beta 用户将无法安装。
 4. 维护者把整个目录上传到 release `plugins`（覆盖旧文件）。
 
 用户端通过 `GET /api/v1/plugins/catalog` 看到新版本。