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

- API 参考按实际路由重写，修正认证方式、请求方法与设置向导端点 - 数据库指南改为异步 Database 与 MIGRATIONS - E2E 指南改为指向 e2e/README.md - 插件快速上手补上安装 SDK 轮子的步骤，ab-plugin dev 加 --config-dir - 发布流程改为手动推送标签触发
2026-11-05 15:08:54 +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/api/index.md
+++ b/docs/api/index.md
@@ -1,619 +1,221 @@
 # REST API 参考

-AutoBangumi 在 `/api/v1` 路径下提供 REST API。除登录和设置向导外，所有端点都需要 JWT 认证。
+AutoBangumi 在 `/api/v1` 下提供 REST API。WebUI 使用的也是这套接口。

 **基础 URL：** `http://your-host:7892/api/v1`

-**认证：** 将 JWT 令牌作为 cookie 或 `Authorization: Bearer <token>` 请求头传入。
-
-**交互式文档：** 在开发模式下运行时，可在 `http://your-host:7892/docs` 访问 Swagger UI。
-
---
+**交互式文档：** 本页只列出端点和用途。请求与响应的字段以运行中实例的 `http://your-host:7892/docs`（Swagger UI，由 FastAPI 根据代码生成）为准。插件路由不出现在 `/docs` 中。

 ## 认证

-### 登录
+AB 接受两种凭据：

