整理入库 1.0 预览版

pt-tools 能把下载完的电影与剧集放进媒体库：先识别出是哪部片，再按媒体库的命名模板放到库目录里（默认用硬链接，不多占空间，种子照常做种），写好 NFO 与海报，通知 Emby、Jellyfin 或 Plex 扫描，最后发一条入库通知。

设置在「媒体 → 媒体库」，结果在「媒体 → 整理历史」。识别要用 TMDB，先在媒体识别里填好 TMDB API Key。

准备目录

pt-tools 要能读到下载目录，也要能写媒体库。直接装在机器上时一般不用改什么；在 Docker 里运行时，要把两个目录都挂进 pt-tools 的容器。

用硬链接时，下载目录与媒体库必须在同一个文件系统上。Docker 里最稳妥的做法是挂载它们共同的上级目录，作为同一个卷：

services:
  pt-tools:
    volumes:
      - /mnt/data:/data # 下载目录在 /mnt/data/downloads，媒体库在 /mnt/data/media

分开挂成 /downloads 与 /media 两个卷时，即使宿主机上是同一块盘，容器里硬链接也会失败。

下载器与 pt-tools 看到的路径不同时（比如两者在不同的容器里），在「路径映射」里添加：下载器里的 /downloads 在 pt-tools 里是哪个目录。按路径分段取最长的匹配，/data 不匹配 /database。路径相同时不用加。

媒体库

每个媒体库收一类条目。电影和剧集各建一个；想把动画单独放时，再建一个勾选「只收动画」的库（TMDB 类型里有「动画」的条目优先进这种库，没有这种库时进普通的库）。同类型有几个库时用排在前面的那个。

项目	说明
类型	电影或剧集；勾选「只收动画」时只收动画
库目录	pt-tools 里看到的路径（绝对路径）
整理方式	硬链接（默认）、复制、软链接、移动，见下表
命名模板	留空用默认模板，见命名模板
刮削	写 NFO 与图片，写哪几样、图片用哪种语言见刮削；交给媒体服务器自己刮时关掉
覆盖	打开后每次整理都重写 NFO 与图片；关闭时已经有的不动
同名文件	库里已经有 pt-tools 放的旧版本时替不替换，见同名文件
二级分类	勾选「按二级分类放进子目录」时放进「库目录/分类/…」，见二级分类

整理方式	说明
硬链接	不多占空间，种子照常做种；下载目录与媒体库要在同一个文件系统上
复制	多占一份空间，跨分区也能用；先写临时文件，复制完再改名
软链接	不占空间；媒体服务器要能用同一个路径读到下载目录，删种后链接失效
移动	文件搬进库里，种子不能再做种；只整理已暂停的种子

移动时删不掉源文件（例如下载目录只读）：库里放好的那份照样记成已整理，方式按实际的记成复制（跨文件系统）或硬链接，写明源文件留在下载目录里，需要时自己删掉。

编辑媒体库时点「检查」：确认库目录存在、可写；用硬链接时，再在每条路径映射的 pt-tools 路径里建一个文件、试着硬链接到库目录，确认在同一个文件系统上。试建的文件检查完就删掉。

命名模板

模板用 Go 的 text/template 写，算出库里的相对路径，不写扩展名（整理时自动加上）。默认模板 Emby、Jellyfin 与 Plex 都认。

电影的默认模板：

{{.Title}}{{if .Year}} ({{.Year}}){{end}}/{{.Title}}{{if .Year}} ({{.Year}}){{end}}{{if .Quality}} - {{.Quality}}{{end}}

示例：奥本海默 (2023)/奥本海默 (2023) - 2160p BluRay HDR10 H.265.mkv。

剧集的默认模板：

{{.Title}}{{if .Year}} ({{.Year}}){{end}}/Season {{.Season}}/{{.Title}} - {{.SeasonEpisode}}{{if .EpisodeTitle}} - {{.EpisodeTitle}}{{end}}

示例：最后生还者 (2023)/Season 1/最后生还者 - S01E02 - 感染.mkv。

编辑框上面有几个预设：目录名里带上 TMDB 编号时，Emby 写成 [tmdbid=编号]，Jellyfin 写成 [tmdbid-编号]，Plex 写成 {tmdb-编号}。改模板时下面会显示示例渲染的结果，写错时写明原因。

