Files
cat-shark 827bbb6b6a feat: 新增种子目录清理脚本与配套 skill
主程序只能把 magnet 交给 Transmission,无法挑选文件,种子内的广告
(*.url、宣传页、样片/预告)会一并下载,同一部作品还会被多个发布站各下一份。
新增离线清理脚本处理下载完成后的目录。

clean_seed_extras.py:
- 保留:>=100MB 的视频(40+ 扩展名;无扩展名时读文件头嗅探)、字幕
  (含 .srt.old-<日期> 备份)、与同目录视频同名的海报、folder.jpg 等通用封面
- 删除:其余文件;同目录内内容相同的大视频只保留一份,校验方式为
  sha256(体积 + 头 4MB + 尾 4MB),体积相同但内容不同的不会误删
- 删除后自底向上级联清理空目录(可删到影片级目录,但不删 --root 本身)
- 默认预演,需 --apply 才真正删除;--manifest 导出待删清单供逐段复核
- 其他开关:--no-subtitles/--no-posters/--no-covers/--no-dedupe/--min-size-mb/
  --prefer-source/--keep-empty-dirs/--skip-recent-min

.agents/skills/torrent-download-cleanup:
- 记录完整流程(预演 -> 出清单 -> 用户确认 -> 执行 -> 复核)、保留/删除规则、
  去重策略、代码维护注意(decide() 必须是 视频 -> 去重 -> 海报匹配 的顺序)
- 附只读盘点脚本 find_missing_torrents.py:找出 Transmission 中数据已不在磁盘
  的任务(自包含,只用 requests)

tests/test_clean_seed_extras.py: 30 个离线用例(tmp_path 临时目录)
tests/README.md: 补充脚本用法与测试说明
2026-10-18 00:54:08 +08:00

8.1 KiB
Raw Permalink Blame History

name, description
name description
torrent-download-cleanup 用 clean_seed_extras.py 清理 LookingWeb 的种子下载目录(默认 /mnt/fnOS/123):保留大体积视频、字幕、同名海报与通用封面,删除广告/样片/重复视频并级联清理空目录。当用户要求"清理/整理下载目录、删除重复视频、看看有哪些垃圾可以删、下载完成了清一下",或需要继续上一次的清理流程与 Transmission 收尾时使用。

种子下载目录清理(LookingWeb)

主程序 LookingWebMain.py 只能把 magnet 交给 Transmission,无法挑选文件,所以种子里的广告 (*.url、宣传页、样片、预告)会和正片一起下载;同一部作品还会被多个发布站各下一份。 本 skill 负责下载完成后的离线清理,与主程序互不依赖。

硬性流程(必须遵守)

  1. 先预演:--quiet 看汇总,--manifest 导出完整清单。绝不直接 --apply。
  2. 把清单给用户看:报数量、体积、分段行号,并把"可能误伤"的类别单独列出来 (小体积视频、通用封面、会被整体清空的影片级目录)。
  3. 拿到明确确认后才执行 --apply。删除不可逆,这是硬边界。
  4. 执行后复核:文件数是否等于预演的"保留"数、垃圾是否清零、再跑一次预演是否 0 删除。
  5. 不要用 df 宣称"释放了空间"(原因见下文"磁盘空间")。

脚本

clean_seed_extras.py(仓库根目录,仅依赖 loguru)。

cd <repo>                                   # 例如 ~/Documents/myProject/lookingWeb
.venv/bin/python clean_seed_extras.py --quiet --manifest clean_manifest.txt   # 预演 + 导出清单
.venv/bin/python clean_seed_extras.py --apply --quiet                        # 确认后执行
参数 作用
--root PATH 目标目录,默认 /mnt/fnOS/123/
--min-size-mb N "大视频"阈值,默认 100
--apply 真正删除;不加则只预演
--manifest PATH 导出待删清单(文件 + 空目录)
--list-all / --list-limit N 预演时是否列出全部待删项
--no-subtitles 连字幕一起删
--no-posters 不保留任何图片
--no-covers 不保留 folder.jpg 等通用封面(只留同名海报)
--no-dedupe 关闭重复视频去重
--dup-check-bytes N 重复校验头/尾各读多少字节,默认 4MB
--prefer-source a,b 优先保留的站点前缀
--keep-empty-dirs 不删空目录
--skip-recent-min N 跳过最近 N 分钟内改动过的文件(防误删在下的)
--quiet 只输出统计,不逐条列文件

保留 / 删除规则

保留(命中任一):

  1. 视频:扩展名在 VIDEO_EXTS 内(mp4/mkv/avi/wmv/ts/m2ts/rmvb/iso…共 40+ 种) 且体积 >= --min-size-mb;扩展名未知或无扩展名时读文件头嗅探 (ftyp / EBML / RIFF-AVI / FLV / ASF / MPEG-PS / TS 双同步字节 / RMF)。
  2. 字幕:文件名含 .srt/.ass/.ssa/.vtt/.sub/.idx/.sup/.smi 等, 含 xxx.CN.srt.old-<日期> 这类备份。
  3. 海报:图片扩展名,且文件名包含同目录下某个已保留视频的文件名主干。
  4. 通用封面:folder.jpg / poster.jpg / cover.jpg / backdrop.jpg / fanart.jpg 等媒体库约定名(Jellyfin/Emby/Kodi 当封面用),且同目录下确实还有保留的视频 (目录里没视频时封面算无主垃圾,一并删)。

