刮削与元数据
刮削把网盘里的目录与文件识别成「作品 / 季 / 集」，并从 TMDB 取回标题、海报与简介。它跑在存储节点（Storage）侧，媒体管理只聚合结果。
刮削从文件管理页发起
选中挂载源，进到分类文件夹的上一级，在目标行点「加入任务」。画面上只有目录列表与工具栏，刮削选项在点开按钮后的弹窗里。
- 只有列表视图，刮削只能逐行发起，没有批量刮削
- 目录弹「目录刮削选项」，单文件点了直接入队
- 进度在工具栏「任务中心」的「刮削任务」Tab 里看
能做什么
- 对分类目录、作品目录或单个文件逐行入队刮削。
- 解析文件名匹配 TMDB，建出作品 / 季 / 集结构。
- 两档深度：
LIGHT（轻刮削）靠文件名推断，DIRECT（直刮削）用 ffprobe 实测。 - 在任务中心看进度，可停止、恢复、跳过子项、清理已结束。
- 写入挂载点自动记变更，由调度任务重放成增量刮削。
怎么发起一次刮削
- 进 文件管理，顶部选中存储节点与挂载源。
- 进到目标目录的上一级——工具栏没有「刮削当前目录」按钮，只能逐行发起。
- 目标行「操作」列点 「加入任务」：目录弹 「目录刮削选项」，单文件直接入队。
- 配置下列各项后点 「开始刮削」，成功提示
已添加刮削任务: {名称}（分类目录）（任务 {jobId}）。 - 工具栏 「任务中心」 → 「刮削任务」 看进度。
首次刮全新的分类目录，「刮削方式」必须选「覆盖」
默认的增量在分类目录下不新建刮削任务，而是去重放该库已有的文件变化日志。首次刮削没有日志可重放，于是直接返回 SKIPPED 与提示 当前分类目录没有待处理的文件变化日志——界面看起来像提交成功了，实际一个文件都没刮。首次用覆盖，日常补新才用增量。
提交成功后弹窗选项不会重置
成功提交只关闭弹窗，不重置「刮削方式」与「TMDB 匹配类型」，下次打开会沿用上次选的「覆盖」；只有「关闭」「取消」才重置。
「目录刮削选项」弹窗字段
| 字段（界面原文） | 控件 | 选项 | 默认 |
|---|---|---|---|
当前目录：{目录名} | 只读 | — | — |
这是分类目录（递归刷新并刮削子目录中的影视文件） | 勾选框 | 勾 / 不勾 | 不勾选，每次打开重置 |
刮削方式 | 单选 | 增量 / 覆盖 | 增量（提交后不重置） |
TMDB 匹配类型 | 单选 | 自动 / 电影 / 剧集 | 自动（提交后不重置） |
刮削参数 | 只读区块 | 扫描线程 / 补全线程 / 请求延迟 | 只对 115 网盘显示 |
弹窗里没有刮削模式、刮削语言与 NFO 选项，这些要在挂载源的系统设置里改（见下文「参数怎么调」）。
勾不勾「这是分类目录」
两种情况都会递归子目录，区别在扫描方式与标题归属：
- 勾选（分类容器，如
/国产剧）：任务中心标 「分类刮削」；按层并发遍历，没有深度上限也没有目标数上限；每个子目录独立解析、独立匹配 TMDB，不继承父目录标题；跳过「疑似分类目录」校验。配「增量」时不建任务，改为重放文件变化日志。 - 不勾选（这个目录本身就是一部作品）：任务中心标 「刮削」；单线程逐层深入，根目录自身也算一个目标；整棵树继承父目录标题与 TMDB ID，当成一部作品；入队前会抽样校验（最多 240 个目录、5 层），主题不一致直接报错。
覆盖刮削成功后的残留清理范围也跟着变：勾选时按整棵目录树清理，不勾选时只清理本任务范围内的孤儿与同 TMDB ID 的历史残留。
单文件与整目录
- 单文件点了直接入队，不弹窗，也不做根类型校验。单集刮成功后会修补同季已有集的标题、简介、首播日、时长与剧照，这一步不受「增量刮削联动补全」开关控制，永远执行。
- 目录会弹窗，并执行根类型校验，可能拒绝入队。
- 完成提示分别是
单项刮削完成，成功 N / M与目录递归刮削完成，成功 N / M。 - 移动端卡片视图、以及勾选多个文件后的批量工具栏，都没有「加入任务」；移动端只有「预览识别结果」。
- 目录行与任务的对应关系靠「路径末段等于目录名」判断，同一挂载源内不同层级的同名目录会互相命中。
发起时会遇到的界面提示
| 提示原文 | 含义与处理 |
|---|---|
检测到当前目录疑似分类目录：父目录名/TMDB 与文件名不一致（示例文件: {X}）。请勾选"分类目录"后再刮削。 | 没勾「这是分类目录」时的校验失败，勾选后重试 |
任务已暂停，请到任务中心恢复或清理后再刮削 | 只在任务正在停止时出现；已经暂停的行按钮不禁用，可直接再次发起 |
已有相同任务在队列中，已合并 | 命中活跃任务去重，或命中 30 秒入队冷却（按「挂载源 + 条目」）。刚失败 30 秒内的任务也算活跃，立刻重试会被静默吞掉 |
提交超时：任务可能已入队，请在任务中心刷新确认 | 前端 20 秒超时，去任务中心刷新确认 |
| 该目录已有排队中 / 刮削中的任务 | 「加入任务」被禁用，提示等任务完成 |
LIGHT 与 DIRECT
刮削模式只有两档，它是刮削深度，与画质、清晰度、码率档位无关。差别不是「有没有技术元数据」，而是文件名推断还是 ffprobe 实测。
| 维度 | LIGHT（轻刮削） | DIRECT（直刮削） |
|---|---|---|
| 文件名解析、递归扫描、TMDB 匹配、季集结构、NFO 读取 | 做 | 做，完全相同 |
| TMDB 匹配准确度 | 同一条匹配路径 | 同一条匹配路径，不比轻刮削更准 |
| 技术元数据 | 按文件名推断分辨率、编码、位深与 HDR 类型；文件名里没有这些信号就不写 | ffprobe 实测时长、尺寸、容器格式、码率、编码、HDR、位深、音轨与内嵌字幕轨 |
外挂字幕（srt / ass / ssa / vtt） | 识别，并为每个外挂字幕多建一条子项 | 识别 |
| 截图 | 不跑 | 跑 ffmpeg 截取第 3 秒画面，作为本地剧照兜底 |
| 音视频补全 | 可发起；补全任务本身按实测方式执行，但不截图 | 不可用，请求补全会报 仅轻量刮削模式支持补全任务 |
| 重刮会不会抹掉已有实测数据 | 不会：本次没有实测结果时只合并外挂字幕，保留库里已有的实测数据 | — |
模式不能在单次任务里指定：唯一入口是「媒体库设置」里的 「刮削模式（scrape_mode）」 下拉，作用域是挂载源级优先、全局兜底，兜底值 LIGHT。
首次推荐 LIGHT，线程数保持默认
轻刮削先把 TMDB 条目匹配出来让库能用，实测元数据之后由「音视频补全」分批补——补全只在轻刮削下可用。要实测分辨率 / 编码 / HDR / 音轨字幕与本地截图（多版本择优要用）才切 DIRECT。「刮削线程数」默认 自动（按机器性能），会按 CPU 核数取 2 到 16 线程。
轻刮削下有一条必然失败的路径
既无法从父目录继承匹配、又没开 NFO 输入的孤立媒体文件（比如散落在分类目录里的单个文件），在轻刮削下拿不到任何探测数据，子项直接失败并报 ffprobe 无数据。绕过办法：改用 DIRECT，或开启 NFO 输入。正常的「剧目录 / 季目录 / 集文件」结构会继承父目录匹配，不受影响。
技术元数据其实有三条采集链路
少了第三条，会误以为「轻刮削的库永远没有实测元数据」。
| 链路 | 什么时候发生 | 与刮削模式的关系 |
|---|---|---|
| 刮削时同步探测 | 刮削任务执行中，由存储节点探测 | 只在 DIRECT 下发生 |
| 音视频补全 | 由调度任务或「增量刮削联动补全」发起，存储节点补测 | 只在 LIGHT 下可发起，补全任务本身按实测方式执行 |
| 播放时补全 | 用户真的播放这个条目时，由播放节点异步补全容器格式、时长与音视频轨道，不阻塞播放 | 与刮削模式无关，一直生效 |
播放时补全的结果不替代存储侧的 TMDB / NFO 刮削，两者互补。
TMDB 凭据只能在配置文件或环境变量里改
界面上没有 TMDB 凭据入口：bearer-token 可用环境变量 TMDB_BEARER_TOKEN 覆盖，api-key 只能改存储节点的配置文件，连环境变量占位都没有。
配置文件里有硬编码兜底值，务必覆盖
存储节点的配置文件为 TMDB 凭据写了硬编码兜底值，公开在仓库里，随时可能失效或被限流。部署后请覆盖成你自己的 key。
直刮削探测会读多少数据
不会下载整片：探测只读文件头部若干 MB（经 115 本地代理时单次读取上限 5 MB）。读多少由「ffprobe 探测大小上限」与「ffprobe 分析时长上限」控制，两项都可以选 自动（按文件大小动态调整）——文件越大，自动档给的预算越大。单次探测命令默认 20 秒超时，超时会记 ffprobe timeout after Nms 并把该子项记为失败。
在哪看进度
文件管理 → 工具栏「任务中心」→「刮削任务」Tab（另一个 Tab 是「文件来源任务」）。
| 区域 | 能力 |
|---|---|
| 顶部工具条 | 刷新频率（关闭 / 1 / 2 / 3 / 5 / 10 / 15 / 30 秒，默认 2 秒，页面不可见时暂停轮询）、任务管理（停止全部(N) / 恢复全部(N) / 清理已结束）、刷新、关闭 |
| 行的聚合维度 | 不统一：刮削任务行是一个任务一行；补全行按**「挂载源 + 剧集目录」聚合成一行**，一行下面可能有多个任务 |
| 左表 7 列 | 挂载源 / 目录 / 类型 / 状态 / 进度 / 说明 / 操作，没有「耗时」列 |
| 类型标签 | 分类刮削 / 刮削 / 新增 / 移动 / 重命名 / 修改 / 删除。补全行的主徽章也是 「刮削」，「补全」「轻刮削」「直刮削」只出现在副标签 |
| 状态筛选与标签 | 筛选 全部状态 (N) / 进行中 (N) / 排队中 (N) / 已完成 (N) / 失败 (N) / 已暂停 (N)；行内状态 排队中 / 刮削中 / 停止中 / 已暂停，终态按计数细分为 已完成（无失败）与 部分完成（有成功也有失败）。另有 搜索目录 与每页 10 / 12 / 20 / 50 条（默认 50）；匹配 N 条 是当前页行数，不是总数 |
| 进度列 | 排队时 等待中，运行中总数为 0 时 扫描中，否则 done/total + 百分比条 + 成功 X 跳过 Y 失败 Z + 当前处理项 ▶ {文件名}；停止后 任务已停止（已处理 N/M）。⚠️ 跳过项也计入「成功」计数，「跳过」数是前端反推出来的 |
| 行内操作 | 只有 停止 N 个任务、恢复 N 个任务、删除 N 个已结束任务（确认框写明此操作不可撤销）三个按钮。没有独立「暂停」、没有「重试」、没有行内展开，停止就是暂停语义 |
| 右栏子项 | 条数 最新50条 / 最新100条 / 最新200条 / 最新500条（默认 100），筛选 完成 N / 排队 N / 失败 N / 跳过 N（恒默认「完成」）；排队中的子项可点「跳过」，但只有任务在运行中时才允许跳过 |
| 右栏补全区块 | 该行是补全组时出现 音视频补全 + N 个任务 徽章，筛选 处理中 N / 失败 N / 跳过 N / 完成 N，每行有 暂停补全任务 / 恢复补全任务 |
「扫描线程 / 补全线程 / 请求延迟」只在刮削弹窗里、只对 115 网盘显示，任务中心没有这类指标。其中**「请求延迟」是网盘目录列表与取直链的间隔**（为风控敏感的网盘准备），不是 TMDB 的调用间隔。
参数怎么调
入口：文件管理 → 「管理挂载源」→「挂载配置」头部 → 「媒体库设置」，改完点 「保存系统设置」。后台的「系统配置」页里没有任何刮削设置项，刮削弹窗里也没有。
| 设置项（界面原文） | 默认 | 取值 | 调整影响 |
|---|---|---|---|
刮削模式（scrape_mode） | LIGHT | LIGHT / DIRECT | 决定技术元数据是文件名推断还是 ffprobe 实测，也决定能不能发起音视频补全 |
刮削线程数（scrape_thread_count） | 0（自动（按机器性能）） | 自动 + 1–16 线程 | 轻刮削的并发。调大更快，但数据库冲突与网盘风控概率上升 |
刷新目录缓存 | 目录下无文件刷新 | 默认不刷新 / 目录下无文件刷新 / 全量刷新 | 全量刷新 每个目录都强制拉网盘，最慢也最吃配额；默认不刷新 完全用缓存，可能刮到过期结构 |
刮削语言（TMDB language） | zh-CN | 简体中文 / 繁体中文 / English / Español / 日本語 / 한국어 | 决定刮削请求 TMDB 的语言，图片语言自动按「该语言 → 无语言」回退。⚠️ 夜间的剧集简介剧照补全任务不读这个设置 |
使用 NFO 文件作为刮削输入 | 关 | 布尔 | 开启后读取网盘里的 .nfo，以其中的 TMDB ID、标题、简介等覆盖自动识别结果。界面建议保持关闭 |
其余设置项是条件渲染的，看不到不代表没有：「目录扫描线程数」「音视频补全线程数」「API 调用间隔」只对 115 网盘显示；「每次最多补全数量」「增量刮削联动补全」只在轻刮削下显示；「ffprobe 探测大小上限」「ffprobe 分析时长上限」只在直刮削下显示。
三条容易踩的作用域规则：
- 刮削设置存在存储节点自己的库里，作用域是挂载源级优先、全局兜底——换一个存储节点就是另一套设置。
- 「目录缓存过期时间」（含
永久（仅手动刷新））不在这个弹窗，它在挂载配置表单里（非本地磁盘才显示，默认永久），是与「刷新目录缓存」完全不同的设置项。 - 当前版本没有面向用户的「刮削数据清理」功能。
元数据来源与优先级
匹配按下面的顺序走，前一步拿到结果就不再往后：
1. 人工指定的 TMDB ID（最高，覆盖文件名解析出的 ID 与影/剧判定）
2. NFO 里的 TMDB ID（需开启 NFO 输入）
3. NFO 里的 IMDB ID（拿它去 TMDB 反查）
4. 文件名 / 目录名里的 [tmdbid-xxx]
5. TMDB 标题搜索（受「TMDB 匹配类型」约束，只搜一类）；带年份搜空则去年份重搜一次
6. 相似度裁决：标题相似度需 ≥ 0.6，文件名年份与 TMDB 年份精确相等时放宽
7. 本地 TMDB 缓存兜底；TMDB 网络异常（非 404）时也读缓存| 来源 | 要点 |
|---|---|
[tmdbid-xxx] 后缀 | 最稳的锚定方式；目录名含 tmdbid- 还会被直接判为媒体目录并跳过分类目录校验 |
[imdbid-xxx] 后缀 | 不参与刮削匹配，文件名解析里没有 IMDB 规则 |
| 文件名其它部分 | 年份、季集（S01E01 / 1x05 / 第1季第2集 / Season 1）、分辨率、HDR、位深与编码会被解析；发行来源与字幕组等噪声词先清洗再搜索 |
| 只有集号的短剧命名 | S02.mp4 在继承父目录匹配的路径下会被当成「第 1 季第 2 集」（为中文短剧设计）；独立匹配路径不做这个转换，只把「有集号无季号」归到第 1 季 |
| NFO | 是「优先覆盖」不是「兜底」：拿到 TMDB 详情后还会用 NFO 覆盖标题、原始标题、简介、上映日、时长、类型标签与演员表，但不改季号集号。刮削只读 NFO，不写 NFO。与文件名里的 TMDB ID 冲突时以 NFO 为准，遇到冲突最稳的做法是关掉 NFO 输入 |
| 辅助目录 | 字幕 / 样片 / 花絮 / 预告 / 封面 / 海报 / 剧照 / 元数据、subtitles、sample、trailer、extras、BDMV 等在扫描与校验中被跳过 |
| 媒体扩展名 | ⚠️ .iso、.rmvb、.m2ts 能被添加为刮削任务，但扫描阶段不会被当作媒体文件收录，所以这些格式实际刮不出来 |
| 图片 | 海报与剧照只存 TMDB 的相对路径，不下载到本地或网盘；刮削唯一写到节点本地磁盘的产物是直刮削下的截图 |
自动增量刮削
写入挂载点不会立即刮削：变化先记进变更日志，由「文件变更增量刮削」任务每 15 秒重放入队，再由「媒体刮削队列处理」任务每 15 秒执行。手动入队则是提交后立刻开始。
开关在 文件运维 → 传输设置 → 「自动刮削」 分组：一个 主开关 加三个分动作开关（上传/复制完成 → 入队刮削、删除 → INCREMENTAL prune、改名/移动 → prune + 入队），默认全开；主开关关掉后三类变化都不再触发。
界面上的「上卷到剧目录去重」开关目前不生效
勾不勾都一样。实际的去重窗口是 30 秒、粒度是「挂载源 + 条目」；「上卷到剧目录」在 webhook 触发的路径里总会执行，不受这个开关控制。
重放规则：
| 变化类型 | 重刮方式 | 行为 |
|---|---|---|
| 新建 | 增量 | 只入队新路径 |
| 移动 / 改名 / 修改 | 覆盖 | 旧路径清数据，新路径入队 |
| 删除 | 增量 | 删掉匹配结果与来源记录，说明列显示 已清理旧数据 N 项 |
| 字幕文件 | — | 找到同名媒体文件后按它的条目入队。⚠️ 这是「已刮削就跳过」规则的唯一例外，允许覆盖已刮削条目 |
| 目录 | — | ⚠️ 季目录（名字形如 S01、Season 1）不入队；只有目录名含 tmdbid-、含 {tmdb- 或带年份才入队 ⇒ 自动增量刮削只对「剧目录」生效 |
四个相关调度任务，都能在调度中心启停、改频率、手动触发：
| 任务 | 频率 | 默认 | 职责 |
|---|---|---|---|
| 文件变更增量刮削 | 每 15 秒 | 启用 | 按上表重放变更日志；全部媒体库都成功才删日志，有库失败则下一轮重跑 |
| 媒体刮削队列处理 | 每 15 秒 | 启用 | 轮询队列并执行，一次把队列排空 |
| 媒体探测信息回填 | 每 3600 秒 | 停用 | 只在轻刮削下生效，按「每次最多补全数量」为缺实测信息的文件建补全任务 |
| 剧集简介剧照补全 | 每天 04:30（Asia/Shanghai） | 启用 | 重查 TMDB，补齐本地真有文件、但缺简介或剧照的集；每集最多每 24 小时重试一次 |
两个「补全」别混：前者补本地实测技术元数据，后者补 TMDB 侧的简介与剧照。
其它触发入口：
- 「文件来源任务」Tab 的刮削徽章：上传之后刮削去哪了的唯一用户可见线索。传输任务行上显示
刮削 #{任务号}或状态原文（BUFFERED= 已写入变化日志待重放、ALREADY_SCRAPED/SKIPPED、NO_LIBRARY/NOT_FOUND），纯文本、点击不跳转。 - 外部 NAS 入站 webhook：对外地址是网关的
POST /api/webhook/{token}，同一路径命中多个媒体库来源时全部触发；Token 与请求体格式见系统配置。
「增量刮削联动补全」要同时满足这些条件才会发生：任务是单文件刮削、文件名能解析出集号、由自动增量或 webhook 触发（手动刮削不触发）、条目是剧集（电影永不联动）。它按「最新集优先」挑候选，且联动补全失败只记日志，不影响主任务成功。
重新刮削
条目详情里（条目已关联存储节点时可见）有折叠按钮 「重新刮削并修复同步」，展开后选 「增量刮削」（默认）或 「覆盖刮削」 再提交。提交结果形如 已提交 N 个后台刮削任务，跳过 X，失败 Y（任务 ids）；条目缺存储节点信息时报 刮削失败：缺少存储节点信息，请确认媒体项已关联存储节点。
| 增量刮削 | 覆盖刮削 | |
|---|---|---|
| 已有子项 | 保留；本任务已有子项时跳过扫描直接续跑（进度文案 已加载上次扫描记录，共 N 个条目，继续刮削...），已结束的子项不重做 | 先清空本任务子项再重新扫描（进度文案 覆盖模式：正在重新扫描目录，请稍候...） |
| 范围 | 只处理新增、变更或尚未完成刮削的文件 | 重新扫描这部剧对应目录下的文件并重建这批刮削数据，适合修复「文件已删但媒体库还在」的残留 |
| 残留清理 | 不会清理已移走的旧残留 | 任务成功时清理残留，但不删 TMDB 缓存与作品 / 季 / 集结构 |
| 分类目录 | 不建任务，改为重放文件变化日志 | 正常建任务并整目录重刷 |
增量模式下只有命中以下任一条件才会重刮，否则子项记 SKIPPED（消息 增量模式：已有匹配结果，跳过）：库里还没有这个条目；父目录或文件名变了；库里缺同步时间基准；云端修改时间晚于库里的记录。⚠️ 云端修改时间为空时直接跳过、不重刮。
排障
失败原因写在任务与子项的说明文字里（超长会截断），没有结构化错误码，只能按文本对照。
慢 / 卡住不动
- 一直显示
扫描中：检查「刷新目录缓存」是不是全量刷新（改回目录下无文件刷新或默认不刷新）；115 还要看「API 调用间隔」是否设得过大。 - 排队不动：到调度中心手动触发「媒体刮削队列处理」，或调大「刮削线程数」；确认模式是
LIGHT（直刮削每个文件都要探测，慢得多）。 - 想中途停下：点「停止」，进度会显示
任务已停止（已处理 N/M）。停止是渐进的，正在处理的子项会跑完。 - 「请求延迟」不是 TMDB 指标：刮削链路里对 TMDB 没有任何限流或退避处理，被限流会直接抛异常、子项记失败。担心 TMDB 压力应该调小「刮削线程数」；调大「API 调用间隔」没有用，调小它反而提高网盘封控概率。
失败与结果不对
| 症状 / 消息原文 | 怎么看 | 怎么调 |
|---|---|---|
| 状态「已完成」但条目不对 | 只要有 1 项成功，任务就标成功，大量子项失败也一样 | 必看进度列的「失败 N」与右栏子项；有成功有失败的行会细分为「部分完成」 |
| 失败后立刻重试没反应 | 去重把刚失败 30 秒内的任务也算活跃，返回 已有相同任务在队列中，已合并 | 等 30 秒以上，或先在任务中心删除该行的已结束任务再重发 |
| 点了「恢复」但失败项没重刮 | 恢复只把任务改回排队，不重做已结束的子项（含失败项） | 要重刮失败项必须用覆盖重新发起，或在条目详情走「重新刮削并修复同步 → 覆盖刮削」 |
TMDB 凭证未配置（api-key/bearer-token） | 任务直接失败 | 在存储节点补 TMDB 凭据（补全任务不检查凭据） |
音视频补全刮削需要 ffprobe，但当前环境未检测到可用的 ffprobe 命令（{cmd}）… / ffprobe timeout after Nms | 存储节点缺 ffprobe，或探测超时 | 在存储节点安装 ffmpeg（含 ffprobe）；超时的再调大探测大小与分析时长上限、检查直链可达性 |
ffprobe 无数据 | 轻刮削下无法继承父目录匹配的孤立文件 | 见上文轻刮削的失败路径：改 DIRECT 或开启 NFO 输入 |
仅轻量刮削模式支持补全任务 | 在 DIRECT 下请求了补全 | 把刮削模式改回 LIGHT，或不请求补全 |
大批量任务集体失败、扫描中止；115 报 115 网盘凭证已失效，请检查 Token 配置或等待自动续期 | 只有检测到 HTTP 405（网盘账号失效或被封控）才会中止整次扫描，其它异常只跳过当前目录继续 | 检查并更新挂载源凭据 |
目录下未找到可识别媒体文件（已递归刷新目录缓存） / 目录递归刮削未命中任何 TMDB 条目 | 目录里没有可识别媒体，或命名完全匹配不上 | 检查扩展名（.iso / .rmvb / .m2ts 入队合法但扫描不收录）与命名，先用「预览识别结果」试匹配 |
当前目录被判定为根目录或非媒体目录，请不要直接刮削该层级 / 当前目录被判定为分类目录，请使用"分类目录刮削"模式 / 安全保护：刮削任务未指定目录 ID（itemId 为空）…禁止扫描整个媒体库 | 入队前的校验拒绝 | 下钻一层再刮，或勾选「这是分类目录」；最后一种情况重新从文件列表行发起 |
当前分类目录没有待处理的文件变化日志 | 分类目录 + 增量，且没有待重放的变更 | 首次建库改用「覆盖」 |
媒体库未启用，无法开始刮削 | 库被停用 | 先启用媒体库 |
识别不准
TMDB 未找到匹配条目: {name}，或匹配到同名电影：在目录名 / 文件名加[tmdbid-xxx]是最稳的锚定方式；短剧把「TMDB 匹配类型」选剧集。- 整棵树被当成一部剧：说明忘了勾「这是分类目录」。
- 开着 NFO 输入时，第三方 NFO 可能覆盖掉正确结果，建议先关掉再对比。
- 「文件识别预览」可以先试匹配：文件行「操作」列点 「预览识别结果」（弹窗标题
文件识别预览），它不落库，超时 15 秒；未命中提示当前文件未命中 TMDB，请先调整文件或文件夹命名后再试。；「技术信息」分组只有 TMDB / IMDB / 媒体类型与原始页链接，不含分辨率、编码与时长。
关键规则
- 先刮削，后建库同步：中央媒体库不扫描磁盘，只聚合存储侧已刮削好的结果，顺序反了得到空库。
- 想给单次任务指定
LIGHT/DIRECT：不行，模式只由「媒体库设置」决定。 - 想补实测音视频元数据：补全只在
LIGHT下可发起，补全任务本身按实测方式执行，且不产出截图。 - 期待刮削整理文件：刮削不移动、不重命名、不新建媒体文件，「分类刮削」也不是自动归类。删除重复版本文件是媒体整理的职责。
- 任务中心的「清理已结束」与行内「删除 N 个已结束任务」都不可撤销。
- 删除挂载源会连带清理关联媒体库、刮削记录与媒体元数据，不可恢复；批量删除文件会先提示其中已有刮削数据的目录与文件数，并同步清理媒体库索引。
- 人工元数据覆盖与刮削结果冲突时覆盖值优先；但媒体侧强制全量覆盖同步会清除用户编辑，详见媒体管理。
- 媒体库类型与「TMDB 匹配类型」是两回事：库类型只有 不限 / 电影 / 剧集 三档，匹配类型只约束本次请求哪种 TMDB 接口。
- 只刮某一集时，TMDB 的季缓存会把整季全部集一起写入。