-```
-POST /auth/login
+- **浏览器会话**：`POST /auth/login` 以表单字段 `username`、`password` 登录，成功后 AB 设置 HttpOnly Cookie `token`。WebUI 使用这种方式。
+- **API 令牌**：在 设置 → 用户与访问控制 → API 令牌 中创建 `scope=api` 的令牌（或调用 `POST /tokens`），明文只显示一次。请求时带上 `Authorization: Bearer <令牌>`。
+
+```bash
+curl -H "Authorization: Bearer $AB_TOKEN" http://your-host:7892/api/v1/status
 ```

-使用用户名和密码进行认证。
+- 请求带 `Authorization` 头时，AB 只校验该令牌，不再看 Cookie。
+- 未认证或凭据无效返回 `401`。
+- 账户管理端点（`/auth/update`、`/users`、`/tokens`、Passkey 的注册与管理）只接受浏览器会话，用 API 令牌访问返回 `403`。
+- 以下端点不需要认证：`/auth/login`、`/passkey/auth/*`、设置向导 `/setup/*`（`GET /setup/status` 始终可用，其它端点在设置完成后返回 `403`）和根路径的 `/health`。
+- `/auth/refresh_token` 与 `/auth/logout` 不看 `Authorization` 头，只使用会话 Cookie。`refresh_token` 没有有效 Cookie 时返回 `401`。登录与 Passkey 登录受 `security.login_whitelist` 限制。
+- 本地开发时，设置环境变量 `AB_DEV_NO_AUTH=1` 可跳过全部认证。不要在生产环境中设置它。

-**请求体：**
-```json
-{
-  "username": "string",
-  "password": "string"
-}
-```
+## 认证与账户

-**响应：** 设置包含 JWT 令牌的认证 cookie。
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `POST` | `/auth/login` | 用户名和密码登录，设置会话 Cookie |
+| `POST` | `/auth/refresh_token` | 延长当前会话 |
+| `POST` | `/auth/logout` | 注销当前会话并清除 Cookie |
+| `GET` | `/auth/me` | 当前用户 |
+| `POST` | `/auth/update` | 修改当前账户，并轮换它的全部会话 |
+| `GET` / `POST` | `/users` | 列出 / 创建用户 |
+| `PATCH` / `DELETE` | `/users/{user_id}` | 修改 / 删除用户 |
+| `GET` / `POST` | `/tokens` | 列出 / 创建 API 令牌（`scope` 为 `api` 或 `mcp`，可设 `expires_at`） |
+| `DELETE` | `/tokens/{token_id}` | 吊销令牌 |
+| `POST` | `/passkey/register/options`、`/passkey/register/verify` | 注册 Passkey |
+| `POST` | `/passkey/auth/options`、`/passkey/auth/verify` | 用 Passkey 登录 |
+| `GET` | `/passkey/list` | 列出当前用户的 Passkey |
+| `POST` | `/passkey/delete` | 删除 Passkey |

-### 刷新令牌
+## 程序

-```
-GET /auth/refresh_token
-```
-
-刷新当前的认证令牌。
-
-### 登出
-
-```
-GET /auth/logout
-```
-
-清除认证 cookie 并登出。
-
-### 更新凭据
-
-```
-POST /auth/update
-```
-
-更新用户名和/或密码。
-
-**请求体：**
-```json
-{
-  "username": "string",
-  "password": "string"
-}
-```
-
---
-
-## Passkey / WebAuthn <Badge type="tip" text="v3.2+" />
-
-使用 WebAuthn/FIDO2 Passkey 进行无密码认证。
-
-### 注册 Passkey
-
-```
-POST /passkey/register/options
-```
-
-获取 WebAuthn 注册选项（质询、依赖方信息）。
-
-```
-POST /passkey/register/verify
-```
-
-验证并保存来自浏览器的 Passkey 注册响应。
-
-### 使用 Passkey 认证
-
-```
-POST /passkey/auth/options
-```
-
-获取 WebAuthn 认证质询选项。
-
-```
-POST /passkey/auth/verify
-```
-
-验证 Passkey 认证响应并签发 JWT 令牌。
-
-### 管理 Passkey
-
-```
-GET /passkey/list
-```
-
-列出当前用户所有已注册的 Passkey。
-
-```
-POST /passkey/delete
-```
-
-通过凭据 ID 删除已注册的 Passkey。
-
---
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/status` | 版本、运行状态、是否首次运行 |
+| `POST` | `/start`、`/stop`、`/restart` | 启动 / 停止 / 重启后台任务 |
+| `POST` | `/shutdown` | 关闭程序 |
+| `GET` | `/check/downloader` | 检查默认下载器是否可用 |
+| `GET` | `/log` | 读取日志 |
+| `POST` | `/log/clear` | 清空日志 |
+| `GET` | `/update/check` | 查询最新版本与在线更新状态 |
+| `POST` | `/update/apply` | 下载并应用最新更新，成功后重启 |
+| `POST` | `/update/rollback` | 回滚到上一个更新版本，没有备份时回到镜像自带版本 |
+| `GET` | `/health`（根路径，不在 `/api/v1` 下） | 存活探针，总是返回 `200`：`{"status", "version", "db_ok"}` |

 ## 配置

-### 获取配置
-
-```
-GET /config/get
-```
-
-获取当前应用程序配置。
-
-**响应：** 完整配置对象，包括 `program`、`downloader`、`rss_parser`、`bangumi_manager`、`notification`、`proxy`、`llm` 等部分。
-
-### 更新配置
-
-```
-PATCH /config/update
-```
-
-部分更新应用程序配置。只需包含您想要更改的字段。
-
-**请求体：** 部分配置对象。
-
---
-
-## 番剧（动画规则）
-
-### 列出所有番剧
-
-```
-GET /bangumi/get/all
-```
-
-获取所有动画下载规则。
-
-### 通过 ID 获取番剧
-
-```
-GET /bangumi/get/{bangumi_id}
-```
-
-通过 ID 获取特定动画规则。
-
-### 更新番剧
-
-```
-PATCH /bangumi/update/{bangumi_id}
-```
-
-更新动画规则的元数据（标题、季度、集数偏移等）。
-
-### 删除番剧
-
-```
-DELETE /bangumi/delete/{bangumi_id}
-```
-
-删除单个动画规则及其关联的种子。
-
-```
-DELETE /bangumi/delete/many/
-```
-
-批量删除多个动画规则。
-
-**请求体：**
-```json
-{
-  "bangumi_ids": [1, 2, 3]
-}
-```
-
-### 禁用/启用番剧
-
-```
-DELETE /bangumi/disable/{bangumi_id}
-```
-
-禁用动画规则（保留文件，停止下载）。
-
-```
-DELETE /bangumi/disable/many/
-```
-
-批量禁用多个动画规则。
-
-```
-GET /bangumi/enable/{bangumi_id}
-```
-
-重新启用之前禁用的动画规则。
-
-### 刷新海报
-
-```
-GET /bangumi/refresh/poster/all
-```
-
-从 TMDB 刷新所有动画的海报图片。
-
-```
-GET /bangumi/refresh/poster/{bangumi_id}
-```
-
-刷新特定动画的海报图片。
-
-### 日历
-
-```
-GET /bangumi/refresh/calendar
-```
-
-从 Bangumi.tv 刷新动画放送日历数据。
-
-### 重置全部
-
-```
-GET /bangumi/reset/all
-```
-
-删除所有动画规则。请谨慎使用。
-
---
-
-## RSS 订阅源
-
-### 列出所有订阅源
-
-```
-GET /rss
-```
-
-获取所有已配置的 RSS 订阅源。
-
-### 添加订阅源
-
-```
-POST /rss/add
-```
-
-添加新的 RSS 订阅源。
-
-**请求体：**
-```json
-{
-  "url": "string",
-  "aggregate": true,
-  "parser": "mikan"
-}
-```
-
-### 启用/禁用订阅源
-
-```
-POST /rss/enable/many
-```
-
-启用多个 RSS 订阅源。
-
-```
-PATCH /rss/disable/{rss_id}
-```
-
-禁用单个 RSS 订阅源。
-
-```
-POST /rss/disable/many
-```
-
-批量禁用多个 RSS 订阅源。
-
-### 删除订阅源
-
-```
-DELETE /rss/delete/{rss_id}
-```
-
-删除单个 RSS 订阅源。
-
-```
-POST /rss/delete/many
-```
-
-批量删除多个 RSS 订阅源。
-
-### 更新订阅源
-
-```
-PATCH /rss/update/{rss_id}
-```
-
-更新 RSS 订阅源的配置。
-
-### 刷新订阅源
-
-```
-GET /rss/refresh/all
-```
-
-手动触发刷新所有 RSS 订阅源。
-
-```
-GET /rss/refresh/{rss_id}
-```
-
-刷新特定的 RSS 订阅源。
-
-### 获取订阅源中的种子
-
-```
-GET /rss/torrent/{rss_id}
-```
-
-获取从特定 RSS 订阅源解析的种子列表。
-
-### 分析与订阅
-
-```
-POST /rss/analysis
-```
-
-分析 RSS URL 并提取动画元数据，但不订阅。
-
-**请求体：**
-```json
-{
-  "url": "string"
-}
-```
-
-```
-POST /rss/collect
-```
-
-从 RSS 订阅源下载所有剧集（用于已完结动画）。
-
-```
-POST /rss/subscribe
-```
-
-订阅 RSS 订阅源以自动下载连载中的动画。
-
---
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/config/get` | 当前配置，秘密字段已掩码 |
+| `PATCH` | `/config/update` | 保存并重新加载配置；收到掩码的秘密字段保留原值 |
+| `POST` | `/config/llm/models` | 列出所选 LLM 提供商的可用模型 |
+| `GET` | `/config/llm/providers` | LLM 提供商列表 |
+| `POST` | `/config/llm/providers/{provider_id}/install` | 安装 LLM 提供商插件 |
+| `DELETE` | `/config/llm/providers/{provider_id}` | 卸载 LLM 提供商插件 |
+| `POST` | `/config/llm/providers/{provider_id}/auth/begin`、`/auth/complete` | 订阅类提供商的授权流程 |
+| `GET` | `/config/llm/providers/{provider_id}/auth/status` | 授权状态 |
+| `DELETE` | `/config/llm/providers/{provider_id}/auth` | 断开授权 |
+
+## 番剧
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/bangumi/get/all` | 全部番剧规则 |
+| `GET` | `/bangumi/get/{bangumi_id}` | 单个规则 |
+| `PATCH` | `/bangumi/update/{bangumi_id}` | 修改规则 |
+| `DELETE` | `/bangumi/delete/{bangumi_id}` | 删除规则 |
+| `POST` | `/bangumi/delete/many` | 批量删除 |
+| `POST` | `/bangumi/disable/{bangumi_id}`、`/bangumi/enable/{bangumi_id}` | 停用 / 启用规则 |
+| `POST` | `/bangumi/disable/many` | 批量停用 |
+| `PATCH` | `/bangumi/archive/{bangumi_id}`、`/bangumi/unarchive/{bangumi_id}` | 归档 / 取消归档 |
+| `PATCH` | `/bangumi/{bangumi_id}/weekday` | 手动设置放送星期 |
+| `GET` | `/bangumi/refresh/poster/all`、`/bangumi/refresh/poster/{bangumi_id}` | 刷新海报 |
+| `GET` | `/bangumi/refresh/calendar` | 刷新放送日历 |
+| `GET` | `/bangumi/refresh/metadata` | 刷新 TMDB 元数据，并自动归档已完结的番剧 |
+| `POST` | `/bangumi/reset/all` | 删除全部规则 |
+| `GET` | `/bangumi/needs-review` | 需要确认集数偏移的番剧 |
+| `GET` | `/bangumi/suggest-offset/{bangumi_id}` | 根据 TMDB 集数建议偏移 |
+| `POST` | `/bangumi/detect-offset` | 检测季度 / 集数与 TMDB 不一致 |
+| `POST` | `/bangumi/apply-offset/{bangumi_id}`、`/bangumi/apply-offset/many` | 应用建议的偏移并触发一次重命名 |
+| `POST` | `/bangumi/dismiss-review/{bangumi_id}` | 清除「待确认」标记 |
+| `GET` / `DELETE` | `/bangumi/{bangumi_id}/torrents` | 列出 / 删除该番剧的种子记录 |
+| `DELETE` | `/bangumi/{bangumi_id}/torrents/{torrent_id}` | 删除一条种子记录 |
+| `GET` / `DELETE` | `/bangumi/torrents/orphans` | 列出 / 删除不属于任何番剧的种子记录 |
+| `GET` | `/bangumi/torrents/orphans/count` | 孤立种子记录的数量 |
+| `DELETE` | `/bangumi/torrents/orphans/{torrent_id}` | 删除一条孤立种子记录 |
+
+## 电影
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/movie/get/all`、`/movie/get/{movie_id}` | 全部 / 单个电影规则 |
+| `PATCH` | `/movie/update/{movie_id}` | 修改 |
+| `DELETE` | `/movie/delete/{movie_id}` | 删除 |
+| `DELETE` | `/movie/disable/{movie_id}` | 停用 |
+| `GET` | `/movie/enable/{movie_id}` | 启用 |
+
+## RSS 订阅
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/rss` | 全部订阅 |
+| `POST` | `/rss/add` | 添加订阅 |
+| `PATCH` | `/rss/update/{rss_id}` | 修改订阅 |
+| `DELETE` | `/rss/delete/{rss_id}` | 删除订阅 |
+| `POST` | `/rss/delete/many` | 批量删除 |
+| `PATCH` | `/rss/disable/{rss_id}` | 停用 |
+| `POST` | `/rss/disable/many`、`/rss/enable/many` | 批量停用 / 启用 |
+| `POST` | `/rss/refresh/all`、`/rss/refresh/{rss_id}` | 立即刷新 |
+| `GET` | `/rss/torrent/{rss_id}` | 该订阅的种子 |
+| `POST` | `/rss/analysis` | 解析一个 RSS 链接，返回识别出的番剧 |
+| `POST` | `/rss/collect` | 下载整季（收集） |
+| `POST` | `/rss/subscribe` | 订阅 |

 ## 搜索

-### 搜索番剧（Server-Sent Events）
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/search/bangumi?site=<站点>&keywords=<关键词>` | Server-Sent Events，逐条推送搜索结果；多个关键词以空格分隔 |
+| `GET` | `/search/provider` | 可用的搜索站点（含插件提供的站点） |
+| `GET` / `PUT` | `/search/provider/config` | 读取 / 保存用户配置的搜索站点 |

-```
-GET /search/bangumi?keyword={keyword}&provider={provider}
+## 下载器
+
+AB 4.0 可以配置多个下载器实例（`plugins.instances`）。种子列表合并所有实例，每条带 `downloader_id`。
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/downloader/instances` | 下载器实例：`{"default": <默认实例 id>, "instances": [{"id", "provider"}]}` |
+| `GET` | `/downloader/torrents` | 所有实例的种子；不可用的实例跳过 |
+| `POST` | `/downloader/torrents/pause`、`/resume`、`/delete` | 暂停 / 恢复 / 删除种子 |
+| `POST` | `/downloader/torrents/tag` | 给种子打番剧 id 标签 |
+| `POST` | `/downloader/torrents/tag/auto` | 按名称与路径为未打标签的种子自动打标签 |
+| `GET` | `/downloader/rename-conflicts` | 等待用户处理的重命名冲突 |
+| `POST` | `/downloader/rename-conflicts/{operation_id}/retry` | 清除一条冲突，下一轮重命名时重新检查 |
+
+## 通知中心
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` / `DELETE` | `/notification/messages` | 列出 / 清空站内通知 |
+| `GET` | `/notification/messages/unread-count` | 未读数量 |
+| `POST` | `/notification/messages/read-all` | 全部标为已读 |
+| `POST` | `/notification/messages/{message_id}/read` | 标为已读 |
+| `DELETE` | `/notification/messages/{message_id}` | 删除一条 |
+| `POST` | `/notification/test` | 按序号测试已保存的通知渠道 |
+| `POST` | `/notification/test-config` | 测试未保存的通知渠道配置 |
+
+## 事件流
+
+`GET /events/stream` 是一条 Server-Sent Events 连接，WebUI 用它代替轮询。
+
+| `event` | 何时推送 | `data` |
+| --- | --- | --- |
+| `status` | 每 3 秒 | 与 `GET /status` 相同的结构 |
+| `downloader` | 每 5 秒 | 所有实例的种子；下载器不可用时为 `null` |
+| `log` | 每 10 秒 | 日志尾部 |
+| `update` | 在线更新进行中且进度变化时 | 更新进度 |
+| `notification` | 连接建立时，以及通知中心变化时 | 通知中心状态，含未读数 `unread_count` |
+| `bus` | 事件总线上有事件时 | `{"kind": <事件名>, "payload": {...}}`，包括宿主事件和插件事件 |
+
+```bash
+curl -N -H "Authorization: Bearer $AB_TOKEN" http://your-host:7892/api/v1/events/stream
 ```

-搜索动画种子。以 Server-Sent Events (SSE) 流的形式返回结果，提供实时更新。
+`bus` 帧中的事件名与字段见 [插件开发 → 事件](/dev/plugins/events)。前端插件组件用 `host.events.on(kind, callback)` 订阅同样的帧。

-**查询参数：**
- `keyword` — 搜索关键词
- `provider` — 搜索提供者（例如 `mikan`、`nyaa`、`dmhy`）
+## 插件

-**响应：** 包含解析后搜索结果的 SSE 流。
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/plugins` | 已发现的插件、状态、配置表单 schema 与当前配置（已掩码） |
+| `PUT` | `/plugins/settings` | 修改 `allow_unsigned`（允许未签名插件） |
+| `PUT` | `/plugins/{plugin_id}` | 启用 / 停用插件或修改配置，保存后立即生效；配置不合法返回 `422` |
+| `GET` | `/plugins/providers` | 插件提供的 Provider id，按扩展点分组 |
+| `GET` | `/plugins/ui` | 已启用插件声明的前端挂载点 |
+| `GET` | `/plugins/catalog` | 签名目录中可安装的插件；目录不可达返回 `502` |
+| `POST` | `/plugins/{plugin_id}/install` | 从签名目录安装或升级插件，并启用 |
+| `DELETE` | `/plugins/{plugin_id}` | 卸载经签名目录安装的插件 |
+| `GET` | `/plugins/{plugin_id}/web/{path}` | 插件 `web/` 目录下的前端静态文件 |
+| 任意 | `/plugins/{plugin_id}/{path}` | 插件自己的路由，见 [REST 路由](/dev/plugins/points/api-router) |

-### 列出搜索提供者
+## 设置向导

-```
-GET /search/provider
-```
+这些端点不需要认证。`GET /setup/status` 始终可用，返回 `need_setup`（设置完成后为 `false`）。其它端点只在首次设置完成前可用，完成后返回 `403`。`/setup/complete` 还要求浏览器会话，或 `admin` 账户仍为出厂密码 `adminadmin`；否则返回 `403`。

-获取可用搜索提供者的列表。
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `GET` | `/setup/status` | 是否需要设置向导 |
+| `POST` | `/setup/test-downloader` | 测试下载器连接 |
+| `POST` | `/setup/test-rss` | 测试 RSS 链接 |
+| `POST` | `/setup/test-notification` | 发送测试通知 |
+| `POST` | `/setup/complete` | 保存向导中的全部配置，并标记设置完成 |

---
+## MCP

-## 程序控制
+AB 在根路径的 `/mcp` 下提供 MCP 服务（SSE 传输）：客户端连接 `GET /mcp/sse`，并向 `POST /mcp/messages/` 发送消息。

-### 获取状态
+- 访问控制与 REST API 分开：客户端 IP 在 `security.mcp_whitelist` 内，或请求带 `scope=mcp` 的令牌（`Authorization: Bearer <令牌>`）。`mcp_whitelist` 为空时拒绝所有基于 IP 的访问，令牌仍然有效。
+- 内置工具：`list_anime`、`get_anime`、`search_anime`、`subscribe_anime`、`unsubscribe_anime`、`list_downloads`、`list_rss_feeds`、`get_program_status`、`refresh_feeds`、`update_anime`。
+- 内置资源：`autobangumi://anime/list`、`autobangumi://anime/{id}`、`autobangumi://status`、`autobangumi://rss/feeds`。
+- 已启用插件提供的工具名为 `<插件 id>__<id>`，资源 URI 为 `autobangumi://plugins/<插件 id>/<id>`，见 [MCP 工具与资源](/dev/plugins/points/mcp)。

-```
-GET /status
-```
+## 响应与错误

-获取程序状态，包括版本、运行状态和 first_run 标志。
-
-**响应：**
-```json
-{
-  "status": "running",
-  "version": "3.2.0",
-  "first_run": false
-}
-```
-
-### 启动程序
-
-```
-GET /start
-```
-
-启动主程序（RSS 检查、下载、重命名）。
-
-### 重启程序
-
-```
-GET /restart
-```
-
-重启主程序。
-
-### 停止程序
-
-```
-GET /stop
-```
-
-停止主程序（WebUI 仍可访问）。
-
-### 关闭
-
-```
-GET /shutdown
-```
-
-关闭整个应用程序（重启 Docker 容器）。
-
-### 检查下载器
-
-```
-GET /check/downloader
-```
-
-测试与已配置的下载器（qBittorrent）的连接。
-
---
-
-## 下载器管理 <Badge type="tip" text="v3.2+" />
-
-直接从 AutoBangumi 管理下载器中的种子。
-
-### 列出种子
-
-```
-GET /downloader/torrents
-```
-
-获取 Bangumi 分类中的所有种子。
-
-### 暂停种子
-
-```
-POST /downloader/torrents/pause
-```
-
-通过哈希暂停种子。
-
-**请求体：**
-```json
-{
-  "hashes": ["hash1", "hash2"]
-}
-```
-
-### 恢复种子
-
-```
-POST /downloader/torrents/resume
-```
-
-通过哈希恢复已暂停的种子。
-
-**请求体：**
-```json
-{
-  "hashes": ["hash1", "hash2"]
-}
-```
-
-### 删除种子
-
-```
-POST /downloader/torrents/delete
-```
-
-删除种子，可选择是否删除文件。
-
-**请求体：**
-```json
-{
-  "hashes": ["hash1", "hash2"],
-  "delete_files": false
-}
-```
-
---
-
-## 设置向导 <Badge type="tip" text="v3.2+" />
-
-这些端点仅在首次运行设置期间可用（设置完成前）。它们**不**需要认证。设置完成后，所有端点返回 `403 Forbidden`。
-
-### 检查设置状态
-
-```
-GET /setup/status
-```
-
-检查是否需要设置向导（首次运行）。
-
-**响应：**
-```json
-{
-  "need_setup": true
-}
-```
-
-### 测试下载器连接
-
-```
-POST /setup/test-downloader
-```
-
-使用提供的凭据测试与下载器的连接。
-
-**请求体：**
-```json
-{
-  "type": "qbittorrent",
-  "host": "172.17.0.1:8080",
-  "username": "admin",
-  "password": "adminadmin",
-  "ssl": false
-}
-```
-
-### 测试 RSS 订阅源
-
-```
-POST /setup/test-rss
-```
-
-验证 RSS 订阅源 URL 是否可访问和可解析。
-
-**请求体：**
-```json
-{
-  "url": "https://mikanime.tv/RSS/MyBangumi?token=xxx"
-}
-```
-
-### 测试通知
-
-```
-POST /setup/test-notification
-```
-
-使用提供的设置发送测试通知。
-
-**请求体：**
-```json
-{
-  "type": "telegram",
-  "token": "bot_token",
-  "chat_id": "chat_id"
-}
-```
-
-### 完成设置
-
-```
-POST /setup/complete
-```
-
-保存所有配置并将设置标记为完成。创建标记文件 `config/.setup_complete`。
-
-**请求体：** 完整配置对象。
-
---
-
-## 日志
-
-### 获取日志
-
-```
-GET /log
-```
-
-获取完整的应用程序日志文件。
-
-### 清除日志
-
-```
-GET /log/clear
-```
-
-清除日志文件。
-
---
-
-## 响应格式
-
-所有 API 响应遵循统一格式：
-
-```json
-{
-  "msg_en": "Success message in English",
-  "msg_zh": "成功消息（中文）",
-  "status": true
-}
-```
-
-错误响应包含适当的 HTTP 状态码（400、401、403、404、500）以及中英文错误消息。
+- 许多操作类端点返回 `{"status": true, "msg_en": "...", "msg_zh": "..."}`。查询类端点直接返回数据。具体结构见 `/docs`。
+- 错误使用标准 HTTP 状态码：`401` 未认证，`403` 无权限，`404` 不存在，`422` 参数校验失败，`500` 服务器错误。