MoviePilot 集成 - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

Mi302 不自己刮削，这件事交给 MoviePilot。本页说明如何连接 MoviePilot、哪些视频会送去刮削、补全缺集如何判断缺哪几集、整理 115 网盘要 MoviePilot 做什么、怎么清掉 qBittorrent 里没速度的种子，以及如何让 MoviePilot 把 Mi302 当作 Emby 媒体服务器。

Mi302 是按 MoviePilot V3 开发的。旧版大多能用，但有几项功能会打折扣，见旧版 MoviePilot。

管理页面的“MoviePilot”页上方有“连线”“刮削”“补全缺集”“qBittorrent”“当成 Emby”五个按钮，点哪个就只显示那张卡片（“当成 Emby”是“让 MoviePilot 把 Mi302 当成 Emby”卡片），下次打开这一页会回到上次看的那个。

工作方式

Mi302 只读取文件夹里已有的 nfo 和图片。这些数据可以在 115 同步时一并下载（见115 网盘与同步），或交给 MoviePilot 刮削：

同步生成新的 strm 后，Mi302 先扫描有变动的地方，新片马上出现在播放器里（这时还没有海报）。
Mi302 把新 strm 的路径发给 MoviePilot 的刮削 API（POST /api/v1/media/scrape/local）。
MoviePilot 识别视频，到 TMDB 等来源查询数据，把 nfo、海报、背景图写进同一个文件夹。
刮削完成后，Mi302 只重新扫描刮削过的地方，播放器就能看到海报和简介。

所以 MoviePilot 和 Mi302 要能看到同一批文件，例如装在同一台机器上，或挂载同一个网络硬盘。

连接设置

设置在“MoviePilot”页的“连线”卡片。

在 MoviePilot 的“设定 → 系统”复制 API 令牌。
在 Mi302 填写“MoviePilot 网址”（例如 http://192.168.1.10:3000，要以 http:// 或 https:// 开头）和“API 令牌”。本地安装（不是 Docker）的 MoviePilot，前端 3000 端口在后端很忙时会自己停掉，建议直接填后端的 3001 端口。
两边看到的路径不一样时，填写“路径对应”，见下一节。
点“测试连线”。它会先保存，再测试。

“测试连线”只检查网址和 API 令牌。它发一个空路径给刮削 API，MoviePilot 会返回“刮削路径无效”，所以不会真的刮削。路径对应是否正确，要看第一次刮削的结果。卡片右上角平时显示“已设定”或“未设定”，测试后显示“连线成功”或“连线失败”。

页面上的名称	配置键	默认值	说明
MoviePilot 网址	`moviepilot.url`	空	末尾的 `/` 会去掉
API 令牌	`moviepilot.api_token`	空	放在 `X-API-KEY` 请求头发送（不放网址，免得留在代理、MoviePilot 的访问日志）；被拒时才带 `token` 查询参数再试一次，给只认它的旧版
同时刮削几项	`moviepilot.concurrency`	3	1–8
路径对应	`moviepilot.path_mappings`	无	见下一节
同步产生新的 strm 后自动送去刮削	`moviepilot.scrape_after_sync`	开	在“刮削”卡片，切换后马上储存；关闭时同步完只扫描
MoviePilot 帐号、MoviePilot 密码	`moviepilot.username`、`moviepilot.password`	空	补全缺集、整理 115 网盘需要；旧版刮削 API 也需要
全量同步后自动补全	`moviepilot.fill_after_full_sync`	关	在“补全缺集”卡片的“设定”里，切换后立即保存
两个新订阅之间隔几秒	`moviepilot.fill_interval`	`60`	在“补全缺集”卡片的“设定”里，点“储存设定”；0 = 不隔
缺超过几集的季不补	`moviepilot.fill_max_missing`	`0`	在“补全缺集”卡片的“设定”里，点“储存设定”；0 = 不限
（只在配置文件）	`moviepilot.timeout`	300	每一项最多等几秒；超时当作连接失败，这一批停下

什么时候要填账号密码

账号密码在“连线”卡片里折叠起来的“MoviePilot 帐号密码（V3 不用填；旧版才需要）”，点一下展开。

MoviePilot V3：刮削、补全缺集、整理 115 网盘用到的 API 都接受 API 令牌（令牌代表 MoviePilot 的管理员），不用填账号密码。
旧版 MoviePilot（V2）：有些 API 只接受账号登录。“测试连线”、补全或整理时出现“拒绝存取”，就填写账号密码；整理 115 网盘要用管理员账号。