变量	说明
.Title、.OriginalTitle	标题（TMDB，按媒体识别里设置的语言）与原名
.Year	年份；剧集是首播年份
.TMDBID、.IMDbID	TMDB 与 IMDb 编号
.Season、.Episode	季与集
.SeasonEpisode	S01E02，一个文件里有多集时 S01E02-E03
.EpisodeTitle	这一集的标题（TMDB 有时才有）
.Quality	分辨率、来源、HDR、编码连在一起
.Resolution、.Source、.VideoCodec、.HDR、.Audio、.Group、.Edition	分辨率、来源、视频编码、HDR、音轨、制作组、版本说明

pad 把数字补零，比如下面的模板写出 最后生还者/Season 01/最后生还者 S01E02.mkv：

{{.Title}}/Season {{pad .Season 2}}/{{.Title}} {{.SeasonEpisode}}

变量里路径不能用的字符（\ / * ? " < > |）换成空格，冒号换成 -；每一级去掉首尾的空格与点，空的一级跳过，每一级最多 200 字节。算出的路径不会跑到库目录外面。

二级分类

媒体库勾选「按二级分类放进子目录」以后，条目先按规则分类，再放进「库目录/分类/」下面，例如 电影/华语电影/让子弹飞 (2010)/…、剧集/欧美剧/最后生还者 (2023)/Season 1/…。规则在媒体库页的「二级分类」里，电影与剧集各一组：

• 从上往下取第一条对得上的；都对不上时直接放进库目录。
• 一条规则可以按类型、原始语言、出品国家或地区分：几个条件都要满足，一个条件里选了几个时满足其中一个就行；三个条件都不选的那条收下前面都对不上的。
• 原始语言写 ISO 639-1 代码（zh、ja 等，TMDB 把粤语记作 cn），国家或地区写 ISO 3166-1 代码（CN、US 等）；列表里没有的可以直接输入。
• 「填入常用分类」填的是和 MoviePilot 默认一样的分类：电影分动画电影、华语电影、外语电影；剧集分国漫、日番、纪录片、儿童、综艺、国产剧、欧美剧、日韩剧、未分类。

分类名称就是目录名，不能有 / \ : * ? " < > |。改了规则或开关只影响之后整理的文件，已经在库里的不动。剧集的 NFO、海报与 Logo 写在分类目录下的剧集目录里。整理入库的预览里会写明放进哪个分类。按规则分要用 TMDB 的详情（电影的出品国家或地区只在详情里），详情取不到时这次不整理，过一会儿自动再试。

同名文件

同一部电影或同一集换了版本（例如先下了 1080p、后来又下了 2160p），整理出的文件名一样时，库里那个位置已经被旧版本占着。媒体库的「同名文件」决定怎么办：

选项	说明
不替换（默认）	留着旧版本，新的这个记成跳过，写明原因
新文件更大时替换	新文件比旧版本大才换

只替换 pt-tools 之前放进这个库的同一部电影（同一集）的文件：按整理记录与文件编号确认还是当初放的那个。用户自己放的、换过的、移动整理的（库里唯一的一份）一律不替换，媒体库用移动整理时也不替换。替换时新文件先放到旁边的临时名，旧文件挪到旁边的备份名并确认是旧记录放的那个，再把新文件放到原位置，写好整理记录以后才删掉旧文件：哪一步失败都会把旧文件放回原处，pt-tools 中途退出时下次启动会把没做完的撤回；旧版本的字幕与同名的 NFO、截图换成新的，目录里的海报等留着，旧的整理记录标成「已删除」并写明换成了什么。下载目录里的文件都不动。库目录所在的文件系统既不支持硬链接、也不支持不覆盖的改名时（少数网络存储），不替换并写明原因。

只按大小换：换下来的小的旧版本再整理（不管是自动还是手动）时不会把大的换回去，记成跳过；要换回去，先在整理历史里删掉新版本的记录（连库里的文件），再整理旧的。命名模板里带画质时（电影的默认模板就带），不同版本的文件名不同，不会撞上，两个版本都会留在库里；只想留一个时从模板里去掉画质，或者用订阅的洗版。

