文件名刮削与文件整理工具
一个 Windows 桌面小工具，用于从文件名中提取标准代码，并按代码批量移动、重命名文件。所有操作都在图形界面完成，不需要懂编程，也不需要打开命令行。
需要写进脚本、计划任务，或者干脆不想开界面时，核心的扫描和移动也可以用命令行批量跑。
完整版还额外提供网页信息抓取和Jellyfin 元数据生成扩展功能，全部通过图形界面操作。
假设你有一堆文件名长这样的视频：
ABP-123 某某标题.mp4
SSIS_456 另一个标题.mkv
FC2-1234567.mp4
随手拍的一段视频.mp4
核心功能（核心版就有）：
- 自动识别哪些文件名里有标准代码（
ABP-123、SSIS-456、FC2-1234567）； - 告诉你识别结果——识别成功标绿色
✓，识别失败标灰色✗； - 按代码把文件移动到指定目录，可以按代码分文件夹，也可以用代码给文件重命名；
- 一键撤回——如果移错了，可以还原。
扩展功能（完整版才有，随程序一起发布）：
| 功能 | 作用 |
|---|---|
| JavDB 信息 | 去 javdb.com 抓取演员、评分、封面图，生成 Excel |
| 字幕猫 | 去 subtitlecat.com 下载中文字幕 |
| Jellyfin NFO | 读取刮削好的表格，给每个电影文件夹生成 Jellyfin 能识别的元数据文件 |
软件有两个版本，选一个下载即可：
| 版本 | 大小 | 包含什么 | 适合谁 |
|---|---|---|---|
| 核心版 | 约 13 MB | 扫描 + 移动功能 | 只想整理本地文件 |
| 完整版 | 约 150 MB | 核心功能 + 全部扩展功能 | 还要抓取网站信息 / 下载字幕 / 生成 NFO |
下载 JAVscraper_core_win64.exe，放到任意目录，双击运行。
下载 JAVscraper_full_win64.7z，解压到任意目录（比如 D:\Tools\AVScraper\），双击里面的 JAVscraper_full_win64.exe。
⚠ 重要：完整版是一个文件夹，不要只把里面的
.exe单独拷出来，会无法运行。
- Windows 10 / 11
- 不需要安装 Python，不需要任何其他软件
-
双击 exe 启动。首次运行会在 exe 旁边自动生成
config.json（配置文件）和log/文件夹（日志）。 -
点击右下角的「配置」按钮，弹出配置窗口。初次使用需要改几个路径：
配置项 填什么 默认扫描目录 你的视频文件所在的目录 输出目录 一般留空即可（结果自动存到 log/下）目标目录 文件整理后要移到哪里 改完点下方的「应用」或「确定」。
-
切到「1-扫描」标签页，检查扫描目录对不对，点「开始扫描」。
到这里就基本能用起来了。详细流程见下一节。
主界面顶部是一排标签页，完整版会显示：
1-扫描 2-移动 3-爬虫 4-Jellyfin NFO
所有配置项都集中在右下角的「配置」窗口里，主界面的各标签页只负责操作。
这是整个流程的起点。
操作步骤：
- 确认顶部的「扫描目录」是你的视频目录；
- 第一次需要手动选，之后会自动记住上次用的目录；
- 点击输入框会展开历史下拉，选之前用过的目录；
- 点「开始扫描」；
- 稍等片刻，结果会一行行显示在表格里。
看懂结果：
| 显示 | 含义 |
|---|---|
✓ 绿色 |
成功识别到代码 |
✗ 灰色 |
没识别到，保持原文件名 |
↳ 蓝色 |
文件名里没找到，但从父文件夹名继承了代码 |
表格上方的状态栏会显示总数、成功数、提取率。点击表头可以排序——比如点「状态」列，把 ✓ 和 ✗ 分开看。
搜索框：
表格上方有一个搜索框，可以实时筛选结果：
- 下拉选「全部列」：所有列里都搜；
- 下拉选具体列名（如「文件名」）：只搜该列；
- 勾上「正则」：搜索文本按正则表达式解释。
小技巧：
- 每个扫描结果会自动存到
log/<时间戳>/里，包括 JSON、文本报告、CSV 表格； - 扫描不会修改任何文件，可以放心重复运行。
如果 ✗ 太多：
- 说明这些文件名里没有可识别的代码；
- 常见原因是文件名里缺少连接符（
-或_）——比如ABP123而不是ABP-123，这时需要手动改文件名； - 识别规则在配置窗口里可以调整（见下方配置窗口）。
扫描完成后，切到这一页。
操作步骤：
- 顶部「输入 JSON」应该已经自动填好了（来自上一次扫描）；
- 确认「目标目录」；
- 点「预览更改」——这一步不会动文件，只是告诉你会发生什么；
- 仔细检查表格里的每一行；
- 用勾选框选择要移动的行（默认全选）；
- 确认无误后，点「执行移动」；
- 弹窗确认后，文件开始移动。
预览表格的颜色：
| 颜色 | 含义 |
|---|---|
| 绿色 | 正常移动 |
| 灰色 | 跳过（目标已存在，不覆盖） |
| 红色 | 覆盖（目标已存在，会被替换）⚠ |
勾选框：
- 每一行前面有一个勾选框，用来标记"这一行是否参与本次移动"；
- 表头的勾选框是"全选 / 全不选"——只对当前可见的行生效；
- 可以配合搜索框使用：搜
ABP，点表头全选，就只勾上了所有 ABP 相关的行； - 状态栏会实时显示已勾选的数量。
搜索与筛选：
和扫描页一样有搜索框，下拉里还能选「已勾选 / 未勾选」，只显示符合筛选条件的行。
移错了怎么办：
点「撤回移动」，会按照上一次移动的记录把所有文件搬回原位。
撤回记录只保留最近一次。如果连续执行了多次移动，只能撤回最后一次。
多视频与分段（-partN）：
如果同一番号下有多个视频文件（如分段视频），勾选「多视频启用 -partN 后缀」后：
- 工具会自动比对文件名，剔除公共部分，提取差异中的序号（支持纯数字或纯单字母）。
- 按序重新编号：不管原文件是
_A, _B还是_1, _2，只要序号连续（1~N），都会按顺序重命名为-part1、-part2…… - 连续性要求：如果检测到的序号跳号（如只有
_1和_3缺少_2），为了 Jellyfin 播放序列的稳定，整组放弃重命名，退回普通移动规则。 - 命名主干：若选择「按提取码命名」，主干为提取码；若选择「保留原文件名」，主干为剔除序号后的最长公共前缀。
附件命名方式有三个选项：
| 选项 | 行为 |
|---|---|
| 保留原文件名 | 附件保持原文件名（默认） |
| 按提取码命名 | 附件改为 提取码.扩展名 |
| 跟随视频命名 | 附件改为与视频同名 |
「跟随视频命名」的详细规则：
-
优先跟随源目录里的视频：同一源目录下恰好一个视频时，附件跟它同名。 例如源目录有
ABP-123 某某标题.mp4和ABP-123-zh-CN.srt， 移动后变成ABP-123 某某标题.mp4和ABP-123 某某标题.srt。 -
源目录没有视频时，到目标目录里找：如果你已经先把视频移到了目标目录 （
目标/ABP-123/），之后单独扫描字幕并移动，工具会在目标/ABP-123/里找那个唯一的视频，让字幕跟它同名。 -
两处都找不到、或找到多个视频时，退回保留原文件名：
- 源目录和目标目录都没有视频；
- 或者任何一处有多个视频（如分段视频
part1/part2）—— 这时配对是模糊的，工具不猜。
-
平铺模式不启用目标目录查找：
移动到提取名子文件夹关闭时， 目标目录里是一堆平铺的文件，无从定位"这个番号的视频"。此时只跟随 源目录里的视频。
典型用法：视频和字幕一次扫描、一起移动 → 用规则 1； 先移动视频、再下载字幕、再移动字幕 → 用规则 2。
「3-爬虫」是一个扩展功能模块，内部包含两个子标签页：
JavDB 信息 字幕猫
两者的使用方式类似：输入一批番号 → 自动去网站上抓取 → 生成 Excel 报告或下载文件。它们的配置项全部在「配置」窗口里。
去 javdb.com 抓取影片信息，生成带封面嵌入的 Excel 表格。
操作步骤：
-
准备一个 Excel 文件，第一列写要抓取的番号，一行一个，不要表头：
ABP-123 SSIS-456 FC2-1234567 -
打开配置窗口，切到「JavDB 信息」，填好以下路径：
配置项 说明 站点地址 默认 https://javdb.com/，一般不用改输入 Excel 上面那个文件 封面目录 下载的封面图保存到哪里 输出 CSV 中间结果（爬到的原始数据） 输出 Excel 最终的漂亮表格 登录状态 见下方「登录 javdb」 点「应用」或「确定」。
-
切回「3-爬虫」→「JavDB 信息」，点「开始爬取」；
-
进度表格会逐行显示状态：
目标番号 实际番号 名称 状态 ABP-123 ABP-123 某某标题 ✓ 完成 SSIS-456 SSIS-456B 别的标题 ⚠ 完成（番号不同） FC2-… — — 进行中… -
全部完成后，点「生成 Excel」。
登录 javdb：
有些信息需要登录才能看到。建议先登录一次：
- 在浏览器里安装 Cookie-Editor 或 EditThisCookie 扩展；
- 打开 javdb.com，确认已登录；
- 用扩展导出 cookies，选 JSON 格式；
- 在配置窗口的「JavDB 信息」页里点「导入浏览器 Cookie」，选刚才的 JSON 文件；
- 完成。
也可以点「启动浏览器」→ 在弹出的浏览器里手动登录 → 回到程序点「关闭浏览器」→ 登录状态自动保存。
重要建议：
- 第一次跑建议开启「显示浏览器窗口」——javdb 会弹验证码，需要你手动点一下；
- 不要贪快——「请求间隔」默认 1 秒，改快容易被封；
- 遇到卡住可以点「停止」，已抓到的数据会保存。
去 subtitlecat.com 搜索并下载中文字幕。
操作步骤：
-
准备番号清单 Excel（和 JavDB 一样）；
-
打开配置窗口，切到「字幕猫」，填好：
配置项 说明 站点地址 默认 https://www.subtitlecat.com/输入 Excel 番号清单 目标目录 下载的字幕保存到哪里（平铺，不建子文件夹） 输出 Excel 爬取完成后自动生成的结果表格 登录状态 一般留空即可 -
切回「3-爬虫」→「字幕猫」，点「开始爬取」。
字幕选择策略：
工具会从搜索结果里挑一条最合适的下载，优先级从高到低：
- 番号一致的；
- 有 👍 标记的；
- 有
translated from Chinese的； - 下载量最高的。
所以只要搜索结果不为空，就一定会选中一条。
结果表格包含的列：
| 列 | 说明 |
|---|---|
| 目标番号 | 你输入的 |
| 搜索结果数量 | 该网站里搜到多少条（带超链接，点击直接跳转到网页） |
| 实际番号 | 选中字幕对应的番号 |
| 名称 | 字幕的标题 |
| 源语言 | 字幕翻译前的语言（中文显示） |
| 下载量 | 该字幕的下载次数 |
| 状态 | 见下 |
状态说明：
| 状态 | 含义 |
|---|---|
| 下载成功 | 正常下载完成，且番号一致 |
| 下载成功（番号不一致） | 下载完成，但选中的字幕是另一个番号的（浅黄底，需要人工核对） |
| 未搜到 | 网站里没有该番号的结果 |
| 下载失败 | 详情页里既没有下载按钮也没有翻译按钮 |
| 下载失败（翻译超时） | 点了「翻译」按钮后等太久，网站还没生成下载链接 |
关于「翻译」按钮：
有些字幕在网站上只提供"翻译成中文"的按钮，需要点击后等网站生成中文版本，然后才会出现"下载"按钮。工具会自动处理：
- 点「翻译」→ 等待 → 过一段时间再回来看；
- 如果超过「等待翻译」秒数（默认 30 秒）网站还没生成，就记为失败；
- 「轮间等待」控制每轮重试之间隔多久（默认 3 秒）。
颜色约定：
| 颜色 | 含义 |
|---|---|
| 浅红底 | 失败（未搜到 / 下载失败 / 翻译超时） |
| 浅黄底 | 下载成功但番号不一致，需要核对 |
| 无底色 | 正常 |
小技巧：
- 下载的字幕文件名与网站提供的一致（如
ABC-123-zh-CN.srt）； - 下载的字幕可以直接用本工具的扫描功能识别番号，再配合移动功能整理到视频旁边。
读取刮削好的 Excel（通常来自 JavDB 信息），为每个电影文件夹生成 Jellyfin / Kodi 能识别的 .nfo 元数据文件，并把封面复制到电影文件夹里。
操作步骤：
-
准备两个目录：
准备 说明 电影文件目录 每个电影一个子文件夹，文件夹名就是番号，如 ABP-123/封面源目录 从刮削表格里提取出来的封面图存到哪里 -
打开配置窗口，切到「Jellyfin NFO」，填好：
配置项 说明 输入 Excel 刮削结果的 Excel（JavDB 生成的，或你自己整理的同结构表格） 电影文件目录 上面那个目录 封面源目录 上面那个目录 工作表序号 Excel 里目标 sheet 的序号（第几个） 列名所在行 表头在第几行 番号列名 / 封面列名 / 标题列名 单列，填实际列名 演员 / 评分 / 类别 / 个人评论 / 网友评论列名 支持多个，用 ,分隔NFO 模式 每个视频生成同名 NFO / 只生成 movie.nfo / 两种都生成 封面命名 与视频同名 / 用番号命名 / 两种都复制 -
切回「4-Jellyfin NFO」，先点「提取图片」，把 Excel 里嵌入的封面抠出来，存到「封面源目录」；
-
再点「生成 NFO」，工具会遍历电影文件夹，复制封面 + 生成
.nfo文件； -
把「电影文件目录」添加到 Jellyfin 媒体库，Jellyfin 会自动读取 NFO 和封面。
注意事项：
- 本功能只处理嵌入单元格的封面图（WPS 的「嵌入单元格图片」格式，或 Excel 365 的「置于单元格中」）。普通"插入图片"（浮动图片）提取不了；
- 电影文件夹名必须与 Excel 里的番号一致，否则会显示"未匹配"；
- 生成的 NFO 是 UTF-8 编码的 XML，可以直接用记事本打开查看。
扫描和移动这两件事可以完全不开界面，用命令跑。爬虫和 Jellyfin NFO 目前只在图形界面里提供。
命令行版和界面版是同一个程序、共用同一份配置，放在同一个目录里就行：
JAVscraper_core_win64.exe ← 双击，打开界面
JAVscraper_cli.exe ← 在 cmd / PowerShell 里用
config.json ← 两者共用
log\ ← 两者的输出都在这里
用 pip 安装的也可以：把下面的
JAVscraper_cli.exe换成av-scraper即可。 命令行版 exe 不带版本号，方便加进 PATH 或者反复敲。
:: 扫描 D:\videos，结果自动存进 log\<时间戳>\（JSON + 文本报告 + CSV）
JAVscraper_cli.exe scan D:\videos
:: 一次扫多个目录（互相包含的目录只会扫一遍）
JAVscraper_cli.exe scan D:\videos D:\downloads
:: 报告换个地方放（默认 log\<时间戳>\）
JAVscraper_cli.exe scan D:\videos --output-dir D:\reports
:: 只在屏幕上看看结果，不写任何文件
JAVscraper_cli.exe scan D:\videos --no-reports
:: 把 JSON 交给下一条命令：- 表示写到标准输出（摘要仍然打在屏幕上，走 stderr）
JAVscraper_cli.exe scan D:\videos --json - > results.json输出长这样：
扫描目录 D:\videos
文件总数 5
直接提取 3
父目录继承 0
保持原样 2
提取率 60.0%
未识别（2）：
- random.mkv
- 随手拍的一段视频.mp4
未识别的文件不会被动，认出来的才参与下一步。
一次扫多个目录时，「扫描目录」下面会把每个目录各列一行；某个目录如果已经在另一个目录里面，命令行只在 stderr 提醒一句「……在……里面，已跳过」，不会重复扫两遍。
先 --dry-run 看一遍，它就是界面里的「预览更改」：
:: 预览：只告诉你会发生什么，一个文件都不动
JAVscraper_cli.exe move results.json -t E:\sorted --dry-run
:: 确认没问题再执行（-y = 不再问一次）
JAVscraper_cli.exe move results.json -t E:\sorted -y
:: 只处理其中几个番号（相当于界面里勾选几行）
JAVscraper_cli.exe move results.json -t E:\sorted -y --only ABP-123,SSIS-456
:: 目标已有同名文件时改成覆盖（默认是「重命名」，加 _01）
JAVscraper_cli.exe move results.json -t E:\sorted -y --on-conflict overwrite
:: 分段视频重新编号成 -part1、-part2（相当于界面里的「多视频启用 -partN 后缀」）
JAVscraper_cli.exe move results.json -t E:\sorted -y --part-naming| 参数 | 说明 |
|---|---|
-t, --target DIR |
目标目录。不写就用配置里的（在界面上选过一次就会记住） |
--dry-run |
只预览，不动文件 |
-y, --yes |
不再确认。在脚本或计划任务里必须加，否则会拒绝执行 |
--only 番号[,番号] |
只处理这些番号 |
--folder / --no-folder |
是否按番号建子文件夹（默认跟配置） |
--video-naming |
keep 保留原文件名 / code 按番号命名 |
--attachment-naming |
keep / code / follow（跟随同目录视频） |
--part-naming / --no-part-naming |
分段视频按 -part1、-part2 重新编号，附件跟随第一段（默认跟配置） |
--on-conflict |
skip 跳过 / overwrite 覆盖 / rename 加 _01（默认跟配置） |
命令行移的文件，可以回界面点「撤回移动」；界面移的也能用命令撤。两边共用 log\move_operations.json（只保留最近一次）。
JAVscraper_cli.exe undo --dry-run :: 先看看会撤回什么
JAVscraper_cli.exe undo -y :: 真的撤回撤回可以重复执行：中途按了 Ctrl+C，或者有几个因为原位置被占用没撤回去，处理好之后再跑一次 undo 就会接着撤，已经撤回去的自动跳过。
JAVscraper_cli.exe config :: 列出当前生效的配置
JAVscraper_cli.exe config --path :: 只打印配置文件在哪命令行不会修改配置，要改配置请用界面的「配置」窗口。
| 退出码 | 含义 |
|---|---|
| 0 | 成功（包括"没有需要处理的文件"） |
| 1 | 有文件没处理成功 / 被中断 / 你自己取消了 |
| 2 | 参数用法问题（包括非交互环境里少了 --yes） |
每个子命令都可以加 -v 看每个文件的明细，或者 -q 只在出错时出声。完整的参数说明：
JAVscraper_cli.exe --help
JAVscraper_cli.exe move --help主界面右下角有一个 「配置」 按钮，点击弹出一个独立窗口。
为什么独立出来：各标签页只负责操作，配置项集中管理，避免操作界面被配置项挤满。
窗口结构：
[核心配置] [JavDB 信息] [字幕猫] [Jellyfin NFO]
─────────────────────────────────────────
（当前标签页的所有配置项）
─────────────────────────────────────────
[重置] [重新加载] [确定] [取消] [应用]
顶部标签页对应不同模块的配置：
| 标签页 | 内容 |
|---|---|
| 核心配置 | 扫描、移动、应用全局设置 |
| JavDB 信息 | JavDB 抓取功能的路径与参数 |
| 字幕猫 | 字幕下载功能的路径与参数 |
| Jellyfin NFO | NFO 生成功能的路径与参数 |
底部按钮：
| 按钮 | 作用 |
|---|---|
| 重置 | 恢复所有配置为出厂默认值并立即保存（会弹二次确认） |
| 重新加载 | 从磁盘重读配置，放弃当前未保存的修改 |
| 确定 | 保存当前修改并关闭窗口 |
| 取消 | 放弃当前修改并关闭窗口 |
| 应用 | 保存当前修改但不关闭窗口 |
几个全局配置项（在「核心配置」的「应用」段）：
| 配置项 | 说明 |
|---|---|
| 关闭时二次确认 | 关闭主窗口时弹窗确认，避免误关 |
| 历史目录上限 | 路径输入框的下拉里最多保留多少条历史 |
| 日志区高度（行） | 各页面日志区显示多少行 |
| 表格区高度（行） | 各页面表格显示多少行 |
修改生效：
- 大部分配置改完点「应用」立即生效；
- 表格 / 日志高度、历史目录上限等全局项也是保存后立即生效，不需要重启程序。
Q：双击 exe 没反应 / 闪退？
- 检查是否有杀毒软件拦截。Windows Defender 或国产杀软对 PyInstaller 打包的 exe 有时会误报，加到白名单即可；
- 完整版确认整个文件夹都在，没有单独拷贝 exe。
Q：扫描时程序卡死？
- 正常不会。如果卡住，多半是磁盘读得慢（尤其是机械硬盘或网络盘），等它跑完即可；
- 日志区能看到实时进度。
Q：扫描结果里 ✗ 很多怎么办？
- 打开配置窗口，切到「核心配置」，确认文件名里的前缀在「已知字母前缀」列表里；
- 不在就加进去；
- 也检查文件名里是否有合法的连接符（
-或_）。
Q：移错了想反悔？
- 点「撤回移动」即可。前提是
log/move_operations.json还在，且没有执行过新的移动。
Q：爬虫标签页没显示？
- 核心版不含爬虫功能，看不到是正常的；
- 完整版如果某个功能显示为红色错误提示，说明该模块的依赖缺失或加载失败，具体原因和修复方法会写在提示里。
Q：抓取 javdb 时总是搜错番号？
- 打开生成的 Excel，看有没有浅红底或浅黄底的行：
- 浅黄底：搜到的第一条结果和目标番号不一致，需要人工核对；
- 浅红底：该番号没抓到，可以重跑一次，或者手动修正。
- 建议先打开「显示浏览器窗口」看一次实际搜索行为。
Q：字幕猫下载的字幕，名字对不上视频？
- 看生成的结果表格里状态是不是浅黄底的「下载成功（番号不一致）」；
- 这类行需要人工核对，或手动改字幕文件名；
- 如果番号一致但文件名不好看，可以用本工具的「移动」功能把字幕重命名。
Q：想清空历史目录记录？
- 关闭程序，用记事本打开
config.json，找到recent_scan_dirs和recent_target_dirs，改成[]，保存。
Q：配置文件在哪？
- 跟 exe 放一起。核心里叫
config.json；爬虫功能叫scraper_config.json；NFO 功能叫jellyfin_nfo_config.json； - 想完全恢复默认：删掉这些文件（或其中一个），重启程序会自动生成新的。
Q：日志和结果文件在哪里？
- exe 旁边的
log/文件夹里； - 每次扫描会在
log/<时间戳>/下生成三个文件； - 这些文件不会被自动清理，想删就手动删。
- 移动是不可逆的物理操作。虽然提供了撤回，但只在特定条件下有效（记录文件还在、之后没有执行过新移动）。执行前务必点「预览更改」，尤其看清红色的「覆盖」行。
- 扫描不修改文件，可以放心反复运行。
- 本工具仅用于本地文件整理。请确保所处理的文件来源合法，并遵守当地法律法规。
- 完整版体积较大（约 150 MB），因为内置了浏览器驱动。这是正常的，不是软件出问题。
- 不要单独拷贝完整版里的 exe——整个文件夹要一起复制或移动。
- 每个功能模块的详细说明见 plugins/ 目录下各自的
README.md； - 想了解内部原理、开发扩展、自己打包？请看 DEVELOPER.md；
- 遇到本文档没覆盖的问题，欢迎提 issue。