填了账号密码时，MoviePilot 返回 401 或 403，Mi302 会用账号密码登录（POST /api/v1/login/access-token）再试一次，之后都用登录拿到的 token；token 过期会自动重新登录。只填网址和账号密码、不填 API 令牌也可以。

路径对应

Mi302 发给 MoviePilot 的是 Mi302 看到的文件路径。两边看到的路径一样（例如装在同一台机器上）就不用填。不一样时，在“路径对应”里一行填一条：

Mi302 的路径 => MoviePilot 的路径

例子：

Mi302 在 Parallels 虚拟机里看到 /media/psf/Vo，MoviePilot 装在 Mac 上看到 /Volumes/Vo：填 /media/psf/Vo => /Volumes/Vo。
MoviePilot 用 Docker：看它容器里的挂载路径。主机的 /volume1/media 挂载成 /mnt/media，就填 /volume1/media => /mnt/media。

规则：

按路径开头的完整文件夹匹配，多条都符合时用最长的那条。
反方向也用同一组规则：MoviePilot 通知 Mi302 重新扫描时发来的是 MoviePilot 的路径，Mi302 会换回自己的路径。
MoviePilot 返回文件不存在时，“刮削”卡片的错误里会写“MoviePilot 找不到 …，请检查路径对应”，后面是它收到的路径。

配置文件里的写法：

moviepilot:
  path_mappings:
    - from: /media/psf/Vo
      to: /Volumes/Vo

发送规则

同步后自动发送的只有这次新生成的 strm。点“刮削”卡片的“刮削缺少资料的项目”时，检查整个媒体库。两种都按这些规则决定发送什么：

电影：发送 strm 文件本身。已经有同名 nfo（X.nfo），或电影放在自己的文件夹、里面有 movie.nfo 的不发送。
剧集：整部剧还没有 tvshow.nfo 时，发送整个剧集文件夹，一次处理剧、季、集。已经有 tvshow.nfo 的剧，只发送没有 nfo 的那几集。
已经有 nfo 的不发送，避免覆盖从 115 带下来或之前刮削好的数据。
点“刮削缺少资料的项目”时，有 nfo 却没有剧照的集也会再发送一次（30 天内确定没有剧照的除外，见下文）。
连接失败、认证失败、MoviePilot 返回 HTTP 错误或超时，整批停下，还没发送的算失败，原因显示在“刮削”卡片上。

剧集文件夹的判断和扫描时一样，媒体库下面可以有分类文件夹（见媒体库与扫描）。例如媒体库路径选 电视剧、下面是 国产剧/庆余年 (2019)/Season 1/…，发送的是 庆余年 (2019) 这部剧，tmdbid 也从它的 tvshow.nfo 取。

刮削速度

MoviePilot 的刮削 API 是同步的：每一项都要等它到 TMDB 查询数据、下载图片才响应，一部片可能要几十秒。Mi302 这样加速：

同时发送多项：“同时刮削几项”默认 3，最多 8。太多时 TMDB 可能限速；MoviePilot 日志出现 429 就调低。
已经刮削过的剧带上 tmdbid：发送单集时，Mi302 从剧的 tvshow.nfo 取出 tmdbid，直接告诉 MoviePilot 是哪一部（media_source=themoviedb&media_id=…）。MoviePilot 不必再用文件名搜索 TMDB，也不会认错。这需要 MoviePilot V3；旧版会忽略这些参数，照常用文件名识别。

MoviePilot 本身慢的话，多半是连接 TMDB 慢：在 MoviePilot 设置 TMDB 的 API 地址和图片地址代理。

刮削结果

“刮削”卡片显示上次刮削（同步后自动或手动）的数字：送出、成功、失败、没有剧照。

刮削中可以点“停止”：已经发给 MoviePilot 的会做完，还没发的不发，下次刮削再发。

MoviePilot 报告完成后，Mi302 会检查它有没有真的写出 nfo：

发送单个文件时看 X.nfo，发送剧集文件夹时看 tvshow.nfo。没写出来就算失败。
MoviePilot 认不出集数时什么都不写，却报告完成。这种集会记为失败，并说明原因：文件名要有 S01E01 这类集号。
剧集的一集有 nfo、没有剧照时算成功，另外计入“没有剧照”。

单集没有剧照

MoviePilot 的单集图片只来自 TMDB 那一集的剧照，保存为和视频同名的 X.jpg（Mi302 也认 X-thumb.jpg）。没有图片通常是因为：

