目录检查与手动刮削

任务管理页为每个任务提供「检查目录结构」和「手动刮削」两个维护入口。本页说明如何定位异常文件、修正单个媒体目录的刮削结果，以及安全地重命名 OpenList 中的目录和文件。

使用前准备

建议先完成以下配置：

1. 在任务中选择明确的媒体库类型：电影、电视剧或动画
2. 在系统设置中配置 TMDB API Key
3. 如需 AI 辅助识别，完成 AI 识别配置
4. 确认 OpenList Token 具有读取权限；需要重命名和上传时还要具备写入权限

自动识别类型主要用于兼容旧任务，没有固定目录结构规则，不能执行结构检查或启用异常结构过滤。

目录结构检查

打开检查入口

1. 进入首页并找到目标 OpenList 配置
2. 点击「管理任务」
3. 找到目标任务，点击文件夹形状的「检查目录结构」按钮

进入检查窗口时，系统会强制刷新 OpenList，并读取：

• 任务根目录下直接存在的视频文件
• 任务根目录下的第一层媒体目录列表

此时不会递归遍历全部子目录，因此大型媒体库也能较快打开。

按需检查单个目录

在「第一层媒体目录」列表中点击某个目录的「检查」按钮，系统才会递归读取该目录，并显示：

• 扫描的文件和目录数量
• 视频文件数量
• 不符合结构要求的视频数量
• 包含异常文件及其父目录的文件树

需要获取最新状态时，点击「重新检查」。每次检查都会重新读取该目录，不复用上一次结果。

目录结构规则

类型	推荐结构	异常示例
电影	电影名 (年份)/视频文件	视频直接放在任务根目录
电视剧	剧名/Season 01/S01E01.ext	缺少剧名层或季目录层
动画	动画名/Season 01/01.ext 或 动画名/[01].ext	视频层级与任务类型不一致

字幕、图片、NFO 等辅助文件不参与结构异常判断。检查操作本身不会移动、重命名或删除 OpenList 文件。

执行时跳过异常视频

编辑任务并启用「跳过目录结构不符合的视频」后：

• 异常视频不生成 STRM
• 异常视频不进入 AI 和 TMDB 刮削
• 增量执行会清理此前为异常视频生成的本地 STRM 和刮削文件
• 日志会记录跳过数量和原因，异常文件较多时只展开前一部分并输出汇总
• 启用 Apprise 通知后，结果会按“结构异常跳过”分组展示文件路径和校验原因

WARNING

该选项会改变任务输出。建议先检查目录结构，确认异常列表符合预期后再开启。

手动刮削

手动刮削适合以下情况：

• 自动任务没有找到正确的 TMDB 条目
• 需要修正单个电影或剧集的 NFO、海报和背景图
• 需要按统一规则重命名媒体目录和文件
• 需要为旧目录补充 TMDB ID

选择媒体目录

1. 在任务操作区点击紫色的「手动刮削」按钮
2. 页面首次只读取任务根目录
3. 根据需要展开文件树，选择一个电影目录或一部剧集的根目录
4. 点击「识别并预览」

文件树采用按需加载。只有展开目录或开始预览时才读取对应层级；预览时会扫描所选媒体目录以生成完整的文件和重命名计划。

电视剧和动画应选择剧集根目录，不要直接选择某个季目录。任务根目录也不能作为重命名目标。

修正匹配结果

系统会根据任务媒体库类型解析文件名，并查询对应的 TMDB 类型。自动匹配失败或结果不正确时，可以使用：

• 标题：重新输入用于搜索的媒体标题
• 年份：缩小电影或剧集搜索范围
• TMDB ID：直接读取指定条目，跳过标题搜索

已经匹配成功时，也可以点击「匹配不正确？手动搜索」重新选择。

检查刮削预览

确认前请检查：