哪些文件会整理

• 视频文件：mkv、mp4、m4v、avi、ts、m2ts、mts、mov、wmv、flv、rmvb、rm、webm、mpg、mpeg。
• 跳过：Sample、Trailers、Featurettes、Extras、SPs、花絮、特典这类目录里的文件，文件名以 sample、trailer 结尾的，NCOP、NCED 片头片尾，以及小于「视频最小体积」（默认 50 MB）的。Specials 目录里的是第 0 季的正片，照常整理。
• 原盘（BDMV、VIDEO_TS 目录）与 ISO 镜像不整理。
• 字幕（srt、ass、ssa、sub、idx、sup、vtt）跟着视频一起整理（花絮、样片目录里的不算），按文件名加上语言后缀：简体 zh-CN、繁体 zh-TW、中文 zh、英文 en、日文 ja、韩文 ko。种子里有几个视频时，按文件名前缀或季集分给对应的视频。
• 剧集的季与集从每个文件名里读，也套用识别词（集数偏移同样生效）；只有一个文件的种子读种子名。

识别用种子名（站点标题不同时作为副标题），有站点给的 IMDb 编号时优先按编号查找。

触发方式

方式	说明
自动整理	pt-tools 推送的种子下载完成后整理。只整理打开以后下载完成的；每 10 分钟补查一次漏掉的
定期扫描	按间隔扫描下载器里已经下载完的种子，不是 pt-tools 推送的也整理。每轮最多 50 个，已经有整理记录的不再扫
目录监控	按间隔扫描「目录监控」里开着的目录，整理放进来的视频（不是下载器里的种子），见目录监控
手动整理	任务列表里「状态」列的整理图标（手机上是行卡的「整理入库」）；下载器 Web UI 里选中一个下载完的种子后点「整理入库」，或右键菜单

整理设置里写明定期扫描与目录监控上一次、下一次大约什么时候（这些时间在 pt-tools 重启以后从头算，启动后的第一轮在一分钟内）。

自动整理与定期扫描都只整理「范围」里的种子：下载器、分类、标签、保存路径（下载器里看到的）四项，留空的一项不限制，填了的要满足其中之一。它们失败以后的自动重试也按现在的设置：关掉了对应的开关，或者种子已经不在范围里，就不再重试。

手动整理先预览：识别出的条目、选中的媒体库、每个文件放到哪里。识别不对时填 TMDB 编号（类型选电影或剧集），也可以换一个同类型的媒体库，点「重新预览」确认后再整理。整理过的种子再整理时沿用之前用的条目（预览里写着「沿用之前整理用的条目」）；要换条目，填 TMDB 编号，或先删除整理记录。复制大文件时整理可能要一会儿，弹窗等 20 秒后先关，整理在后台继续，结果到整理历史里看。

同一个文件只整理一次：完成事件重复到达、几种方式同时触发，都不会重复整理。库里已经是这个文件（同一个 inode，或指向源文件的软链接）时直接算完成；目标位置是别的文件时不覆盖，记为跳过（复制与移动出的文件认不出是不是自己放的，目标已存在时一律跳过）；是 pt-tools 之前放的同一条目的旧版本时按媒体库的「同名文件」，见同名文件。字幕没整理成时写进记录，下次整理这个种子（重试或再手动整理一次）时补上。

目录监控

放进监控目录的视频（不是下载器里的种子，例如手动拷进来的、别的工具下载的）也能按媒体库整理。在媒体库页的「目录监控」里添加目录（pt-tools 里看到的路径），扫描间隔在「整理设置」里改，默认 10 分钟。添加以后路径不能改，要换目录就删掉再添加。