TMDB 没有这集的剧照：国产剧、综艺、刚播出的集很常见，MoviePilot 也写不出来。这种集 Mi302 改用剧的横幅图（thumb、landscape），没有就用背景图，播放器不会一片空白。
MoviePilot 下载图片失败：MoviePilot 日志有“图片下载失败”，多半是连不上 image.tmdb.org，要在 MoviePilot 设置 TMDB 图片代理。修好之后点“刮削缺少资料的项目”，有 nfo 却没有剧照的集会再发送一次。

发送过、确定没有剧照的集，30 天内点“刮削缺少资料的项目”不再重发。

补全缺集

媒体库里的剧少了几集时，可以让 MoviePilot 去下载补齐。设置在“MoviePilot”页的“补全缺集”卡片。

准备工作

把 Mi302 加为 MoviePilot 的媒体服务器（见下文“让 MoviePilot 把 Mi302 当作 Emby”），MoviePilot 才知道哪些集已经有了。
在“连线”卡片填好 MoviePilot 网址和 API 令牌并保存（旧版 MoviePilot 不接受令牌时再填账号密码）。
剧要先刮削过，tvshow.nfo 里有 tmdbid。没有 tmdbid 的剧不会发送。

卡片上的剧集列表

“补全缺集”卡片把媒体库里的剧按“接下来要做什么”分成几页，每一页标着有几部：

分页	里面是什么	可以做什么
缺集	对照过 TMDB、真的缺集，而且还没订阅	每一部的“補全”，或分页右边的“補全這 N 部”
處理中	缺集的季都交给 MoviePilot 了：还订阅着（它还在找资源），或已经送去下载、等入库	通常不用做什么；下载失败时点“再補一次”
季號對不上	都对照过了，媒体库有、TMDB 上却没有的季（例如 TMDB 把几季合成一季），MoviePilot 订阅不了（还有季没对照的先在“還沒對照”）；没有这种剧时不显示这一页	“去整理”：把剧集文件夹加进“115 網盤 → 整理 115 網盤”列表最上面；预览时在对不上的那一季指定 TMDB 的季号（或集数定位）再整理
還沒對照	新加的剧、新的季，还没对照过 TMDB；没有 tmdbid 的剧也在这里（要先刮削）	每一部的“檢查”，或“檢查這 N 部”
不補	你标了“不補”的剧	“恢復補全”
全部	所有的剧，齐全的标“齊全”

卡片右上角的“檢查缺集”（对照过之后叫“重新檢查”；“還沒對照”分页不显示，改用列表上方的“檢查這 N 部”，只查还没对照的）把每一季向 MoviePilot 查一次 TMDB 已播出的集，只记下缺哪几集，不建订阅、不下载；只要填了 API 令牌就能用。6 小时内查过的季不再查。补全时查到的也会一起记下。媒体库之后多了、少了集，列表当场重算，不用重查。
缺集的季各占一行：“有 N 集・TMDB 已播出 M 集”、缺几集、缺哪几集，MoviePilot 在处理的标“已訂閱”或“已送下載・多久以前”（见下面）。没有空洞的季也可能缺前面或后面几集，对照过才知道。还没对照的季只看得出集号的空洞（例如有第 2、4 集，没有第 3 集）。
“補全這 N 部”只发送“缺集”那一页的剧：MoviePilot 已经在处理的、标了“不補”的、齐全的都不发送，会先确认一次。
“已訂閱”和“已送下載”：MoviePilot 找到资源、交给下载器之后，会把那个订阅记成完成、从订阅列表移到订阅历史，这时集还在下载、还没整理进媒体库。Mi302 把这种季标成“已送下載”，和还订阅着的一起放在“處理中”，补全（手动、全部、全量同步后自动）都不会重复订阅。下载完、整理进媒体库、同步之后就不缺了，剧会从这一页消失。
送去下载超过 3 天还没入库的（下载失败、种子被删了），会回到“缺集”，可以再补。不想等的话点那一部右边的“再補一次”，马上再订阅一次、请 MoviePilot 重新搜索。送下载之后才播出的新集不算在那一次里，照样列在“缺集”。
“處理中”要读取 MoviePilot 的订阅列表和订阅历史；读不到时（连不上、被拒绝）没有这一页，缺集的都在“缺集”。
在“搜尋劇名”里输入即可搜索，片名、原名、年份、拼音、首字母都能识别。旁边的“全部媒體庫”下拉菜单可以只看某一个媒体库的剧（例如国产剧、国漫；剧集媒体库只有一个时不显示），“全部年份”可以只看某一年的剧，三个可以一起用。
筛选出什么，按钮就只处理什么：搜索、选了媒体库或年份之后，每个分页上的数字只算筛选出来的；“補全這 N 部”“檢查這 N 部”只处理筛选出来的，右上角的按钮也改成“檢查這 N 部”（对照过之后是“重新檢查這 N 部”），确认框会写明范围。例如年份选 2026 再按“補全這 N 部”，就只补 2026 年缺集的剧；媒体库选国漫再按“檢查這 N 部”，就只检查国漫。
一页放不下时，列表下方可以翻页、选每页 20、50、100 或 200 部，浏览器会记住。搜索、换媒体库、换年份或换分页时回到第 1 页。
不想补的剧点右边的“不補”：之后检查、手动补全、全量同步后自动补全都跳过它，移到“不補”那一页；再点“恢復補全”就取消。按 tmdbid 记在 Mi302 的数据库里，重新扫描、改文件夹名都还在。
检查、补全中卡片上方显示进度，可以点“停止”：做完手上这一季就停，已经建好的订阅保留。做完后显示一行结果，每一季的细节可以展开。
特别篇（第 0 季）不列出、不发送。