• 中文标题、原始标题、年份和 TMDB ID
• 简介、评分、海报和背景图
• 将要生成并上传的 NFO、海报和背景图文件名
• 开启重命名时的目录及文件变化

只有点击「确认刮削」后才会修改 OpenList。

重命名规则

任务配置中的「普通任务自动重命名媒体」默认关闭。开启后，手动执行和 Cron 定时执行都会先按下述规则重命名 OpenList 中的媒体目录与文件，再重新读取远端文件清单并生成 STRM，确保 STRM 使用重命名后的路径。

该开关要求同时开启 TMDB 刮削、选择明确的电影/电视剧/动画媒体库类型，并为 OpenList Token 配置写入权限。无法识别、TMDB 未匹配或发生目标名称冲突时，任务会保留该目录的原名称并继续处理，不会覆盖已有文件。任务配置中的「STRM 文件名正则表达式」只影响本地 .strm 文件名，与此开关相互独立。

电影

开启「重命名媒体目录和文件」后，电影目录和媒体文件会包含年份与 TMDB ID，例如：

原目录：后室
目标目录：后室 (2026) {tmdbid-1083381}

原文件：movie.mp4
目标文件：后室 (2026) {tmdbid-1083381}.mp4

电视剧和动画

电视剧按以下顺序执行，后一步始终使用前一步更新后的路径：

1. 剧集根目录
2. 季目录
3. 媒体文件

示例：

Show                         → Show (2011) {tmdbid-1399}
S1                           → Season 01
raw.S01E01.mkv               → Show - S01E01.mkv

季目录支持从复合目录名中提取明确的季标记：

原季目录	目标目录
第4季、第四季	Season 04
The Boys Season 4 Remux	Season 04
The.Boys.S04.2160p	Season 04
Specials、特别篇	Season 00
黑袍纠察队 第四季 1080p Remux	Season 04

同一目录包含多种相同季号时，按「第 x 季 → Season x → Sxx → 特别篇」确定匹配来源。

重命名安全保护

以下情况不会自动执行：

• 同一目录包含不同季号，例如 S03 第四季
• 多个源季目录将变成同一个目标目录
• 目标媒体目录、季目录或媒体文件已经存在
• 当前选择的是任务根目录

四季酒店 没有明确的“第 x 季”标记，不会被误识别；S04E01 是剧集标记，也不会单独作为季目录匹配。

冲突发生时系统不会覆盖或合并现有文件。请先在 OpenList 中整理冲突项，然后重新生成预览。

异步执行与失败续跑

确认刮削后，接口会立即创建后台作业，页面通过任务 ID 显示进度。主要阶段包括：

1. 校验目录并读取 TMDB 信息
2. 重命名目录和媒体文件（可选）
3. 生成 NFO 和图片
4. 上传到 OpenList

作业运行期间，同一任务的再次手动刮削和手动执行会被锁定，避免在上一次重命名尚未完成时再次修改路径。

如果下载、生成或上传阶段失败，页面会保留作业进度。排除网络或权限问题后，点击「从当前阶段继续」，系统会从持久化检查点恢复，不会重新执行已经成功的重命名操作。

常见问题

TMDB 没有找到结果

先尝试简化标题并填写年份；仍然没有结果时，到 TMDB 网站确认条目 ID，然后直接输入 TMDB ID 查询。

点击确认后等待时间较长

刮削已在后台运行，不需要保持原 HTTP 请求。下载图片和上传文件的耗时取决于 TMDB、代理、OpenList 和存储端速度，可以在页面查看阶段和进度。

季目录没有出现在重命名预览中

确认所选目录是剧集根目录，并检查季目录名称中是否包含明确的 第 x 季、Season x、独立 Sxx 或特别篇标记。包含不同季号的歧义目录会被跳过，并在日志中记录原因。

清理或改名后如何确认结果

返回任务管理页重新执行目录结构检查，或再次打开手动刮削页面展开对应目录。两处都会重新读取 OpenList 的最新目录状态。