前言¶
在 DSH（DeepSeek Harness）里跑工作流时，本地素材目录往往混入完全相同的副本、时长相近的 MP4，以及扩展名与真实编码不一致的 MOV/AVI/WMV。单靠手工对比文件名或肉眼抽帧，既慢又容易漏。社区插件 dsh-duplicate-file-check 把查重、抓帧疑似重复、批量改名与转码整理收进面板（界面显示为「小视频整理」），按任务分组执行，同一时刻只跑一个任务，适合在确认来源目录与目标目录规则后再批量处理。
这是什么¶
dsh-duplicate-file-check 是 jediliu005 维护的 DSH 工作流类插件（社区目录分类：工作流）。它面向来源目录内的文件与视频：支持完全一致校验（抽样或逐字节）、两类 MP4 抓帧疑似重复检测、批量改后缀与 UUID 命名、按大小或视频时长排序后重命名并移动、MOV/AVI/WMV 按文件头识别并统一转 MP4，以及删除空文件夹与失败后的复位。依赖本机可用的 ffmpeg / ffprobe（统一编码与抓帧任务需要）。许可证为 MIT；package.json 当前版本为 0.2.0。
核心功能¶
面板最上方配置「来源目录」与全局「并发数」（0 表示自动），下列九个任务各自有开始按钮、进度与状态。
完全一致文件校验¶
先按文件大小分组，只处理同大小且数量大于 1 的组。快速模式对头、中、尾各取 100KB 比对；严格模式逐字节全量比对。开启「删除完全一致文件」时，每组保留最早的一个，其余删除且不可撤销。
抓帧疑似重复（两种模块）¶
仅处理 MP4；先排除完全一致文件。
「抓帧疑似重复校验_时长匹配」按时长分组（容差可配，默认 100ms），比对前 N 秒画面相似度（旧算法保留）。
「抓帧疑似重复校验_忽略片头」为独立模块：16×16 灰度 MAD、dHash、pHash 跨时长匹配，支持片头错位；有独立抓帧时长、片头容差与输出目录。
公共约定：抓帧时长默认 10 秒、上限 20 秒；频率默认每秒 2 帧（1–5 可调）。「移动疑似重复」将整组移到输出目录，按 1xxxxx.mp4 递增重命名；忽略片头模块命中时可在输出目录下为每组建子文件夹（如 重复组_001），组内保留原文件名。
批量改名与按序搬移¶
- 批量改后缀：只改扩展名（如
dat→mp4），同名目标跳过。 - 随机文件名：改为 UUID，后缀不变。
- 按文件大小重命名并移动：从小到大排序，从 100000 起编号并移到目标目录。
- 按视频长度重命名并移动：用
ffprobe读真实时长，从短到长排序后同样编号搬移。
目标目录不能等于来源目录，也不能在来源目录内部；目标不存在且上级存在时会自动创建，已有编号会自动续号不覆盖。
统一编码（MOV / AVI / WMV → MP4）¶
按文件头判定格式（与扩展名无关）；已是 MP4 的跳过。命中后先进入对比目录再转同名 MP4，不覆盖已有文件。转码尽量对齐原片分辨率、帧率、码率与音频参数；支持 x264 与 NVENC/QSV/AMF（失败自动回退 x264），可选智能容器直通、HDR 处理策略。默认保留原文件；取消勾选时仅在转码成功且校验通过后删除原件。
删除空文件夹与复位¶
递归删除来源下没有文件的子目录（先深后浅；来源根本身不删；不处理符号链接与 junction）。
五个会移动文件的任务（两种抓帧、按大小、按时长、统一编码）移动时写入 _dupfc_restore.json；「复位文件」按记录搬回原目录，已删除跳过，原目录不存在报错；记录外文件会 UUID 改名进入 resetFail。
并发策略因任务而异（例如完全一致与抓帧自动约 2–8；统一编码转码侧上限约 4），命名用内存占位避免 worker 冲突。
安装与启用¶
在已安装 DSH 的环境中执行：
dsh plugin install dsh-duplicate-file-check
也可在 DSH 配置文件的 bundles 中加入本包。安装后于面板或侧边栏打开「小视频整理」，确认 ffmpeg、ffprobe 在 PATH 或配置的目录中且进程有读写权限。
典型用法¶
1、在面板「来源目录」中添加待整理的根路径，按需设置并发数。
2、完全一致清理：在「完全一致文件校验」中选择快速或严格模式，确认后再启用删除（不可撤销）。
3、MP4 疑似重复：时长相近且片头一致用「时长匹配」；片头可能错位用「忽略片头」，按需调抓帧时长、片头容差与吻合率阈值，再用「移动疑似重复」整组导出人工核对。
4、整理命名：扩展名错误先用「批量改后缀」；需要匿名化用「随机文件名」；归档用「按文件大小」或「按视频长度」重命名并移动。
5、混合格式素材：用「统一编码」将 MOV/AVI/WMV 转为 MP4，关注对比目录下的 fail、original 与是否保留原文件。
6、误移恢复：在对应任务执行「复位文件」；处理完毕可跑「删除空文件夹」。
适用场景与注意¶
适合在单机或 NAS 挂载目录上批量去重、归类短视频素材、统一容器格式后再交给下游脚本或智能体引用的场景。插件以当前 DSH 进程的权限读写磁盘，删除完全一致文件与部分搬移操作不可逆或依赖复位记录；安装与启用前应自行查看 GitHub 仓库 源码与 MIT 许可。
社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，本包属于工作流类扩展。
结尾¶
dsh-duplicate-file-check 把字节级查重、抓帧近重复、批量改名与按头转码串成一套可停可复位的工作流，减少手工整理成本。进一步参数与边界行为以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/jediliu005/dsh-duplicate-file-check
- GitHub：https://github.com/jediliu005/dsh-duplicate-file-check