“檢查缺集”和补全用的是同一套判断（见下面），只是不建订阅。标了“不補”的剧、没有 tmdbid 的剧不检查。

每一季怎么判断

补全按季逐一处理，只处理媒体库里已经有集的季。TMDB 上有、媒体库整季都没有的季不会自动订阅。

向 MoviePilot 查询 TMDB 上这一季的集和播出日期（GET /api/v1/tmdb/{tmdbid}/{季}）。TMDB 上没有这一季时（MoviePilot 返回空列表，Mi302 再查一次这部剧有哪几季确认，TMDB 临时出错不算），不建订阅：MoviePilot 查不到这一季的总集数，一定会拒绝（“未获取到第 N 季的总集数”）。记为“TMDB 没有”，列表上移到“季號對不上”。
判断哪些集已经播出：
- 有播出日期的，日期不晚于今天（Mi302 主机的日期）就算播过。
- 没有日期的常是还没播的占位集。集号不超过媒体库里这一季最后一集的算播过（都有第 10 集了，第 3 集一定播过）。
- 在最后一集之后、又没有日期的不确定，不算缺。结果里会注明有几集 TMDB 没有播出日期、没有计入。
对照 Mi302 里这一季已有的集号。已播出的都有，就不建订阅，记为“已经齐全”。
缺的集数超过“设定”里的“缺超过几集的季不补”（默认 0 = 不限）时不建订阅，记为“缺太多不补”，结果里写明缺几集。适合只收了几集的长篇动画、只想要其中几集的综艺这类，不会一口气订阅几百集。
缺集才建订阅（POST /api/v1/subscribe/），用 tmdbid 指定是哪一部（V3 的 media_source／media_id），不靠剧名，不会认错。
新建的订阅，立即请 MoviePilot 搜索（POST /api/v1/subscribe/search/{订阅 id}）。MoviePilot V3 建订阅后只是安排搜索，有时要等到定时搜索才开始。这一步失败时，结果里会注明，MoviePilot 会在定时搜索时处理。
MoviePilot 已经在处理的季（还订阅着的、3 天内送去下载还没入库的）不重复订阅；还订阅着的 MoviePilot 自己会定时搜索（默认每 24 小时）。

不一口气发送：每个新订阅都会让 MoviePilot 把所有站点搜一遍。它对同一个站点一次只搜一个，但搜完马上接下一个，中间不停；一口气建几百个订阅，站点会被连续请求、被 Cloudflare 拦截。所以两个新订阅之间隔开，默认 60 秒（“设定”里的“两个新订阅之间隔几秒”，0 = 不隔），等待时卡片上会显示。只有新建的才要等，已经齐全、之前就订阅过的不用。第一次补全很多剧时会跑比较久（例如 100 个新订阅大约 100 分钟），在后台进行，可以关掉网页。

连不上、出错而查不到 TMDB 的集数时，照样建订阅，交给 MoviePilot 判断（算不出缺几集，“缺超过几集的季不补”也管不到）。

MoviePilot 下载、整理完会通知 Mi302 重新扫描。缺集的季如果还在更新，订阅会继续追新集。

取消所有订阅