删除:其余全部;外加同目录内内容相同的大视频只保留一份。 删除完成后自底向上级联清空目录:子目录先删,父目录变空后继续向上删, 可一路删到影片级目录,但不删 --root 本身。 不跟随符号链接目录;删符号链接只删链接本身。

重复视频去重

同一部作品被多个发布站各下一份时,文件名只差站点前缀,例如:

masex.tv@vrkm01874_1_8k.mp4     ← 保留
hkbisi.com@vrkm01874_1_8k.mp4   ← 删除(体积与头尾指纹完全一致)
  • 先按「同目录 + 同体积」分组(几乎不耗 IO),再对每组算 sha256(体积 + 头 4MB + 尾 4MB) 确认内容一致。体积相同但内容不同的不会误删。
  • 不做全量哈希:740 个视频约 3.5TB,读全量不现实。
  • 保留哪一份依次比较:无站点前缀 > --prefer-source 指定站点 > 同目录内该前缀出现次数更多(保持目录内命名一致)> 文件名短 > 字典序。
  • 实测站点前缀:masex.tv@、4k2.com@、4k2.me@、hkbisi.com@、twojav.com@、489155.com@。

代码维护注意(改 decide() 时)

处理顺序必须是:① 标记达阈值视频 → ② 去重 → ③ 字幕/海报/封面匹配。

去重必须排在海报匹配之前:否则"被删副本的同名海报"要等到下一轮才被清掉,脚本就不是一次收敛 (历史上踩过这个坑,测试 test_去重后副本的同名海报一并删除 会断言"再跑一次无事可做")。 另外第 ③ 轮的入口是 if entry.keep or entry.reason: continue——reason 非空表示已定案 (保留或已判为重复视频),不能被覆盖成"待删除"。

改完必须同步:tests/test_clean_seed_extras.py(离线用例)与 tests/README.md。

.venv/bin/python -m pytest tests/test_clean_seed_extras.py -v

执行后的复核清单

cd /mnt/fnOS/123
find . -type f | wc -l                       # 应等于预演的"保留"数
find . -type f -size +100M -name '*.mp4' -printf '%h\t%s\n' | sort | uniq -d | wc -l   # 应为 0 组
find . -name '*.url' | wc -l                 # 应为 0
find . -type d -name '.pad' | wc -l          # 应为 0
find . -type d -name '*.trickplay' | wc -l   # 应为 0
.venv/bin/python <repo>/clean_seed_extras.py --quiet   # 再跑一次应为"删除: 0"(幂等)

Transmission 收尾(每次清理后都要看一眼)

清理会让 Transmission 里的任务缺文件:被清掉的样片/预告 → 部分缺失; 被去重删掉的那一侧副本 → 该任务数据全部不在磁盘上。

先用只读脚本盘点(scripts/find_missing_torrents.py,自包含,只用 requests,不修改任何东西):

.venv/bin/python .agents/skills/torrent-download-cleanup/scripts/find_missing_torrents.py
.venv/bin/python .../find_missing_torrents.py --json     # 机器可读输出
.venv/bin/python .../find_missing_torrents.py --host 192.168.123.199 --port 9095

输出里标 ! 的任务仍在活动状态(会空转/报错),最值得处理。

注意:Transmission 的 downloadDir 是 NAS 侧路径(实测为 /downloads), 在客户端命名空间里不存在,所以不能用 os.path.join(downloadDir, f["name"]) 判断存在性—— 那样会把所有任务误报为"全部缺失"。必须按文件名 basename 与本机目录比对。

要把这些任务从 Transmission 移除时(torrent-remove,只删任务记录不删数据), 必须先列出清单(id / 名称 / 状态 / 缺失文件数)给用户确认,不要自行决定。

磁盘空间:不要用 df 下结论

/mnt/fnOS/123 是 CIFS 挂载(//192.168.123.199/123),它报告的容量是缓存的: 实测写入 256MB 并 sync 后 df 读数一位都没变,间隔 20 秒的两次读数也完全相同。 所以 df 既不能证明"空间已释放",也不能证明"没释放"。 释放空间请让用户到 fnOS 存储空间页面确认;若那边也没降,考虑快照或回收站占用。

背景数据(2026-10-18 首次完整清理)

  • 清理前 4540 个文件 → 清理后 3021 个(视频 701 / 字幕 1658 / 海报 624 / 通用封面 38),目录 276。
  • 累计删除 1519 个文件 ≈ 226.7 GB:1441 个垃圾(2.9GB)+ 39 个重复大视频(223.8GB)
    • 39 个孤儿海报(26.8MB);另删除 751 个空目录。
  • 站点常见垃圾:*.url(广告)、twojav.com@* 等前缀的样片/预告、 .pad/(BT BEP47 填充文件,全 0 字节)、*.trickplay/(Jellyfin 缩略图)。
  • 预告片特征:同一支 19.3MB 的 三 上 悠 亚 想 要 跟 你 决 胜 负.mp4 在 80+ 个目录重复。