• 目录下的每一项（一个文件，或一个文件夹）当作一个种子：按它的名字识别，里面的视频按媒体库的方式（硬链接、复制、软链接、移动）放进库里，整理记录里「下载器」一栏写「目录监控」。
• 最近 2 分钟里还有改动的项先不整理（可能还在复制）。每个视频都有整理记录的项不再扫；文件夹里后来多了几集时，整理新的那几集。
• 隐藏的文件与文件夹、NAS 的系统目录（@eaDir、#recycle 一类）、没下载完的文件（.part、.!qB 一类）不看。目录超过 6 层或文件超过 5000 个的项整项不整理，整理历史里写明原因。
• 一个位置只有一条整理记录，整理时记下源文件的编号（同一个文件，大小与修改时间也没变才算同一个）：同一个位置上换成了另一个文件（例如移动整理以后又放进来一个同名的），记录管着库里的文件时不整理新的，在那条记录里写明；要整理它，先删除那条记录，下一轮扫描就会整理。记录不管库里的文件（例如识别失败的）时按新文件整理。
• 监控目录不能是媒体库的目录，也不能在媒体库里或包含媒体库；也不要监控下载器的下载目录，那里的种子由自动整理与定期扫描处理。
• 媒体库用移动整理时，先确认这一项不是下载器里的种子（移走了种子就没法做种）：是的话不整理，记录里写明；连不上下载器、确认不了时过一阵再试。种子的路径按「路径映射」换成 pt-tools 里的路径再比；在 pt-tools 里找不到的（没配路径映射，或者下载器在别的机器上）按名字认，和这一项同名的种子当成是它。
• 没有站点给的标题与 IMDb 编号，只按名字识别。认错了时在「媒体识别」里加纠正或识别词，再到整理历史里重试。
• 「删种时一并删除入库链接」不管目录监控整理出的文件：删掉监控目录里的源文件，库里的照样留着。

刮削

打开刮削后，「刮削内容」里可以分别选 NFO、海报、背景图、Logo、季海报与集截图（后两项只有剧集有）。没选过的媒体库写 Logo 以外的几项。

条目	写的文件
电影	<文件名>.nfo；电影有自己的目录时写 poster.jpg、fanart.jpg 与 clearlogo.png，放在库目录根下时写 <文件名>-poster.jpg、<文件名>-fanart.jpg 与 <文件名>-clearlogo.png
剧集	剧集目录里的 tvshow.nfo、poster.jpg、fanart.jpg、clearlogo.png、season01-poster.jpg（第 0 季是 season-specials-poster.jpg）；季目录里的 season.nfo；每集的 <文件名>.nfo 与 <文件名>-thumb.jpg

Logo 是透明背景的片名图，Emby、Jellyfin 与 Kodi 都认 clearlogo.png。「图片语言」决定用哪一张：

图片语言	海报	背景图	Logo
跟识别语言（默认）	TMDB 按识别语言给的那张	TMDB 给的那张	依次找识别语言、英文、没有文字的
中文、英文、日文	优先用这种语言的，没有时用 TMDB 给的那张	优先用没有文字的	依次找这种语言、识别语言、英文
无文字	优先用没有文字的	优先用没有文字的	依次找没有文字的、识别语言、英文

要写 Logo 或选了图片语言时，pt-tools 会多取一次条目的图片列表（缓存一周）。取不到时海报与背景用 TMDB 给的那张、不写 Logo，整理结果里写明原因。季海报与集截图总是用 TMDB 给的那张。

NFO 是 Kodi 格式，Emby、Jellyfin 与 Plex 的 NFO 插件都认，里面带 TMDB 与 IMDb 编号。图片从 TMDB 下载，走媒体识别里设置的代理。模板把每集平铺在库目录根下时，不写剧集与季的文件。

「简介与评分」默认用 TMDB 的。选「豆瓣」时，写 NFO 前按中文名在豆瓣上找同一部，找不到再用原名找：名字对得上的里面年份相同的优先，没有时差一年以内的只有一个才用；同名的不止一个、拿不准时用 TMDB 的。

• 电影的简介换成豆瓣的，评分以豆瓣的为主（TMDB 的也留着），再记下豆瓣编号；pt-tools 推送的种子带着站点给的豆瓣编号时先按编号取，名字与年份都对得上才用。
• 豆瓣上剧集是一季一个条目：tvshow.nfo 用第 1 季的，season.nfo 用这一季的简介；每集的 NFO 还是 TMDB 的。
• 豆瓣没有开放的接口，pt-tools 用的是豆瓣网页自己用的两个（搜索与条目详情），不登录豆瓣，不走媒体识别的代理。找不到或暂时不能访问时用 TMDB 的，手动整理的结果里写明，后台整理写进日志。
• 每 2 秒最多请求一次豆瓣；搜索结果缓存一天，条目缓存一周。只找这次要写的 NFO 用得上的：已经有的 NFO 不覆盖时不去找，打开「覆盖已有的 NFO 与图片」后重新整理才会换。