补全建了太多不想要的订阅、想清掉重来时，展开卡片下方的“MoviePilot 的訂閱”（标题上写着现在有几个），点“取消所有訂閱…”：

先显示 MoviePilot 里现在有几个订阅（电视剧几个、电影等其他几个），要输入“取消訂閱”才会开始。电视剧和电影的订阅都会取消，不只是 Mi302 建的。
在后台一个一个取消（DELETE /api/v1/subscribe/{订阅 id}），卡片上能看到进度，可以点“停止”：已经取消的不会回来，还没取消的保留。
只删订阅。已经下载、整理好的文件不动；取消之后 MoviePilot 不再替它们搜索、追新集。
取消前的订阅列表（名称、年份、类型、季、tmdbid）Mi302 留一份：做完后卡片上有“下載（JSON）”，取消错了可以按它重新订阅。
和检查缺集、补全不同时运行。用 API 令牌或管理员账号时，能看到、取消的是所有人的订阅。

结果

卡片上的数字：

名称	含义
建订阅并搜寻	有缺集、建了订阅并请 MoviePilot 搜索的季数
缺的集数	所有季缺的集数合计
已经齐全	已播出的集都有、没建订阅的季数；旧版 MoviePilot 以“媒体库中已存在”拒绝时也算在这里
之前订阅过	MoviePilot 里已经有订阅、没有重复订阅的季数
已送下载	MoviePilot 已经找到资源、送去下载，还没入库，没有重复订阅的季数
没 tmdbid	没有 tmdbid 而跳过的剧数
缺太多不补	缺的集数超过“缺超过几集的季不补”、没建订阅的季数
TMDB 没有	TMDB 上没有这一季（季号对不上）、没建订阅的季数
标了不补	标了“不补”而跳过的剧数
失败	MoviePilot 不接受订阅，或中途停下后没做的季数

展开“每一季的结果（N）”可以看每一季缺哪几集、MoviePilot 怎么回复。连接或认证失败时整批停下，剩下的季算失败。同一时间只运行一批补全；已经在运行时再点，会提示“已经在补全中，等它做完”。

全量同步后自动补全

勾选“全量同步后自动补全”（默认关闭，切换后立即保存）时，每次全量同步、刮削完之后，自动把所有有 tmdbid 的剧发送一次。没设置 MoviePilot 时不做。等刮削完才做，是因为新刮削的剧到这时才有 tmdbid。标了“不补”的剧、缺太多的季同样跳过。

qBittorrent 没速度的种子

MoviePilot 订阅到的种子交给 qBittorrent 下载。qBittorrent 开了队列（限制同时下载几个）时，没人做种、速度一直是 0 的种子照样占着名额，排在后面的一直轮不到。Mi302 可以连接 qBittorrent，把这种种子删掉，让排在后面的接着开始。

在“MoviePilot”页点“qBittorrent”：

填 WebUI 地址（例如 http://127.0.0.1:8080），点“储存”，再点“测试连线”。qBittorrent 和 Mi302 装在同一台、WebUI 设置了本机跳过身份验证时，账号密码不用填；否则填 WebUI 的账号密码。
打开“自动删掉太久没速度的种子”（默认关闭，打开前会再确认一次）。

怎么判断：

每 5 分钟读一次种子列表。只看正在下载、还没下载完的（下载中、等待、获取元数据、强制下载）；排队、暂停、校验中、做种、下载完的都不动。
从 Mi302 看到它在下载开始算，平均速度一直不超过“平均速度不超过几 KB/s 算没速度”（默认 0：完全没下载到东西才算），连续“连续几分钟没速度就删”（默认 60 分钟，10–10080）就删掉。中间有速度了就从头算。
排队、暂停的时间不算：排了好几天才轮到的种子，从开始下载才算，不会一轮到就被删。qBittorrent 自己的“最后活动时间”分不出这个，所以不用它。
没速度多久只记在内存里：Mi302 重启、连不上 qBittorrent 之后，都从头算。
默认连同下载到一半的文件一起删；关掉“连同下载到一半的文件一起删”的话只从 qBittorrent 移除，文件留在下载目录。
打开“只删做种数为 0 的”时，tracker 报告还有人做种的先不删，只列出来等（卡片上写“還有人做種，先不刪”）；做种数降到 0 又还是没速度才删。tracker 没报告做种数时当成 0。注意 PT 站常有“有人做种却连不上”的情况，这种照样会一直卡着。
删掉几个，就接着开始排在后面的几个（按队列顺序；没开队列时按添加的先后）。在队列里排队的，qBittorrent 空出名额自己会开始；暂停的由 Mi302 让它开始。
“随时要有几个种子在下载”（默认 0 = 不管）：有速度的不够这么多，就按队列顺序把排队的强制开始（强制开始不受 qBittorrent 的队列上限限制，所以就算队列被死种占满也开得了），排队的用完就不开。强制开始后过了“强制开始后几秒内没速度就删”（默认 30 秒）还没下载到东西：tracker 有正常响应的，就是种子有问题，删掉；tracker 没响应（站点挂了、被 Cloudflare 挡）或打开了“只删做种数为 0 的”又还有人做种的，只取消强制、放回队列，一小时内不再试它，免得 tracker 一断就把整条队列删光。有速度了就按一般的规则看。

