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}/{季}）；6 小時內查過的用記下的，不再問。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}），挑出中文名。見媒體庫與掃描。