媒体服务器

整理完通知媒体服务器扫描新目录。不加媒体服务器也能整理，媒体服务器会按自己的计划扫描。

项目	说明
种类	Emby、Jellyfin 或 Plex
地址	完整的地址，如 http://192.168.1.10:8096（Plex 是 :32400）。媒体服务器回跳转时不跟着跳
API Key	Emby、Jellyfin 在控制台的「API 密钥」里新建；Plex 填 X-Plex-Token。加密保存，只写不读
刷新方式	只扫整理到的目录（默认），或刷新整个媒体库
路径前缀	媒体服务器看到的路径与 pt-tools 不同时填两边的前缀，比如 pt-tools 的 /media 在 Emby 里是 /data/media

点「测试」确认地址与 API Key 能用。列表里写着最近一次通知的结果；通知失败不影响整理。填了路径前缀而整理到的目录不在里面时，不把 pt-tools 的路径发给这个服务器，列表里写明原因。

入库通知

在「整理设置」里选择通道后，每次有新文件入库时发一条：标题与年份、季集、画质、媒体库、来源种子，最后是 TMDB 的海报地址（Telegram 一般会把它显示成预览图）。通知按通道的静默时段延后，失败时自动重试。没有选通道时不发。

整理历史

每个视频文件一条记录，写明整理到哪里、用什么方式、哪种方式触发、成功还是失败。

状态	说明
已整理	文件已经在库里
失败	写明原因。TMDB 暂时不能访问这类问题按 10 分钟、30 分钟、1 小时、3 小时、12 小时自动重试，之后不再自动重试；没识别出来、不在同一个文件系统这类要先改设置的不自动重试
跳过	目标位置已经有别的文件，或者种子是原盘、没有可整理的视频
已删除	库里的文件已经删掉

「重试」重新整理这条记录所在的整个种子；改了识别词、加了纠正或媒体库之后点它。「删除」时可以勾选「同时删除库里整理出的文件」：视频与字幕只删确认还是当初整理出的那个文件（硬链接与复制按文件编号确认，包括设备、inode、大小与修改时间；软链接按指向确认）；NFO 与图片只删 pt-tools 刮削时写的那份，目录里的海报、背景、Logo 与 NFO 等目录里不再有视频时才删；最后删空目录。换掉或改过的文件留着，删除后会列出来。记录变成跳过或失败（例如库里的视频被换成了别的文件）时，之前整理出的字幕与刮削写的文件仍记在这条记录里，删除时照样按上面的规则清理。移动整理的文件是唯一的一份，这里不删。下载目录里的文件都不动。

与自动删种的关系

硬链接入库以后，删掉种子连数据也腾不出空间（库里的链接还占着），所以低空间紧急清理不挑已经硬链接入库的种子。常规的删种规则照常生效：做种够了删种，库里的文件照样能看。

「删种时一并删除入库链接」默认关闭。打开后，种子已经不在下载器里、源文件也没了（连数据删掉了）时，pt-tools 每 10 分钟检查一次，删掉从它整理出的硬链接与软链接，记录改成「已删除」；复制与移动的文件不删。打开以后，紧急清理也会挑硬链接入库的种子，删掉以后空间才腾得出来。种子的保存目录或库目录不在（例如没挂载）、下载器连不上时不做任何删除。

常见问题

整理失败：源文件与媒体库不在同一个文件系统：硬链接要求下载目录与媒体库在同一个分区。Docker 里按准备目录挂载成同一个卷，或者把媒体库改用复制。

整理失败：pt-tools 里找不到某个路径：下载器与 pt-tools 看到的路径不同，在「路径映射」里添加对应关系。

没有识别出来：到媒体识别里预览这个种子名，选候选或填 TMDB 编号纠正，再回到整理历史点「重试」；也可以手动整理时直接填 TMDB 编号。

目标位置已经有同名文件：pt-tools 不覆盖别的文件。确认库里那个文件不要了，删掉后重试。