卡片上列出现在没速度的种子、没速度多久、再过多久会删。“现在看一次”马上检查一次（开了自动删除时，够久的照样会删）。展开“最近删掉的”看删了哪些：什么时候、没速度多久、下载了多少、文件有没有一起删，日志也各记一行。

MoviePilot 把种子交给 qBittorrent 时，就当那几集已经送去下载，种子被删它不知道。送去下载超过 3 天还没入库的季会回到“缺集”，可以再补；想早点补就点那一部的“再補一次”，见卡片上的剧集列表。

整理 115 网盘

集号不对的剧、命名不按 MoviePilot 格式的文件夹，都在“115 网盘”页的“整理 115 网盘”卡片整理或删除，见 115 网盘与同步。和 MoviePilot 有关的：

MoviePilot 要 v2.11.1-1 以上。更旧的版本不支持预览，“预览”会变成真的整理，所以 Mi302 预览前先查版本（GET /api/v1/system/env），太旧或查不到都不发送。
“连线”卡片设置好 MoviePilot。V3 用 API 令牌就够；旧版的查询整理后名称、手动整理、推荐集数定位和查版本的 API 只接受账号登录，要填管理员账号密码。
MoviePilot 的 115 网盘（存储）要登录和 Mi302 同一个 115 账号。Mi302 发送的是 115 上的文件夹、文件 id，MoviePilot 靠它移动文件。
用到的 API：GET /api/v1/transfer/name（整理后叫什么）、POST /api/v1/transfer/manual（预览和执行；一个文件夹发送一个 fileitem，和 MoviePilot 网页“文件管理 → 整理”一样）、POST /api/v1/transfer/episode-format/recommend（推荐集数定位）、GET /api/v1/storage/directories（目录设置；V2 是 /api/v1/system/setting/Directories）、POST /api/v1/transfer/manual/target-path（它自己会整理到哪个目录）、POST /api/v1/transfer/manual/history（有没有整理记录）。
发送时它整理对话框的“按类型分类”“按类别分类”“刮削元数据”“复用历史识别信息”都关掉，整理方式是移动：MoviePilot 只用自己的重命名格式改文件夹和文件名。已经在它媒体库目录里的，“照 MoviePilot 的目录设定”也留在原来的分类文件夹（见 115 网盘与同步）。整理到指定的文件夹、对不上目录设置时，已有的文件不覆盖。

Mi302 整理助手插件

“整理 115 网盘”里很多文件夹结构已经对、只是名字不按格式，例如 H-画江湖之天罡-2023-[tmdb=1221210] 要改成 画江湖之天罡 (2023) {tmdbid=1221210}、Season 1 改成 Season 01、文件名改成 MoviePilot 的格式。这种其实每个文件、文件夹改一次名就好。MoviePilot 的整理流程一个文件要查来源、查目标、移动、再查、改名，大约 7～8 个 115 请求，它每秒最多 3 个，一部 265 集的剧要十几分钟。

Mi302 仓库里的 moviepilot-plugin/ 是一个 MoviePilot V3 插件“Mi302 整理助手”。装好、启用后，Mi302 预览时看出只需要改名的文件夹，会把改名清单交给它；它用 MoviePilot 自己的 115 授权直接改名，一个文件一个请求，限速和被 115 限流时的冷却都和 MoviePilot 共用。要搬位置、加一层季文件夹、并进旁边已经有的文件夹的，照常走 MoviePilot 的整理。

1.1.0 起插件也会算名字：预览时（整理到哪里已经定了：已经在媒体库目录里、“同一层”或指定的文件夹），Mi302 把这一部分的文件清单交给它，它调用 MoviePilot 自己算名字的那几个函数（解析文件名、按 TMDB 编号识别、沿用整理记录里的片名、查这一季的集信息、套重命名格式、字幕加语言标记），名字和 MoviePilot 整理的一模一样，但不跑它整套整理预览（不抓图、不匹配目录设置），同一部片只识别一次。几百集的文件夹从几分钟变成几秒，MoviePilot 也不会因为预览吃掉几 GB 内存。认不出来的文件原因也更清楚（例如“未识别到文件集数”，而不是只有“整理任务处理失败”）。插件是旧版、或算名字出错时，那一部分改用 MoviePilot 的整理预览，预览上会写明；让 MoviePilot 自己挑目录的也照常用它的预览。真的要移动位置的照常交给 MoviePilot 整理，它整理时算的名字和预览一样。

安装（MoviePilot V3），两种方式二选一：

从插件市场装：MoviePilot“设置 → 系统 → 插件市场”加一行 https://github.com/MiCat-S/Mi302-MoviePilot-Plugins，保存后到“插件”页，市场里就会出现 Mi302 的两个插件（整理助手、清种助手），之后有新版也在市场里更新。这个仓库是 Mi302 仓库 moviepilot-plugin/ 的镜像（MoviePilot 只读仓库根目录的 package.v3.json，所以要另外一个仓库）。

用本机路径装（和 Mi302 同一台、想跟着 Mi302 一起更新时）：

让 MoviePilot 看得到 moviepilot-plugin 这个文件夹。和 Mi302 装在同一台机器时，就是 Mi302 安装目录下的 moviepilot-plugin，例如 /root/Mi302/moviepilot-plugin；不在同一台的话把这个文件夹复制过去。
在 MoviePilot 配置目录里的 app.env 加一行 PLUGIN_LOCAL_REPO_PATHS=/root/Mi302/moviepilot-plugin（换成你的路径），重启 MoviePilot。路径一定要存在，不然 MoviePilot 启动时所有插件都加载不了。
MoviePilot 的插件市场会出现“Mi302 整理助手”。安装后打开“启用”并保存。
Mi302“整理 115 网盘”卡片的“用 MoviePilot 的「Mi302 整理助手」外掛算名字、改名”保持打开（默认开）。之后预览只需要改名的文件夹时，会写“只需要改名：交给 MoviePilot 的「Mi302 整理助手」直接改 N 个档案、M 个资料夹的名字”。

Mi302 更新后插件有新版本时，到 MoviePilot 的插件市场更新或重新安装（例如 1.0.0 → 1.1.0 才会算名字；没更新的话 Mi302 照常用 MoviePilot 的整理预览）。1.2.0 起插件启用后会先检查这版 MoviePilot 还有没有它算名字要用的内部函数（MoviePilot 改版时可能去掉）；缺了就不算名字，Mi302 改用整理预览，预览的说明会写“Mi302 整理助手和這版 MoviePilot 對不上”，缺了什么写在 MoviePilot 的日志。

细节：

什么时候算“只需要改名”：每个要发送的文件，新位置和旧位置的文件夹层数一样，每个旧文件夹对应唯一一个新名字，新名字也不会和旁边已经有的文件夹、留在原处的文件重名。没有自己文件夹的电影、视频直接放在剧的文件夹里（要加一层季文件夹）的都不算。
改名的顺序：先文件（视频、字幕、音轨），再里面的文件夹，最后外面的。中途失败或停止时，已经改好的保留；再预览一次，改好的会算“已经按格式命名”，从还没改的接着做。
用插件改名不会写进 MoviePilot 的整理记录。改名后 Mi302 的增量同步按 115 的生活事件，把本地的 strm 跟着搬。
插件的接口在 /api/v1/plugin/Mi302Organizer/（status、names、rename、job、cancel），用 MoviePilot 的账号登录或 API 令牌。它只按 Mi302 发来的清单改，不会自己去改任何东西。
遇到 115 限流（429）时，MoviePilot 会把所有 115 操作停一小时，插件的改名也跟着等。

Mi302 清种助手插件

qBittorrent 没速度的种子那一套规则也做成了 MoviePilot V3 插件“Mi302 清种助手”，和“Mi302 整理助手”在同一个 moviepilot-plugin/ 目录里（安装方式同上，插件市场里会多一个）。区别：

插件直接用 MoviePilot 里设置好的 qBittorrent 下载器，不用再填地址账号密码；有多个下载器时可以选要管哪几个（不选 = 全部 qBittorrent）。
定时交给 MoviePilot 的调度（“几分钟看一次”，默认 5），强制开始后几秒回来看照样会做；“立即看一次”马上跑一轮。
默认只看带 MOVIEPILOT 标签的种子（MoviePilot 自己加的），手动添加的不会被动到；清空标签就是全部。
删掉时可以发 MoviePilot 的通知。插件详情页列出每个下载器上一轮看到的、现在没速度的种子和最近删掉的。
其他选项（连续几分钟没速度就删、平均速度阈值、连同文件、只删做种数为 0 的、随时要有几个在下载、强制开始后几秒内没速度就删）和 Mi302 本体一样，判断规则也一样。

Mi302 本体的“MoviePilot → qBittorrent”和这个插件二选一打开就好；两边都开会抢着删同一个种子，没速度的时间也各算各的。

让 MoviePilot 把 Mi302 当作 Emby

MoviePilot 可以把 Mi302 加为媒体服务器，用来判断片子是否已经有了，整理完自动通知 Mi302 重新扫描。

在 Mi302“MoviePilot”页的“让 MoviePilot 把 Mi302 当成 Emby”卡片，输入用途（例如 MoviePilot，不填就叫 MoviePilot），点“建立 API 金钥”。在列表里点复制图标复制密钥。
在 MoviePilot 的“设定 → 媒体服务器”新增 Emby。地址填卡片上显示的“地址”（就是你打开管理页面用的网址，例如 http://192.168.1.20:8096），API 密钥粘贴刚才那把。MoviePilot 要能访问这个地址。

API 密钥以管理员身份调用 Emby API，但不能用来操作管理页面。不用了可以在列表里删除；用这把密钥的程序会连不上。

MoviePilot 通知 Mi302 某些文件有变动时（POST /Library/Media/Updated），Mi302 按“路径对应”把路径换回自己的路径，只扫描这些文件所在的电影或剧，不重新扫描整个媒体库。通知里没有路径时，才扫描整个媒体库。

媒体库封面

播放器首页每个媒体库的封面，可以用 MoviePilot 的媒体库封面插件生成，例如 wio-ki/MoviePilot-Plugins 的“Emby媒体库封面生成”：

先按上一节把 Mi302 加为 MoviePilot 的 Emby 媒体服务器。
安装插件，在插件设置的媒体服务器里选 Mi302，选择要生成封面的媒体库。
在插件里手动运行一次，或设置定时任务（例如每天一次）。

插件从媒体库里随机挑选海报组成封面，再上传到 Mi302（POST /Items/{id}/Images/Primary）。上传的封面：

保存在数据目录（server.data_dir）的 images/ 里，重新扫描不会被覆盖，也比媒体库文件夹里的 poster／folder／cover 图优先。
在“媒体库”页能看到。也可以点“上传封面”自己上传，或点“改回预设”删除上传的封面。见媒体库与扫描。

插件的“入库监控”要 MoviePilot 整理完成或 Emby 的新增通知才会触发。Mi302 从 115 同步进来的文件不经过这两者，所以新片进来后封面不会自动更新，请用定时任务或手动更新。

旧版 MoviePilot

Mi302 是按 MoviePilot V3 开发的。在旧版（例如 V2）上：

刮削、建订阅、手动整理这些 API 可能不接受 API 令牌：出现“拒绝存取”时要填账号密码。
刮削时带的 tmdbid 参数会被忽略，照常用文件名识别，比较慢，也可能认错。
建订阅：旧版认 tmdbid 字段，V3 认 media_source／media_id，Mi302 两种都发。旧版遇到媒体库已有的会拒绝（“媒体库中已存在”），Mi302 记为“已经齐全”。
请 MoviePilot 搜索订阅：V3 用 POST，旧版用 GET。收到 HTTP 405 时，Mi302 改用 GET 再试。
查询 TMDB 集数：V3 和旧版返回的格式不同，两种都能识别。
整理 115 网盘：手动整理的预览从 v2.11.1-1 开始，更旧的不发送（见整理 115 网盘）。推荐集数定位是 V3 才有的，旧版推荐不出来，改用 Mi302 从文件名看的，或自己填。
遇到 MoviePilot 没有的 API（HTTP 404），Mi302 会显示“MoviePilot 没有这个 API（…），请确认网址或升级 MoviePilot”。

其他用到 MoviePilot 的地方

“演职人员显示中文名”开启时，Mi302 通过 MoviePilot 查询 TMDB 人物的别名（GET /api/v1/tmdb/person/{id}），挑出中文名。见媒体库与扫描。